Bricolage Configuration Directives
by David Wheeler
|
Pages: 1, 2, 3, 4
Alert Configuration
Bricolage has an interface for sending alert emails when it logs events that meet certain criteria against objects. Bricolage needs to know a few things before it can send the alerts.
SMTP_SERVER-
Bricolage uses an SMTP server to send alert email messages. The default value for this directive,
localhost
, is fine if you use a Unix system with sendmail (or some other SMTP server) running locally. If your organization has a dedicated SMTP server or if your Bricolage host has none of its own, change the value of this directive. ALERT_FROM-
Set this directive to an email address that you want to appear in the
From
header of alert emails. I typically set it to something likeBricolage Admin <www@example.com>
, but use whatever is appropriate for your organization. If your users are inclined to reply to alert emails, you may want to set up a specialALERT_FROMemail address that has an auto-responder to let the user know that the reply will go unread. ALERT_TO_METH-
This string directive indicates which header to use for specifying alert recipients in email alerts. The possible values are
To
andBcc
.
User Interface Configuration
Some configuration directives enable you to affect how the Bricolage user interface works in subtle ways. If you haven't used the Bricolage browser-based interface much yet, some of these won't make much sense just now. Feel free to come back and look again when you're you've had some experience with the Bricolage interface and want to make it behave more according to your own notions of correctness.
FULL_SEARCH-
By default, when you search for objects in the Bricolage admin interfaces, or for stories, media, or templates in the asset library, the Bricolage UI appends a wildcard character to the end of your search string. Thus if you search for
foo
, the search will return results for all records that start withfoo
. If, however, you set theFULL_SEARCHBoolean directive to a true value, all searches in the Bricolage UI will become substring searches. So a search forfoo
will return all records wherefoo
appears anywhere in a record.The downside to this approach is that it prevents PostgreSQL from using its database indexes. In principal, this is only a problem if you have a large number of objects in Bricolage. If, say, you had 100,000 stories in Bricolage, you would notice that story searches would be noticeably slower with
FULL_SEARCHenabled than with it disabled. Leave it disabled if you expect to manage a lot of documents. Your users can always manually prepend the wildcard character (%
) to the front of search queries if they want a substring search. ALLOW_WORKFLOW_TRANSFER-
Bricolage workflows are made up of a series of desks. In general, workflows have their own desks, but desks can appear in more than one workflow. In such a case, documents moved to such a shared desk in one workflow will be visible on the same desk in another workflow. This is great for managing common tasks across workflows, such as translation or legal review. The upshot is that, by default, a document placed on a desk in one workflow cannot be transferred from that desk to another desk in a different workflow. Users can only move it to other desks in the workflow in which it originated. Set the
ALLOW_WORKFLOW_TRANSFERBoolean directive to a true value to remove this constraint, so that a document placed on a desk in one workflow can be moved from that desk to other desks in other workflows that the desk is in. ALLOW_ALL_SITES_CX-
When managing multiple sites in Bricolage, the user interface will display a
site context
select list. Only the workflows for the selected site will be displayed. If you want to allow users to see all of the workflows for all of the sites that they have permission to access, set this Boolean directive to a true value to add anAll Sites
option to theSite context
select list. But beware! If you have access to a lot of sites, you'll have access to a bewildering number of workflows when you select this option! YEAR_SPAN_BEFOREYEAR_SPAN_AFTER-
For the input of dates in Bricolage, the user interface offers select lists for the day, month, and year. By default, the years available in the
Year
select list have a limit of the ten years before and after the value for the year or the current year. If you need more years in your select list, set these directives to the number of years before and after the current value or current year. For example, if you manage a site of historical photographs with Bricolage, you might need to select years that range back over 100 years. In such a case, setYEAR_SPAN_BEFOREto100
. A science fiction book review site, on the other hand, might need years much farther in the future. For such a case, setYEAR_SPAN_AFTERto the appropriately high number. DEFAULT_FILENAMEDEFAULT_FILE_EXT-
The file names generated for story documents are set on a per-output channel basis. The user interface offers default values for these settings in the output channel profile. The default file name is
index
, and the default file name suffix ishtml
. If, say, you were outputing content to an IIS server, you might want to set theDEFAULT_FILENAMEdirective todefault
and theDEFAULT_FILE_EXTdirective tohtm
, instead. It's not a big deal either way, though, because you can actually set the values you need for each output in the user interface. These are just the displayed defaults, settable as directives for the ultimate in laziness. ENABLE_OC_ASSET_ASSOCIATION-
Document models are associated with output channels in Bricolage. When you create a new document based on a model, it will automatically have the output channel associations defined by the model. If you'd like users to be able to change the associations—say, to assign output channels defined by the model to be optionally associated with documents based on that model—set this directive to a true value. If, however, the added complexity of output channel associations will only confuse your users, set this directive to a false value to remove the user interface for changing document output channel associations.
ENABLE_CATEGORY_BROWSER-
When editing a story document in Bricolage, you'll see a select list of all categories that you have READ permission to access to allow you to optionally add the story to a new category. Most of the time, however, you'll only add a story to one or two categories, and then never change these settings. Therefore, if you have a lot of categories in your Bricolage installation (and there are systems in production with over 2000 categories), it's wasteful to load them all every time you edit a story document when you'll never change them again.
In such a case, set the Boolean
ENABLE_CATEGORY_BROWSERdirective to a true value and restart Bricolage. This will change the story profile to offer a link to a category browser, which enables you to search for the category or categories to associate with a story. Now, not only will you no longer load all categories every time you access the story profile (and the story profile is, for content producers, the most commonly accessed page in the Bricolage UI), but you'll only load those you search for in the category browser. I highly recommend that every Bricolage admin to set this directive to a true value.
Document Management Configuration
These directives relate to how Bricolage manages documents.
PUBLISH_RELATED_ASSETS-
Bricolage allows you to create relationships between documents. These can point to
related stories
or add images to a document, among other things. By default, when you publish a document, Bricolage will also try to publish any related documents. This will help to prevent 404s or broken image problems. In some cases, you might not want this behavior, so set thePUBLISH_RELATED_ASSETSBoolean directive to a false value. STORY_URI_WITH_FILENAME-
Story documents in Bricolage must have unique URIs. URIs consist of a story's category and optionally other parts of the story, such as its cover date and its slug (a one-word description of a story). They do not, however, consist of the file name. This is in keeping with W3C suggestions. The idea is that the story has a directory URI, and there may be several forms of the story with different file names in that directory, such as
index.html
for HTML,rdf.xml
for RDF, andindex.pdf
for PDFs.However, some organizations have Website policies that demand the inclusion of file names in the URI. This is so that different documents can be in the same directory. A common example might be a
About Us
directory with separate/about/index.html
,/about/contact.html
, and/about/copyright.html
documents. Such URIs are not possible by default in Bricolage, which requires that all stories have unique URIs, because each of these stories would have the same URI, namely/about
. To get around this issue, set theSTORY_URI_WITH_FILENAMEBoolean directive to a true value. From then on, all stories will include their file names in their URIs. Be careful, though! Existing stories will not have their URIs changed. Decide how you want to set this directive when you start using Bricolage, and never change it. ALLOW_SLUGLESS_NONFIXED-
The URIs for story documents are determined by patterns specified on a per-output channel basis. There are two different URI formats in each output channel, one for fixed documents and one for non-fixed documents. Non-fixed documents typically use parts of the cover date in their URIs, while fixed URIs do not. Each document model has a flag set to indicate whether documents based on the model will use the fixed for non-fixed URI patterns. The result is that, for non-fixed stories, you might have URIs like
/reviews/books/2004/12/23/princess_bride
. Here the URI format includes the slug, a one-word summary of the contents of a story (theprincess_bride
part of this example). However, slugs are optional in stories, even non-fixed stories. If you want to force all non-fixed stories to include the slug in order to guarantee the creation of more meaningful URIs, set this Boolean directive to a true value. AUTOGENERATE_SLUG-
This Boolean directive complements the
ALLOW_SLUGLESS_NONFIXEDdirective. If you want to keep the slug optional but generate one when a user neglects to type one in, setAUTOGENERATE_SLUGto a true value. This will cause Bricolage to generate a simple slug based on the title of the story. For example, a story with the titleEssential Perl 6
would have the slugessential_perl_6
generated for it.
Apache::SizeLimit Configuration
Bricolage is a large application that includes many CPAN modules as well as
its own 120,000+ lines of code. When you start it up, its processes can take up
30MB of memory or more. In general this isn't a problem, because Apache shares
that memory between child processes. As each process handles requests, however,
its size can swell independent of other processes. If you're performing
resource intensive activities, such as publishing a lot of documents at once,
the process that handles the request can become quite large. Because Perl (and,
by extension, mod_perl) does not return memory to the system, this
can give the appearance that you have a memory leak.
The solution to this problem is to use the Apache::SizeLimit module distributed with
mod_perl to check your mod_perl processes
periodically and kill them when they exceed a certain size. Bricolage has
integrated support for Apache::SizeLimit that these directives can quickly
enable and configure.
CHECK_PROCESS_SIZE-
This Boolean directive turns on the Apache::SizeLimit support. After you set it to a true value and restart Bricolage, it will use the settings in the following directives to decide how often to check your processes and to kill them when they get to be too big.
MAX_PROCESS_SIZE-
This is the maximum size, in bytes, that processes can reach before Apache::SizeLimit will kill them.
CHECK_FREQUENCY-
This directive determines how often Apache::SizeLimit will check the size of your
mod_perlprocesses. If you set it to5
, it will check a process after every fifth request handled by that process. The default is1
. MIN_SHARE_SIZE-
This directive indicates the minimum amount of shared memory the process must employ to avoid being considered a candidate for termination. Consult the Apache::SizeLimit documentation for more information. The default is
0
, meaning that all Apachemod_perlprocesses will have their sizes checked. MAX_UNSHARED_SIZE-
This directive sets a limit on the amount of unshared memory a process may consume to not be a candidate for termination. You can use this directive to tweak your settings if you find that Apache::SizeLimit terminates processes while they are still mainly using shared memory. The default is
0
.
