Frequently asked questions

Evaluating Bricolage
Element Administration
- I added a field to an element and deleted it, and now I can’t add a new field with the same name. Why not?
- I created a new subelement element type but it does not appear in the list of elements for which I can choose to create a template. Where is it?
Templating
Errors
Miscellaneous

Evaluating Bricolage

Does Bricolage support databases other than PostgreSQL?

PostgreSQL supported and maintained for versions up to and including 1.10.5. Both PostreSQL and MySQL are supported in the Bricolage-Devel 1.11.0 release and will be included the in next production release of Bricolage, which is slated for summer 2008.

Are there any pre-compiled packages for Bricolage?

There is a FreeBSD port for most versions of Bricolage. To use it, simply update your ports tree, and then:

cd /usr/ports/www/bricolage
make
make install

There is also an experimental Debian package for Bricolage. To install it, add these lines to your /etc/apt/sources.list file:

# bricolage
deb http://tetsuo.geekhive.net/mark/debian/unstable /
deb-src http://tetsuo.geekhive.net/mark/debian/unstable /

Then do this (as root):

apt-get install bricolage-db
apt-get install bricolage

Then just point your Web browser to your local box on port 8080. This should work so long as you don’t have anything else running on port 8080.

Are there any Bricolage System that runs directly from CD?

You can run Bricolage directly from CD using the latest Bricolage VMware image, which is available on the Bricolage downloads page.

There is also a defunct project to make a KNOPPIX-style CD for Bricolage. Informally this CD is known as KNOPPIX with Bricolage. It is a CD that contains a Linux Distribution (Debian in this case) with Bricolage 1.6 preinstalled. The system is self-contained on a CD and the user merely needs to boot an i386-compatible computer from the CD. The CD will not in any way alter the content of your hard disk. This CD used to be useful for evaluating Bricolage since it removes the hassle of installation, but given that Bricolage 1.6 is years out of date, it’s no longer really useful.

How well does Bricolage perform?

As far as we know, no one has performed any benchmarks comparing Bricolage to other content management systems. But the performance of Bricolage is irrelevant to a public facing site. As a back office content management and publishing system, Bricolage does not host web sites or serve content. Rather, when documents are published in Bricolage, they are pushed through templates and the resulting files are distributed to your Web server. So if your Bricolage templates output static HTML, your public Web server should serve your content very fast indeed since performanc depends entirely on the scalability of your Web server.

All that said, the Sportsnet Bricolage installation had 70,000 stories in it as of June 1, 2008.

What are the advantages to using Bricolage?

There are a number of advantages to using Bricolage, including separation of content from presentation, multi-site management, and highly flexible Perl- and PHP-based templating. See the Benefits section of the site for more in-depth information.

Element Administration

I added a field to an element and deleted it, and now I can’t add a new field with the same name. Why not?

Fields cannot have the same name, even if they’ve been deleted. This is because you might have older stories around that use the old name, and still republish them to templates that use the old name.

The solution is to give the new version of the field a different name, but make the Label the same. So you might have a name like new_paragraph and the label Paragraph. Just remember to change any references to the old field name in your templates to use the new field name.

I created a new subelement element type but it does not appear in the list of elements for which I can choose to create a template. Where is it?

Did you add it as a subelement to a document element type, or as a subelement to any element type that’s part of a document element type hierarchy? If not, it won’t show up in the template select list. This behavior has to do with sites; only story and media element types are associated with sites, so to create a new template in a workflow (which is associated with a site), it looks for all the story and media element types associated with that site, and then adds all subelement types of those element types. So unless your new subelement type is associated with a story or media element, you won’t see it when you go to create a new template.

Templating

I added a template to a category and then deleted it, and now I can’t add a new template with the same name. Why not?

Deleted template profiles don’t actually get deleted but instead marked inactive in the database. This prevents creating a new template with the same name in them same category in the same output channel. Bricolage 1.10 and above offer to reactivate a deactivated template when you try to create it, but earlier users of Bricolage were out of luck.

If you’re not running Bricolage 1.10 or later, a deleted (that is, deactivated) template can be brought back by updating the database directly and querying against the output channel ID and the template’s file name:

psql -U [username] -d [databasename] -c \
  "UPDATE formatting SET active = 1 \
   WHERE  output_channel__id = [ocid] \
              AND file_name = '[path]'"

The arguments in brackets above are:

username: The username for your Bricolage PostgreSQL user. This is the username that Bricolage itself uses to connect to the PostgreSQL database, and which is listed as the DBI_USER bricolage.conf directive.
databasename: The name of the Bricolage database. This is the database that Bricolage itself users, and which is listed as the DB_NAME bricolage.conf directive.
ocid: The ID of the output channel that the template is in.
path: The full URI path name of the template. This is a combination of the category path and the name of the template, usually constructed from the element type for which it is created. For example, a Mason template created for the element type with the key name book_review in the category /reviews/books would be called /reviews/books/book_review.mc.

I get an compile error when I try to use $story or $element in a Mason template <%once> block. What gives?

To check the syntax of a Mason template as you develop it, Bricolage creates a Mason interpreter and compiles the template. Because <%once> blocks are designed to execute only once, Mason actually executes them during the compile. Of course, there is no $story or $element object when you’re editing a template, only when you’re publishing or previewing a story.

But since these objects are available in a <%once> block during a publish or preview, and as of Bricolage 1.6.14 and 1.8.0 the $burner object is always available, you can use the $story or $element object in a <%once> block like this:

<%once>;
unless ($burner->get_mode == SYNTAX_MODE) {
    # Do stuff with $story or $element.
}
</%once>

My templates are outputting binary data or converting output to a character set other than UTF-8, but the output is getting messed up. What gives?

You need to set the proper encoding for your output. All content in Bricoalge is UTF-8, and so that’s the default value that the burner uses to output files. If your templates are outputting something other than UTF-8, however, you need to tell the burner what you’re outputting. Use the set_encoding()method to do so:

$burner->set_encoding('iso-8859-1');

If you’re outputting binary data, set the output to raw:

$burner->set_encoding('raw');

Errors

If make cpan fails, what can I do?

Bricolage depends heavily on CPAN modules. The purpose of make cpan is to verify that the required CPAN modules exist and, if not, fetch and install them from CPAN, whenever possible. In the worst case where it cannot handle the an error automatically, it gives instruction on how to do it manually. Usually, the instruction tell you to:

perl -MCPAN -e shell
look package::module
perl Makefile.PL
make
make test
make install

where package::module is the name of the file to look for.

Sometimes, it will exit with a error without telling you what to do. Read the last few lines of the output. See which package::module caused the error. Then manually install the module using the procedure outlined above. If, when carrying out the procedures described above, make test fails, you might still want to go ahead with make install nonetheless. However, bear in mind that the module might not always function properly. After this, rerun make cpan.

Sometimes, make cpan reports that a CPAN module is not found. This could be because it is trying to get an older version of the CPAN module which CPAN no longer hosts because your CPAN index file is out-of-date and needs to be refreshed. To refresh your CPAN index file,

perl -MCPAN -e "reload index"

and repeat make cpan.

Sometimes you might need to update your CPAN bundle, itself:

perl -MCPAN -e "install Bundle::CPAN"

Why does make install exit with the error Missing or empty inst/bricolage.sql!?

You checked Bricolage out from Subversion and didn’t run make dist. Do something like this:

# make dist
[lots of output...]
# cd bricolage-1.10.2
# make install

Why does make install exit with the error Unable to set bricolage.conf variable APACHE_BIN to "/usr/local/apache/bin/httpd"?

Most likely it’s because you’re installing Bricolage on Red Hat 8 or later and haven’t gotten around to reading README.RedHat. In fact, a fair number of Perl modules will fail to install or test properly with Perl 5.8 on Red Hat 8. This is because Red Hat is configured such that it defaults to a Unicode character set. Bricolage prefers this, of course, since all Bricolage data is stored in the database is Unicode. However, it does require that you set the LANG environment variable on Red Hat 8, like this:

export LANG=en_US

From what we’ve heard, LANG must not include utf8. Presumably you should set LANG to a value for your local language. At any rate, you’ll need to make sure that this is set in your shell in order to install Bricolage and all of its modules, and you may need to include it in your httpd.conf file, as well:

PerlSetEnv LANG en_US

We’ve also heard that you can set the LANG environment variable globally in the /etc/sysconfig/i18n file. Then you wouldn’t need to worry about it anywhere else.

Why does make install exit with the error IDENT authentication failed for user "postgres"?

I’m not sure why the IDENT fails. In inst/db_grant.pl, we switch EUID to that of postgres. Maybe more things need to be set in order to convince PostgreSQL that you’re logging in as postgres instead of root?

You can work around the problem by ignoring it; in pg_hba.conf:

#local  all     all                                ident sameuser
#host   all     all     127.0.0.1    255.0.0.0     ident sameuser
local   all     all                                trust
host    all     all     127.0.0.1    255.0.0.0     trust
host    all     all     0.0.0.0      0.0.0.0       reject

A short introduction to pg_hba.conf can be found in Bric::DBA, and it is more thoroughly documented in the PostgreSQL manual.

Why do I get a 404 when I connect to the Bricolage UI and get an error like the following in Apache’s error_log?

[error] [client 127.0.0.1] Error executing AccessHandler: \
Bric::App::Session -- \
/usr/local/lib/perl5/site_perl/5.8.0/Bric/App/Session.pm -- 236
Difficulties tie'ing the session hash to file '/tmp/bricolage/session'

Most likely it is because one or more files or directories in your Bricolage temp directory are no longer writable by the Apache user. You need to chown the temp file directories and restart Bricolage (if nobody is your Apache user):

sudo chown -R nobody:nobody $BRICOLAGE_ROOT/tmp
sudo bric_apachectl restart

When I try to login to Bricolage, I get redirected to /login, but the page is blank. There’s nothing in the HTML source except <html><head></head></html> or nothing at all. There are no errors in the error log or the access log. What’s wrong?

We’ve seen this a couple of times, but the cause was different each time. On one occasion, there was a FilesMatch directive in a separate VirtualHost directive in httpd.conf that was preventing Mason from seeing any of the Bricolage UI components. The directive that caused the problem looked like this:

<FilesMatch "\.mas">
  SetHandler  perl-script
  PerlHandler Bric::App::Handler
</FilesMatch>

I have no idea why this would have caused a problem, but when it was removed, Bricolage started working again.

On another occasion, a user noticed that the files comp/login/dhandler and comp/login/welcome.html were empty. This caused the equivalent of a Document Contains No Data error, only it didn’t. When a document contains no data, a Mozilla setting can sometimes force the <html><head></head></html> to be added. The problem was fixed by reinstalling Bricolage (a make upgrade would probably do the trick, too), but it’s likely that simply copying these two files from the Bricolage source directories to your installed component root will correct the problem. Holler on the bricolage users mailing list if it doesn’t.

When I try to login to Bricolage, I get redirected to /login, but the web server reported a 500 Internal Server Error. What’s wrong?

Look in your Apache error_log file. If you find an error along the lines of

cannot login ...

Then you need to update your pg_hba.conf file as described in the section Why does make install exit with the following error? If you issue the following command on the command line:

/usr/local/pgsql/bin/pgsql -U bric bric

you will get

IDENT authentication failed for user &amp;quot;bric&amp;quot;

Thus demonstrating that you’re dealing with a PostgreSQL configuration issue, rather than a Bricolage issue.

I’m trying to restore a backup of the Bricolage database, but I keep getting an error like this: ERROR: Function login_avail(varchar, numeric, numeric) does not exist. What gives?

This is a known issue with PostgreSQL’s pg_dump utility—it’s not smart enough to handle circular dependencies. The PostgreSQL developers are aware of the issue. New features of PostgreSQL 7.3 and later allowed Bricolage to circumvent the entire problem. We recommend an upgrade to the latest stable release.

But if that’s not an option, the workaround is to edit your SQL dump file so that the Bricolage database will load properly. In your SQL dump file, search for and remove the line containing the string CONSTRAINT "ck_usr__login". This should remove the creation of the constraint that uses the login_avail() function before the function is created. Next, go to the very end of the SQL dump file and add these lines:

ALTER TABLE usr ADD CONSTRAINT ck_usr__login
CHECK (login_avail(LOWER(login), active, id));

This will add the constraint at the very end of the load, when both the usr table and the login_avail() function have been created. Now you should be able to load the database and get back to work!

Why do I get the error Can’t locate object method "" via package "HTML::Mason::Lexer"?

This is a bug in Perl. It is caused by the presence of Unicode in a Mason template, and dates from a period when Perl’s regular expressions had some difficulty with Unicode. It was fixed in Perl 5.8.1. Upgrade to the latest version of Perl and you should be good to go.

I keep clicking the Click here to start link on the very first Bricolage page I see, but it keeps just opening up a new window with Click here to start again. What gives?

I’m going to go out on a limb here and guess that you’re using Safari 1.1.1 or earlier on Mac OS X. Prior to the release of version 1.2, Safari had a JavaScript bug wherein it didn’t know the name of a window. The Click here to start link opens a new named window, but since Safari doesn’t know that it’s named, Bricolage’s JavaScript can’t tell that it’s named, either, and so keeps trying to get you to open a window with the correct name. It’ll never happen. We recommend that you upgrade to the latest version of Safari.

But if a Safari upgrade is out of the question, there are two ways to resolve this issue: First, don’t use Safari. This is the preferred solution, and since there are some other great Browsers for Mac OS X (notably Camino, Firefox, and Mozilla), it’s a real option for most Bricolage users. The second solution is to disable the named window by adding the undocumented configuration directive NO_TOOLBAR to your bricolage.conf file with a false value. The downside of this approach, however, is that all users of Bricolage will now be using Bricolage in a window with the back button, and this can potentially lead to problems with the state of story objects while you’re editing them. However, if you never use the back button, it should be fine.

Bricolage seems to be automatically changing my accented and other non-ASCII characters: when I enter element content with accented characters às become Ã¨s and similar things occur to other accented characters. What’s going on?

You need Perl 5.8.0 or later for Bricolage to properly handle non-ASCII characters. Also, The PostgreSQL database for Bricolage must use the UNICODE encoding. Please see Bric::Admin for further information on the recommended setup for letting Bricolage correctly handle non-ASCII content.

Why do accented and other non-ASCII characters look right in Bricolage’s internal preview, but not on my own preview server or my production server?

You need to make sure that your non-Bricolage server or virtual host knows that it’s serving content using the UTF-8 encoding. If you’re running an Apache server, just add this to your httpd.conf and restart:

AddDefaultCharset utf-8

Consult the documentation for your Web server for more information.

The Bricolage SOAP server segfaults when I try to use it. What gives?

Apache inadvertantly compiled the wrong expat XML parser into itself. Rebuild Apache, this time using the —disable-rule=EXPAT option.

Miscellaneous

What does Bricolage mean?

To quote the About Bricolage page when one clicks the Bricolage logo in the UI:

The name Bricolage was not drawn directly from the common usage of the term in French, but rather from the first chapter of The Savage Mind, by the famed French anthropologist Claude Lévi-Strauss. In that famous discussion of scientific thought vs. mythical thought—of science vs. the science of the concrete—Lévi-Strauss declares, Mythical thought is therefore a kind of intellectual bricolage.

Bricolage is the product of a bricoleur, a kind of handyman who assembles the fruits of his labors from the tools he has at hand. Similarly, mythical thought uses the extant concepts available to the cultural bricoleur to shape the world of cultural understanding. In other words, one’s understanding and interpretation of the world and its events derives from assembling new interpretations based on existing cultural (Lévi-Strauss would say structural) symbols. Signs allow and even require the interposing and incorporation of a certain amount of human culture into reality, Lévi-Strauss writes. Thus signs (or symbols, as modern anthropologists are more likely to call them) are the building blocks of cultural comprehension.

Similarly, content is assembled in the Bricolage content management system by drawing on extant element types to create a new end product. Element type administrators function as Lévi-Straussian scientists, in that they create new symbols (element types) that document editors—as new media bricoleurs—draw upon to assemble and manage new structures of meaning (content).

For those who may find this explanation too much a stretch, we fall back on the meaning of the term bricolage as it is commonly used in English, rather than French. For our French users, who might see the name and immediately think big hack, note that typical English definition, according to The American Heritage Dictionary of the English Language, Fourth Edition, is simply, something made or put together using whatever materials happen to be available. This definition nicely describes how Bricolage documents are built from the element types defined for them.

David Wheeler

Where can I get more information?

Read the README document in the directory where you unpacked Bricolage to learn about other documents on specific things like Bricolage administration, usage, or hacking. The project’s web site is http://www.bricolage.cc/. The web site contains online documentation and information about mailing lists.

I can’t get my head around the idea of workflow. Is there any documentation on it?

Not really, no. We’ll likely write some one of these days. in the meantime, you might find some use in this presentation given at the 2000 OSCON by Ian Kallen, in which he discussed what Salon needed out of a CMS (including workflow) and how he came to select the tools to use the CMS that was the proof-of-concept for Bricolage.

Why do searches return only objects with fields that start with my query string, rather than containing the query string anywhere in the field?

This behavior is intentional. The search interface goes directly into an SQL query, and thus supports SQL wild card characters. Unless you query for a string at the beginning of a column, any index on that column won’t be used. So we default to only searching at the beginning of a field in order to take advantage of the speed provided by an index.

However, you can get around this functionality in two ways. You can by put a % in front of your search string, thereby forcing the SQL query to be a full substring query. Or you can enable on the FULL_SEARCH bricolage.conf directive and restart Bricolage. But know that either of these methods will be a lot slower (though you probably won’t notice much until you have tens of thousnds of documents).

Why can’t I see all the stories I should see in Find Stories/Find Media/Find Templates ?

What is your Filter search results by site context preference set to? When this preference is set to On, Bricolage filters search results according to the Site context selected in the select list at the top right-hand corer of the Bricolage interface.

Does Bricolage have a memory leak?

No. Bricolage can use a lot of memory resources, especially if you publish a lot of documents at once, such as via the SOAP interface. Perl grabs the memory it needs, but it never releases it back to the operating system, although it will reuse it before asking the OS for more. So if you’ve published a lot of stories at once or done anything else to cause Bricolage to load a lot of data (such as used the search interface to get a list of all 10,000 stories in your Bricolage database), then the process that handled your request will become quite large and stay that way for its lifetime.

There are a number of ways to address this issue:

If you’re using bric_soap to execute big SOAP requests, use its —chunks option whenever possible to cut down on the amount of work any one request is doing.
Change your Apache configuration to get a better handle on your process sizes. Set MaxSpareServers and MinSpareServers to a reasonable numbers, and set MaxRequestsPerChild to limit the number of requests any one child handles. See the Apache documentation for more information on these and related directives.
Use Bricolage’s support for Apache::SizeLimit. This support is enabled via the CHECK_PROCESS_SIZE bricolage.conf directive, and you can tune it using the MAX_PROCESS_SIZE, CHECK_FREQUENCY, MIN_SHARE_SIZE, and MAX_UNSHARED_SIZE directives, as well. See Bric::Admin for details.
If you are using any character sets besides UTF-8, specify these character sets with the LOAD_CHAR_SETS directive. This will make sure that the character sets you are using are pre-loaded during server startup. This is especially important for large character sets like Big5 or Shift-JIS.
If you are using any languages besides en_us, specify these languages with the LOAD_LANGUAGES directive. This will make sure that the languages are pre-loaded during server startup. If you are using any time zones besides UTC, specify them the LOAD_TIME_ZONES directivE. This will make sure that the time zones are pre-loaded during server startup.

I accidentally deleted a category and now I can’t create it again. How do I get my category back?

As with stories, media, templates, element types, and most other objects in Bricolage, deleted categories don’t actually get deleted but instead marked inactive in the database. This is so that any documents or templates that currently exist and use the deleted category will continue to work. A deleted (that is, deactivated) category can be brought back by updating the database directly:

% psql -U [username] [databasename]
databasename=> SELECT id, site__id, asset_grp_id
databasename-> FROM   category
databasename-> WHERE  uri = '[category_uri]';
 id   | site__id | asset_grp_id 
------+----------+--------------
 1024       2222           3333
databasename-> 
databasename-> UPDATE category
databasename-> SET    active = 1
databasename-> WHERE  id = 1024;
UPDATE 1
databasename=> 
databasename=> UPDATE grp
databasename-> SET    active = 1
databasename-> WHERE  id = 3333;
UPDATE 1
databasename=% \q

The arguments in brackets above are:

username: The username for your Bricolage PostgreSQL user. This is the username that Bricolage itself uses to connect to the PostgreSQL database, and which is listed as the DBI_USER bricolage.conf directive.
databasename: The name of the Bricolage database. This is the database that Bricoalge itself uses, and which is listed as the DB_NAME bricolage.conf directive.
category_uri: The URI of the category you wish to re-activate. We select the site__id column, as well, because there might be other sites with the same category URI. If there are, be sure to select the category ID from the correct site; check the contents of the site table for the appropriate site.

What is the difference between URIs and and Fixed URIs? What is the relevance/standard use/importance of this feature in Bricolage 1.10?

The distinction between fixed URIs and non-fixed URIs is the result of an historical need for the difference at Salon, but it turns out to be pretty useful in the general sense. Prior to Bricolage 1.4 the two formats were not configurable, but locked down. The fact that they became configurable and that output channels could include other output channels has made the distinction basically unnecessary, but it’s still useful.

Think of it this way: A non-fixed URI is for a story that is tied to a particular date. At Salon and other magazines, this usually means an article published with a particular cover date. For example, the latest cover story in Vibe has this URI:

/news/cover_stories/2006/08/janet_jackson_forever_young/

That’s the original URI format, /%{categories}/%Y/%m/%d/%{slug}/, used in this case because the article was published on a specific (cover) date. This is a standard, meaningful URI: looking at it alone, you can be pretty sure what it contains.

Another page has this URI:

/news/cover_stories/

Note that it has no date in its URI; it’s the traditional (in Bricolage) Fixed URI format of /%{categories}/. We call it Fixed because it refers to a page that’s always relevant and doesn’t shift over time. Fixed perhaps insn’t a great word for it; a better word might be Cover. But the idea is that a fixed URI is for stories that are an important part of the hierarchy of a site, usually called Section Covers, Section Home Pages, Category Home Pages, or something similar. The Home Page on any site is the same thing: A story with the Fixed URI /.

Here’s another example. There are usually two different types of images on the typical site: Those used for navigation, banners, headers, footers, and whatnot (not to mention CSS), and those specific to a particular story. The first is fixed, because you always want it to be in the same place, where you can find it, such as /ui/img/banner.jpg. The latter should be non-fixed, because it’s specific to a particular date or story, such as /music/news/2006/06/outkast/group_photo.jpg.

Provide feedback

Saved searches