Bric::ElementAdmin - Bricolage Element Administration Guide.
$Revision: 1.16 $
$Date: 2003/03/07 16:38:12 $
This guide covers the art and science of Element Administration in Bricolage. It is geared toward users who will be responsible for determining the elements of stories and media, figuring out their relationships, and then creating and editing them in the Bricolage interface.
The core of Bricolage is asset editing. Most users will spend the vast majority of their time building and editing story assets, and to a lesser degree Media assets. (Template editing and management is covered in the Bric::Templates manpage and the Bric::AdvTemplates manpage and will not be addressed in this document.) How editors and media producers interact with Bricolage to build assets, however, is heavily dependent on how well thought-out and designed Element Administration has been. Elements are the building blocks of stories in Bricolage. Each story is based on a single Element that defines its story type, and Subelements of the story are available if they have been designated as available within the story type. In turn, each Subelement can have Subelements, and the depth of the Subelements can be arbitrarily deep.
Since by default there are only a few Elements available in Bricolage to get you started, it's important to think about how you'd like to use Bricolage within your organization and how your stories and media are constructed, and to come up with a design for your element hierarchy. This document will assist you in this task with the goal of helping you to create an element infrastructure that matches the needs of your organization while creating an intuitive and easy-to-use interface for your editors and producers.
Note: I shall be using stories in all of the examples below, but by and large the same concepts apply to media objects. The difference lies mainly in the likelihood that you'll use far fewer Subelements (if any) in your media objects.
Once you have become familiar with how Bricolage works, it's important to start thinking about how you plan to use it within your organization. Aspects that deserve some thought include Workflow and Desk design, Category Administration, Output Channel Administration, Contributor Type Administration, Destinations, and user groups and permissions. Each of these administrative functions are covered in separate documents [or will be, eventually!], but the most important bit to think about, from your users' point of view, is Element Administration.
The planning stage of element administration requires that you think about how stories in your environment are constructed. Here are some of the issues that need to be addressed:
Let's start with a couple of simple examples. Say that there are two basic types of stories on your site, covers (also known as index pages) and stories (which contain the bulk of the content).
Each cover on your site might have the following features:
Each story might have the following features:
Once we have identified the kinds of stories you will be creating, the next step is to build a hierarchy of parts based on our description of covers and stories. Think about the hierarchies in terms of two different types of parts: items that contain other parts, and items that contain data. These two types translate roughly into the Bricolage concepts of Elements and fields, and can be represented fairly well in an outline format. Here is an example of the hierarchies for the examples described above:
This hierarchical format nicely illustrates the construction of covers and stories, as the term is used above. Items in the outline that have sub-items are Elements, while items that have no sub-items are fields.
The exception to the last statement is relationships. While quite a few of the items listed in the above hierarchies are specific to a particular story (e.g., Title, Deck, Page, Paragraph, etc.), several are specific to other Bricolage objects. In the above examples, these are Image, Linked Story, and Byline.
In addition to stories, objects that users will frequently use are Media and contributors, and these can be linked to from a given story -- a relationship can be created. So starting with the cover page, we see that it consists mainly of links to stories. The upshot is that while most of the fields can be created for a particular Element (say, ``Top Story,'' which has the fields ``Image,'' ``Title,'' ``Teaser,'' and ``Byline''), the truth is that if a link is created to the top story, then all of those data fields will be available from the top story itself (provided they've been associated with the Story type!). Thus all you have to do is link to the story itself, not enter in all of those fields again!
Note: You may decide to include them, anyway, if you wanted, for example, to override the values in the story itself. Such an override would have to take place in the templates that format the story, however.
What this calls for, then, is a reorganization of the hierarchy of the Cover and Story story types. Because fields are in stories, they don't have to be included in the Element that links to them:
Note that virtually all of the fields are removed from the linked stories in both Cover and Story, because those fields are available from the linked stories themselves -- that is, they've been defined in the Story story type. Similarly, I've removed the Byline Element, because all stories can have any number of contributors associated with them, and custom fields can be created for contributor types (see [documentation forthcoming]). Clearly, the relationships offer powerful specialization. Just be sure that any fields that you require in related contexts are either included in the related item itself, or in a field specific to the related context. [I hope that last sentence wasn't as clear as mud!]
Given the above considerations, it's time to map out the Element Types, Elements, and fields that will need to be created. Fortunately, this is a logical step from what has already been done, with the exception of Element types. Element Types are basically groupings of Elements, where certain properties of all of the Elements of that type are set. Those properties are discussed below. For now, simply think of Element Types as a way to group related Elements. With our existing examples, there aren't too many related Elements, so we end up with a fair number of Element Types.
Here is the list of objects we'll need to create. The difference between this representation and that presented above is that some of the hierarchy is flattened out. We don't need to represent the hierarchy of Element relationships here because all we want is a list of all the Elements. So we list them instead by their Bricolage object types. Element Types come first, and Elements of each type are subsumed under their type. Fields are in turn indented under the Elements of which they are parts. We'll use this list in conjunction with the above list to actually create the Elements and Element Types in Bricolage.
Notice that I've left out the ``Title'' field of the ``Story'' Element. This is because all stories have a ``Title'' field by default in Bricolage. However, this hard-coded field has a character limit of 256 characters, so if you expect that you'll need titles longer than that, go ahead and include the Title field in your spec.
Also notice that we're missing information about contributors. This is because contributors are managed separately from story Elements. All stories can have contributors associated with them, regardless of their Element makeups. Thus all we'll need to do, once we've created our Elements and Element Types, is to make the associations when we're editing stories, and then, in the templates, grab the list of contributors and get their data to output onto the pages.
So now that we have our list of Elements, Element Types, and fields, let's create them!
The first thing we'll need to do is to edit or create a new Element Type to manage your cover story type. By default, Bricolage ships with the Element Type ``Covers,'' and this Element Type conveniently sets a number of properties required in the above scenario. Let's look at the ``Covers'' Element Type.
In the navigation bar, go to ADMIN -> PUBLISHING -> Element Types. In the list of Element Types, click the ``Edit'' link for the ``Covers'' entry. This brings up the Element Type Profile, where you'll find the name and description of the Element Type, and a list of its properties. You can fill in the name and the description however you like, but you need to be familiar with the other options:
Now the ``Stories'' Element Types is defined similarly to the ``Covers'' Element Type, but with a few differences in the properties. Taking a look at the default ``Stories'' Element Type -- which is configured fine for our purposes -- note the properties are set as follows:
The remaining Elements in our specification are all subelements -- that is, they're all associated with either a story or a cover, or with subelements of stories or covers. Thus, all remaining Element Types will be of the type ``Element.''
Moving through the list we created above, we see that the next Element Type is ``Columns.'' There is no such Element Type installed by default in Bricolage, so let's create one. In the navigation bar, go to ADMIN -> PUBLISHING -> Element Types. Click ``Add a New Element Type.'' This will bring up the first page of the Element Type Profile. Fill in the form fields as follows:
Then click the ``Next'' button. This will bring up the main Element Type profile page. Since column elements are not pages, fixed, or contain related stories or media, leave the remaining checkboxes unchecked.
Use this table to create the remaining Element Types:
Name Type Page Fixed Related Story Related Media -------------- ------- ---- ----- ------------- ------------- Nav Element No Yes No No Story Lists Element No No No No Linked Stories Element No No Yes No Ads Element No Yes No No Pages Element Yes No No No
Note that we've selected to allow the ``Linked Stories'' Element Type to relate to a story. Note also that we've selected to make the ``Nav'' and ``Ads'' Element Types ``Fixed.'' This is on the assumption that they contain content that doesn't necessarily change all that often. In fact, it may be that these Elements do little in Bricolage (they contain no fields or relationships), but rather give a cue to the formatting templates that they should insert SSI or Mason code to point to existing pages on your delivery systems. (Actually, the ``Fixed'' property is meaningless if an element is not also a ``Page'' or of the type ``Story'' or ``Media'', but it hurts nothing to set it as such in these examples, and serves as a reminder of their purpose.)
Now that we have set up all of the Element Types we need, it's time to create the real meat of this thing, the Elements. Now, because Subelements can only be added to Elements if the Subelements already exist as elements in the system, it works best to start at the bottom of the list and work our way up. That way we ensure that these dependencies are covered in advance.
Returning to our list, we find that the last Element listed is ``Page.'' In the navigation bar, go to ADMIN -> PUBLISHING -> Elements. Click ``[All] to see a list of all the Elements already defined in Bricolage. Here again you'll find a default Element that will do the trick: ''Page.`` Click the ''Edit`` link for this item.
It turns out that the default configuration for this Element is more complex than our plan calls for. It contains the Subelements ``Inset'' and ``Pull Quote.'' While we do need to add pull quotes to pages, we have ``Pull Quote'' specked out as a field, rather than as a subelement. Thus, the first thing we'll want to do is to remove these Subelements. Check the ``Delete'' checkboxes for both the ``Inset'' and ``Pull Quote'' Subelements.
Notice also that there are move fields than we need. While ``Paragraph'' is essential to our pages, neither ``Previous'' nor ``Next'' are needed by our specification. Check the ``Delete'' checkboxes for these two fields as well. Then scroll to the bottom of the profile and click the ``Save'' button. The offending Subelements and fields will be removed and we'll be returned to the Element Manager. Click the ``Edit'' link for the ``Page'' Element again to return to its profile.
Now, since a ``Paragraph'' field has already been included in the ``Page'' Element, all we need to do is to add a ``Pull Quote'' field. To do so, scroll down to the ``Add New Field'' section. Since a pull quote may be fairly long, let's create a text area input field. Select the radio button next to ``Text Area''. The input fields will change to the offer attributes relevant to a text area input field. Type the following values into their fields:
Click ``Add to Form'' and voila! We have the new ``Pull Quote'' field included in the ``Page'' Element. Now we just need to add a ``Subtitle'' field and we're on our way. Scroll down to the ``Add New Field'' section once again, and select the ``Text Box'' radio button. Fill in the relevant fields as follows:
Once again, click ``Add to Form'' to add the ``Subtitle'' field to the ``Page'' Element. Click ``Save'' to save the ``Page'' element and return to the Element Manager. The ``Page'' Element is now complete.
A ``Story'' Element is also installed by default with Bricolage, and we need merely alter it to suit our needs here. It's even already a ``Stories'' Element Type Element (imagine that!). Click ``Edit'' for the ``Story'' Element to get into its profile.
You'll note that this Element profile is different from the ``Page'' profile in that it has an ``Output Channels'' section. This is because all Elements whose Element Types are marked as ``Story'' or ``Media'' Element Types are used to define Story and Media assets, and such assets need to be specifically identified with certain Output Channels -- otherwise, they won't be distributed at all! So make sure that your ``Story'' Element is associated with the Output Channels you need to distribute it to.
Moving on to the next section, we see that two Subelements have been added to the ``Story'' Element. They are ``Page'' and ``Pull Quote''. Looking at our Element Specification above, we see that we do indeed need ``Page'' to be a Subelement of ``Story'', but not ``Pull Quote''. Select its ``Delete'' checkbox.
Returning to our Element specification, we find that we need a few more fields in our ``Story'' Element. While ``Deck'' is already included, we need to add ``Coverline'' and ``Teaser'' fields. Here are some recommendations for their specifications:
Click the ``Save'' button and the ``Story'' Element is ready to roll. We now have all the Elements and fields you need to build stories based on our spec.
No default Element corresponds to this Element, so we'll have to create it from Scratch. In the Element Manager, click the ``Add a New Element'' link. Fill in the name (``Advertisement'') and a description if you like.
Now, the ``Type'' select list is very important, as it determines what type of Element we're creating and we won't be able to change it later. Fortunately, it's fairly easy to determine which you're creating: they correspond directly to the Element Types we've already specified and created. Thus for the ``Advertisement'' Element we're creating, we want to select the ``Ads'' Element Type. Click the ``Next'' button to continue creating the ``Advertisement'' Element.
Now, because this is not a Story or Media Element, but just a plain Element (as defined in the ``Ads'' Element Type), there are no Output Channel associations. Furthermore, our specification above requires no subelements or fields for this Element. The idea is that it just gets added as a subelement of the ``Column Three'' Element, and requires no information from the story editor. Therefore, there's nothing more to do with this profile, so click the ``Save'' button to save it and return to the Element Manager.
Next up we have the ``Linked Story,'' ``Linked Story with Teaser,'' ``Top Story'', and ``Navigation'' Elements. Like the ``Ad'' Element, these contain no additional fields or subelements. Thus they can easily be created by following these criteria:
Name Description Type ------------------------ --------------------------- -------------- Linked Story A linked story. Linked Stories Linked Story with Teaser A linked story with teaser. Linked Stories Top Story The top story. Linked Stories Navigation Navigation element. Nav
The ``Current Stories'' and ``Recent Stories'' Elements inherit from the ``Story Lists'' Element Type. These, too, are simple, but each contain a Subelement. Create them as follows:
Name Type Subelements --------------- ----------- ------------------------ Current Stories Story Lists Linked Story with Teaser Recent Stories Story Lists Linked Story
This Element has no fields, but does contain subelements. Follow these steps to create it.
That's it. Once you have the basic subelements created with their own Subelements and fields, it's relatively easy to create the higher-up Elements that simply contain subelements and no fields. Here are the specs for the remaining column fields:
Name Type Subelements ------------ ------- ----------------------------- Column Two Columns Current Stories, Top Story Column Three Columns Recent Stories, Advertisement
And that's it! You're now ready to start editing stories using the Element structure we've created here. I suggest you do so, to get a feel for how the Element structure we've created here influences the interface for editing stories.
But the main point I hope to have highlighted here is how important it is to carefully analyze what you need for your site and content, and then figure out what Element Types, Elements, and fields you need before you ever create them. You might even find it useful to sketch out what you expect your site content to look like on your site and then use that sketch to decompose it into its basic parts.
David Wheeler <firstname.lastname@example.org>