Bric::ElementAdmin(3p)User Contributed Perl DocumentatioBric::ElementAdmin(3p)



Name
       Bric::ElementAdmin - Bricolage Element Administration Guide.

Version
       $LastChangedRevision$

Date
       $LastChangedDate: 2006-03-14 05:21:53 +0100 (Tue, 14 Mar 2006) $

Description
       This guide covers the art and science of element type 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.

Introduction
       The core of Bricolage is document editing. Most users will spend the
       vast majority of their time building and editing stories and to a
       lesser degree, media documents. (Template editing and management is
       covered in Bric::Templates and Bric::AdvTemplates and will not be
       addressed in this document.) How editors and media producers interact
       with Bricolage to build documents, however, is heavily dependent on how
       well thought-out and designed the element types 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 element 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 types 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 in order 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 type 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 documents. The difference lies
       mainly in the likelihood that you'll use far fewer subelements (if any)
       in your media documents.

Planning
       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 type
       administration.

       The planning stage of element type administration requires that you
       think about how stories in your environment are constructed. Here are
       some of the issues that need to be addressed:

       Typology
           What kinds of stories do you have? Are there different types of
           stories for different parts of your site? For different sites
           managed from within Bricolage? At a minimum, you will likely want
           to consider using two different types of stories: covers, which
           include content summarizing and pointing to other stories, and
           stories, which make up the bulk of the content for your site.

       Construction
           For each type of story you define for your organization, think
           about what constitutes each story of that type. There are two
           aspects of this level of the design: elements available for each
           story, and fields within each of those elements. Elements are the
           building blocks of a story, while the fields in an element
           constitute an element's content.

       Relationships
           Individual elements can be associated with one story or with one
           media object.  These relationships are useful for creating links to
           other stories, and for displaying images within a story. Plus,
           stories can be associated with contributors--the people who provide
           their content.

   The Examples
       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).

       Cover

       Each cover on your site might have the following features:

       o   A Fixed URL that doesn't change and isn't linked to a date.

       o   A single page.

       o   Three columns of content. The columns are defined as follows:

           1.  Column one contains navigation to other sections of the site.

           2.  Column two features the title of the cover and link to the top
               story of the day (based on its title) with an image, teaser,
               and byline from that story, as well as links to other stories
               (with their titles, teasers, and bylines) that are related to
               the first.

           3.  Column three features a list of links to recent stories (with
               their bylines) on your site and a section containing
               advertising.

       Story

       Each story might have the following features:

       o   A title.

       o   A deck (A brief summary of what the story is about).

       o   A byline.

       o   A coverline.

       o   A main image.

       o   Multiple pages. Each individual page may contain, in addition to
           any of the above items:

           o   A Subtitle.

           o   Multiple paragraphs of body copy.

           o   One or more pull quotes.

   Establishing the Hierarchy
       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 content. 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:

       Cover
           Column One
               Navigation
           Column Two
               Top Story
                   Image
                   Title
                   Teaser
                   Byline
               Current Stories
                   Story
                       Title
                       Teaser
                       Byline
           Column Three
               Recent Stories
                   Story
                       Title
                       Byline
               Advertisement
       Story
           Title
           Deck
           Byline
               Writer Name
               Source
           Coverline
           Main Image
           Page
               Subtitle
               Paragraph
               Pull Quote

       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.

   Establishing Relationships
       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 type
       (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 element 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 be exploited 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:

       Cover
           Column One
               Navigation
           Column Two
               Top Story (Linked)
               Current Stories
                   Story (Linked)
           Column Three
               Recent Stories
                   Story (Linked)
               Advertisement
       Story
           Title
           Deck
           Coverline
           Main Image
           Contributor (Linked)
           Page
               Subtitle
               Paragraph
               Pull Quote

       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. 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 relating element. [I
       hope that last sentence wasn't as clear as mud!]

   Pulling it all Together
       Given the above considerations, it's time to map out the element types
       and fields that will need to be created. Fortunately, this is a logical
       step from what has already been done.

       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 element types and the fields they contain. We'll use this
       list in conjunction with the above list to actually create the elements
       types in Bricolage.

       Cover
       Column One
       Column Two
       Column Three
       Navigation
       Current Stories
       Recent Stories
       Linked Story
       Linked Story with Teaser
       Top Story
       Advertisement
       Story
           Deck (single field)
           Coverline (single field)
           Teaser (single field)
       Page
           Paragraph (multiple field)
           Pull Quote (multiple field)
           Subtitle (single)

       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 types. Thus all we'll need to do, once we've created our
       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.

Administration
       So now that we have our list of element types and fields, let's create
       them!

   Elements
       The first thing we'll need to do is to edit or create the Element
       Types, which are real meat of this thing. Now, because subelement types
       can only be added to element types if the subelement types already
       exist as element types 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.

       But first, there are a number of fields in the element type profile
       with which you should be familiar:

       Page
           This checkbox indicates whether elements of this Element Type
           represent pages or not. If an element is a page, then if you add
           more than one element of this type to a story, each one will
           trigger the generation of a new page -- that is, literally, a
           separate HTML page.

       Fixed
           This checkbox indicates whether the elements of this element type
           have fixed URIs. A Fixed URI is formatted according to the pattern
           specified for the "Fixed URI Format" of an output channel. In
           general, however, a fixed URI is one that is not associated with a
           cover date. Most stories will not be fixed URIs, as you'll want to
           associate them with a date.

       Related Story
       Related Media
           All elements in Bricolage can have one story and/or one media
           object associated with them. By checking one or both of these
           options, users who add an element of this element type will have
           the option to associate a single story and/or media object. The
           purpose of this feature is to allow links to be made between
           assets.  We'll cover more on this below.

       Type
           There are only three types that are associated with Element Types:
           Story, Media, and Subelement. A story element type is an element
           type whose elements define stories. A media element type is an
           element type whose element define Media documents. Most element
           types, however, will be of the type Subelement. These are elements
           that can be added to stories or media or other elements as
           subelements. The type of an element type can only be defined when
           it is created; it can never be changed, as the other options depend
           on this property.

       So let's see how our element types shape up.

       Page

       Returning to our list, we find that the last element type listed is
       "Page." In the navigation bar, go to ADMIN -> PUBLISHING -> Elements
       Types. Click "[All] to see a list of all the element types already
       defined in Bricolage.  Here you'll find a default element type that
       will do the trick: "Page." Click the "Edit" link for this item.

       Of the checkbox options at the top, the only one that should be checked
       is "Page", because, yes, we do want a Page element to represent a page
       in a story. And indeed, it should already be checked.

       It turns out that the default configuration for this element type is
       more complex than our plan calls for. It contains the subelement types
       "Inset" and "Pull Quote." While we do need to add pull quotes to pages,
       we have "Pull Quote" specified as a field, rather than as a subelement.
       Thus, the first thing we'll want to do is to remove these subelement
       types. Check the "Delete" checkboxes for both the "Inset" and "Pull
       Quote" subelement types.

       Notice also that there are more 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
       and Stay" button.  The checked subelement types and fields will be
       removed

       Now, since a "Paragraph" field has already been included in the "Page"
       element type, 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:

       Key Name: pull_quote
           This is the unique identifier for the field, within the Page
           element type, that will allow templates to get a handle on the
           field.

       Label: Pull Quote
           This is the label that will be displayed next to the field.

       Default Value: [Blank]
           If you wanted, you could place a default value in a field you
           create for Bricolage. Since pull quotes are specific to the story
           of which they're a part, however, we'll leave the "Default Value"
           field blank.

       Rows: 4
           This is the number of rows the text area field will take up.

       Columns: 40
           The number of columns wide (in characters) for the text area field.
           Most of the default text area boxes in Bricolage use a 40-character
           width.

       Max Size: 0
           The maximum number of characters that can be entered into the text
           area field.  Set this field to 0 (zero) to allow values of
           unlimited length.

       Position: 2
           You can specify a position field for the field in your form. This
           will only be used if a field is required, however (see below).

       Required: Unchecked
           If a field were required to be in an element, you could select this
           checkbox.  We don't need to require that all pages have a "Pull
           Quote" field, however, so we leave this option blank.

       Repeatable: Checked
           All fields can be placed in an element either once or more than
           once. That is, you can specify that a field appear in an element no
           more than once, or allow an unlimited number of instances of a
           field to appear. Since some pages may wish to use multiple pull
           quotes, go ahead and check this checkbox.

       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:

       Key Name: subtitle
       Label: Subtitle
       Default Value: [Blank]
       Size: 32
           This option dictates how wide the field will be displayed in the
           element.

       Maximum Size: 0
       Position: 3
       Required: Checked
           All pages should have a subtitle.

       Repeatable: No
           Each page needs but one subtitle.

       Once again, click "Add to Form" to add the "Subtitle" field to the
       "Page" element type. Click "Save" to save the "Page" element and return
       to the element type manager. The "Page" element type is now complete.

       Story

       A "Story" element type is also installed by default with Bricolage, and
       we need merely alter it to suit our needs here. Click "Edit" for the
       "Story" element type to get into its profile.

       None of the top checkboxes need to be checked, as a story should not be
       a page or have a related media document or related story. But note that
       its type is "Story," meaning that it is a story type element.

       You'll note that this element type is different from the "Page" element
       type in that it has an "Output Channels" section (or it would if there
       was more than one output channel--create one in the output channels
       manager to see it).  This is because all element types marked as
       "Story" or "Media" element types are used to define story and media
       documents, and such documents need to be specifically identified with
       certain output channels--otherwise, they won't be distributed at all!
       So make sure that your "Story" element type is associated with the
       output channels you need to publish it to.

       Furthermore, if you have configured Bricolage to manage multiple sites,
       the Story element type profile will also have a "Sites" section. The
       idea is that you can publish the same types of documents to different
       sites. So if you need to publish Story documents to multiple sites,
       make sure that you've added them all. The interface will also ensure
       that a primary output channel is associated with each site, as well.

       Moving on to the next section, we see that two subelement types have
       been added to the "Story" element type. They are "Page" and "Pull
       Quote." Looking at our Element type specification above, we see that we
       do indeed need "Page" to be a Subelement of "Story," but not "Pull
       Quote." Select its "Delete" checkbox and click "Save and Stay" to
       delete it.

       While we're looking at our element type specification, we find that we
       need a few more fields in our "Story" element type. While "Deck" is
       already included, we need to add "Coverline" and "Teaser" fields. Here
       are some recommendations for their specifications:

       Coverline: Text Box
           Key Name: coverline
           Label: Coverline
           Default Value: [Your City]
               If the coverline is likely to often be the same, you may indeed
               wish to include a default value.

           Size: 32
           Maximum Size: 0
           Position: 2
           Required: Checked
           Repeatable: Unchecked
       Teaser: Text Area
           Key Name: teaser
           Label: Teaser
           Default Value: [Blank]
           Rows: 4
           Max Size: 0
           Columns 50
           Position: 3
           Required: Checked
           Repeatable: Unchecked

       Click the "Save" button and the "Story" element type is ready to roll.
       We now have all the Elements and fields we need to build stories based
       on our spec.

       Advertisement

       No default element type corresponds to this element type, so we'll have
       to create it from scratch. In the element type manager, click the "Add
       a New Element Type" link. Fill in the name ("Advertisement") and a
       description if you like. Select "Subelement" for its type, as
       advertisements do not define story or media documents, but subelements
       of story documents. Click the "Next" button to continue creating the
       "Advertisement" element type.

       Now, because this is not a story or media element type, but just a
       plain subelement type, there are no output channel associations.
       Furthermore, our specification above requires no subelements or fields
       for this element type.  The idea is that it just gets added as a
       subelement of the "Column Three" element type, 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 type manager.

       Linked Story, Linked Story with Teaser, Top Story, and Navigation

       Next up we have the "Linked Story," "Linked Story with Teaser," "Top
       Story", and "Navigation" elements types. Like the "Advertisement"
       element type, these contain no additional fields or subelements. Thus
       they can easily be created by following these criteria:

         Name                      Key Name                  Type        Page  Fixed  Rel. Story  Rel. Media
         ------------------------  ------------------------  ----------  ----  -----  ----------  ----------
         Navigation                navigation                Subelement   No    Yes      No           No
         Linked Story              linked_story              Subelement   No    No       Yes          No
         Linked Story with Teaser  linked_story_with_teaser  Subelement   No    No       Yes          No
         Top Story                 top_story                 Subelement   No    No       Yes          No

       Current Stories and Recent Stories

       The "Current Stories" and "Recent Stories" element types are also
       simple, but each contains a subelement type. Create them as follows:

         Name             Key Name         Type        Page  Fixed  Rel. Story  Rel. Media  Subelements
         ---------------  ---------------  ----------  ----  -----  ----------  ----------  ------------------------
         Current Stories  current_stories  Subelement   No    No       Yes          No      Linked Story with Teaser
         Recent Stories   recent_stories   Subelement   No    No       No           No      Linked Story

       Column One

       This Element has no fields, but does contain subelements. Follow these
       steps to create it.

       o   Click "Add a New Element Type" in the element type manager.

       o   Key Name: column_one

       o   Name: Column One

       o   Description: A column.

       o   Type: Subelement

       o   Click the "Next" button.

       o   Add the "Navigation" element as a Subelement.

       o   Click the "Save" button.

       That's it. Once you have the basic subelement types created with their
       own subelement types and fields, it's relatively easy to create the
       higher-up element types that simply contain subelement types and no
       fields. Here are the specs for the remaining column element types:

         Key Name      Name          Type        Subelements
         ------------  ------------  -------     -----------------------------
         Column Two    column_two    Subelement  Current Stories, Top Story
         Column Three  column_three  Subelement  Recent Stories, Advertisement

Conclusion
       And that's it! You're now ready to start editing stories using the
       element models we've created here. I suggest you do so, to get a feel
       for how the element types we've created influence 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 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, er, elements.

       Good luck!

Author
       David Wheeler <david@kineticode.com>

See Also
       <http://www.bricolage.cc/about/doc_models/> contains graphical
       depictions of the document models used to create the Bricolage Website
       in a nice illustration of how to construct document models from element
       types and fields.



perl v5.12.2                      2006-03-13            Bric::ElementAdmin(3p)
