Document Modeling with Bricolage
by David Wheeler |

Categories

There is one final topic to discuss before you can create a story document based on the Article document type: categories. Categories are hierarchically organized content locations. Think of them as similar to a file system of directories (or folders, for you Mac fans out there). Indeed, categories in Bricolage are used in the URIs of story and media documents, so the translation is close (modulo date parts and slugs). They are also used to categorize content, so it makes sense to create category hierarchies that make sense for your site.

Figure 12. Create new categories starting with top-level categories added as subcategories to the root category, "/"

For example, if your site were a newspaper featuring movie and book reviews, you might want to create a category named Reviews as a subcategory of the root category ("/"), and then subcategories of the Reviews category named Books and Movies. The full URIs for these categories would be /reviews, /reviews/books, and /reviews/movies, respectively.

To create categories for your site, navigate to the Categories manager under ADMIN -> PUBLISHING and click "Add a New Category" for each category you wish to add. The root category already exists for each site, so start by creating your top-level categories and make your way down. See Figure 12 for an example creating a top-level Reviews category.

Figure 13. Navigate to the Story workflow and click New Story to create and edit a new story

Document Editing

Having created the categories you need, you can create a story document based on the Article story type. Open the Story workflow in the side navigation and select New Story (Figure 13) to bring up the New Story screen shown in Figure 14. Enter a title and slug. A slug is a very short hint (one or two words, separated by an underscore or dash) as to the contents of the story. Generally, the slug should complement the category selection rather than repeat it. For example, if you were creating a review of The Princess Bride in your /reviews/books category, you might make the slug "princess_bride." Select the Article story type, and cover date and click the Create button. This action creates a new story in the Story workflow and puts it on that workflow's "start desk," in this case the Edit desk.

Figure 14. Create a new story based on the Article story type. Be sure to enter a meaningful slug and cover date, and put the article in the relevant category

Figure 15. Add fields and elements to the story in the Content section of the story profile

The new story will then open in the story profile. The first section of the profile, Properties, mostly covers the same data points as the New Story screen. It's the second section, Content, that is most interesting (Figure 15). The bottom of this section has an Add Element button and a select list. From this list, you can select the fields or container subelements you'd like to add to the story. After adding a field, you can edit it, as with the Teaser and Long Teaser fields in Figure 15.

Notice that the names of the elements available in the Add Element select list is identical to the names of the container elements and fields associated with your modeled Article story type element. Because these are the only content containers that editors can add to a story, the structural integrity of the story strictly adheres to the model you created. The advantage is that the structure of the stories to be published to the site will be consistent across stories. This approach enables the maintenance of document standards and styles across a site, which can be very important in a large organization with thousands of pages of content to maintain. It also allows for simple yet extremely flexible templating, so that you can output documents in a variety of formats (XHTML, RSS, PDF, etc.) while maintaining identity and design standards.

Why are container elements and fields all listed together in one select list? Because as an editor works on a story, she doesn't need to think in great detail about what to add. It's unnatural for a writer to have to stop and think, "Do I want to add a container element or a field?" as she decides from which list to select. She only has to think, "I need to add a paragraph" or "I think a pull quote would work well here." The difference is important to us a document modelers and, later, as template developers, but for editors, the distinction is irrelevant.

Figure 16. Edit the fields of the Related Image subelement. Click the Edit button in the Related Media section to search for an image document to relate to this element

If you elect to add a subelement, say by selecting the Related Image option, you will then see the profile for that element. Figure 16 illustrates the Related Image element profile. Note how the required fields for this element (Title, Alt Text, Position, and Caption) are in the profile. Furthermore, because this is a related media element, there's an extra section called, curiously enough, Related Media. By clicking the Edit button, you can search your existing media documents to create a relationship, much as you searched for subelements to add to an element in the element manager. In Bricolage 1.10.0, you can also upload a media file directly in this interface, implicitly creating a media document in the same category and with the same cover date as the current story.

Click the Save button to save the element. Back in the main story profile, the new Related Image subelement will appear in the Content Section. You can re-order elements and fields by selecting new values from the Position select lists adjacent to each element. To edit a field, simply do so directly. To edit the Related Media subelement again, click its Edit button and you'll return to its profile.

Before finishing with this story, there's one more editing interface that's important to know. Adding individual fields to a story so as to keep their contents in independent records is all well and good, but the first time you tell an editor that she has to add each paragraph one at a time, duck. Just as an editor doesn't want to think about whether to add a container element or field to a story, she also doesn't want to have to go to a select list, click a button, and wait for a browser reload every time she wants to add a single paragraph.

Figure 17. Super Bulk Edit allows editors to use POD-like syntax to edit all of the fields in an element in a single textarea box

For this reason, Bricolage features two other interfaces for editing. The first, Bulk Edit, allows editors to edit all instances of a repeatable field in a single textarea. This is convenient if the majority of the content of a story is paragraphs, for example. The editor can simply write all the paragraphs she wants in a textarea box, separating each with a blank line. To use it, simply select the type of repeatable field to edit and click the Bulk Edit button to the right of the Add Element button and list.

Most documents are not simple lists of paragraphs though (if they were, you wouldn't need a tool as sophisticated as Bricolage). Instead, they're a mix of different blocks of content; the so-called Super Bulk Edit feature will likely prove to be more useful. To use it, select Super Bulk Edit from the Bulk Edit select list and then click the Bulk Edit button. Doing so will bring up the screen depicted in Figure 17. Here, you can edit all of the fields and subelements of the current element in a single textarea field. Each individual field or subelement has POD-like tags that start with an equal sign (=) and end with the key name of the element or field. The tags for subelements each exist on a line by themselves, while field tags identify the field to which the contents below them belong. You can even select a default element (say, Paragraph) from the Default Element select list, and then any blocks of text that have no POD tag will default to that element. This approach makes it easy for writers to edit all the different parts of an element without having to select, reload, and wait for every one. They can also create and reorder subelements, although they cannot change the contents of subelements themselves.

Click Save to return to the story profile, and the Save button there to save the story and return to My Workspace. Now you have created a story based on the article model. Go ahead, create as many more as you like.

Up Next: Templating

The next article will show how to write your first templates in Bricolage to format stories for output, so that you can actually see how your documents will look when they're published. Stay tuned!

Prev  [1] [2] [3] [4]