Bricolage Templates

Using a content management system doesn't mean the pages on your Web site all have to look alike. Create a custom template for each section.
Modifying Templates

I'm going to assume you already have created and published at least one story on your system. If you're not sure how to create and publish a story, see my previous articles on Bricolage from the last few issues. Once you have published a story, it is sent to a particular output channel, either by copying a file on the filesystem or by using FTP to move it to a remote server.

The look and feel of your story is determined by the template. So, before we create our own simple templates, let's look at the basic examples that come with the system. Go to the Find Template link in the Template menu on the left side of the Bricolage administrator screen (user name is administrator, password is change me now!), and click on the Search button without entering anything into the text field. You should see a list of templates, one for each element type in the system (Figure 1).

Figure 1. Select the template you want to edit from the Find Templates page.

In many ways, Bricolage templates are like stories: they are created, edited and deployed at different desks; access to them is limited to certain users and groups; and Bricolage keeps track of changes (and avoids clashes) with a simple version-control system. Indeed, if you look at Figure 1, you can see that each template has a version number associated with it. Each can be checked out of the version-control system by clicking on the associated check box and then the Checkout button at the bottom of the page. Checked-out templates are available from the Active Templates link under the Templates menu.

In Bricolage, a story is only one type of publishable element. Further, each element may contain any number of additional elements. Bricolage comes with several predefined top-level elements, such as story, book review and column, plus several additional elements designed to be included in other elements, such as a pull quote.

If you think about a daily newspaper, you should realize that each section is styled differently, even for similar elements. For example, columns in the Metro section of the New York Times look different from columns in the Business section, which look different from the Op-ed page. That said, they are all columns. Bricolage resolves this problem by allowing you to assign a category to an element. So if you are writing a column for the Sports section, you indicate that it is part of the sports category. When Bricolage publishes the column to the Web, it looks for the /sports/ template. If it exists, Bricolage applies that specific template. If not, Bricolage looks for a template at the top (root) category. In other words, if you have a top-level template for an element, it serves as a fallback, or default, for all the elements of that type on the system. You can give some or all sections of your site a different look and feel by defining category-specific templates.

As you can see from Figure 2, I have checked out the / template, which is the top-level template for stories. Rather than having a view link, I have an edit link that allows me to modify the template. I also can edit the template by going to the active templates page, which provides me with a similar edit link. Open up the template for editing, which should give you a screen similar to Figure 2.

Figure 2. Editing a Checked-Out Template

Editing a template is similar to editing a story or any other element type, except that you are modifying the container into which the story will be inserted. If you insert only static HTML, every element looks identical. Thus, the trick is to use the predefined $story, $element and $burner objects to fill in the page with dynamic content. For example, here is the default / template:

<!-- Start "Story" -->

%# Only show this if we are on the first page
% unless ($burner->get_page     ) {
<h1><% $story->get_title %></h1>
<% $element->get_data('deck') %>
<hr />
% }

%# Display all the pages of this story
% $burner->display_pages('page');

Page <% $burner->get_page + 1 %>
<!-- End "Story" -->

As you can see, the above template is rather simple. An actual site might insert a drop-cap, set some styles in CSS or include some additional static text to identify the site. The basic version of / does the following:

  • It gets the current page number from $burner->get_page(). The page numbering begins at 0; however, we display the story's title and the element's deck if we are on the first page. The title comes from the $story object, with $story->get_title(), and the deck (an abstract) comes from the element itself. Notice how $element->get_data() is a fairly generic-looking method; we can use $element->it to retrieve any field from within an element.

  • We display the story by requesting it from the burner, using $burner->display_pages('page').

  • Finally, we use $burner->get_page() once again to show the page number at the bottom of the page.

What happens if we remove the page number and insert some static HTML of our own at the top or bottom of this template? Our changes then are reflected for all stories on the system. But it's important to remember that not all elements are stories, so changes that we make to / do not affect columns, book reviews or other element types.

When you are done editing /, you can click on the Check-In button at the bottom of the page. When you check a template in, you can send it to the development template desk (the default) or you can deploy it right away. This option is particularly useful if you discover a mistake on a template that is affecting the entire site; you can modify the template, deploy it and see the results immediately.

Finally, notice how / does not contain any <html> or <title> tags. That's because such items are implemented within the autohandler. The /autohandler template, which you can view, check out and edit from the Templates menu, is defined by default to be the following:

<!-- Start "autohandler" -->
        <title><% $story->get_title %></title>

    % $burner->chain_next;
<!-- End "autohandler" -->

The autohandler, which is global to the entire site, places the title of a story within the appropriate HTML <title> tags. It also incorporates the appropriate page contents into the template by invoking $burner->chain_next().

If you want to include a global CSS stylesheet, add a standard menu to the top of each page or put your company's logo at the top of each page on the site, this autohandler is the place to do it. And because autohandlers nest, you can have a global autohandler for your overall site, with section-specific autohandlers in each category.



Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Re: Bricolage Templates

Anonymous's picture

in version 1.8.1 you now need to make a little forward slash in the "fsearch" feild after you click "find template"- in order to indicate you are looking for the first level. A blank feild no longer works.

Geek Guide
The DevOps Toolbox

Tools and Technologies for Scale and Reliability
by Linux Journal Editor Bill Childers

Get your free copy today

Sponsored by IBM

Upcoming Webinar
8 Signs You're Beyond Cron

Scheduling Crontabs With an Enterprise Scheduler
11am CDT, April 29th
Moderated by Linux Journal Contributor Mike Diehl

Sign up now

Sponsored by Skybot