=head1 Name

Bric::ElementAdmin - Bricolage Element Administration Guide.

=head1 Version

$LastChangedRevision$

=head1 Date

$LastChangedDate: 2006-03-13 20:21:53 -0800 (Mon, 13 Mar 2006) $

=head1 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.

=head1 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
L<Bric::Templates|Bric::Templates> and
L<Bric::AdvTemplates|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.

B<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.

=head1 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:

=over

=item 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: B<covers>, which include content summarizing and pointing to
other stories, and B<stories>, which make up the bulk of the content for your
site.

=item 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.

=item 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.

=back

=head2 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).

=head3 Cover

Each cover on your site might have the following features:

=over

=item *

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

=item *

A single page.

=item *

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

=over

=item 1

Column one contains navigation to other sections of the site.

=item 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.

=item 3

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

=back

=back

=head3 Story

Each story might have the following features:

=over

=item * A title.

=item * A deck (A brief summary of what the story is about).

=item * A byline.

=item * A coverline.

=item * A main image.

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

=over

=item * A Subtitle.

=item * Multiple paragraphs of body copy.

=item * One or more pull quotes.

=back

=back

=head2 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 B<elements> and
B<fields>, and can be represented fairly well in an outline format. Here is an
example of the hierarchies for the examples described above:

=over

=item Cover

=over

=item Column One

=over

=item Navigation

=back

=item Column Two

=over

=item Top Story

=over

=item Image

=item Title

=item Teaser

=item Byline

=back

=item Current Stories

=over

=item Story

=over

=item Title

=item Teaser

=item Byline

=back

=back

=back

=item Column Three

=over

=item Recent Stories

=over

=item Story

=over

=item Title

=item Byline

=back

=back

=item Advertisement

=back

=back

=item Story

=over

=item Title

=item Deck

=item Byline

=over

=item Writer Name

=item Source

=back

=item Coverline

=item Main Image

=item Page

=over

=item Subtitle

=item Paragraph

=item Pull Quote

=back

=back

=back

This hierarchical format nicely illustrates the B<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.

=head2 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!

B<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:

=over

=item Cover

=over

=item Column One

=over

=item Navigation

=back

=item Column Two

=over

=item Top Story (Linked)

=item Current Stories

=over

=item Story (Linked)

=back

=back

=item Column Three

=over

=item Recent Stories

=over

=item Story (Linked)

=back

=item Advertisement

=back

=back

=item Story

=over

=item Title

=item Deck

=item Coverline

=item Main Image

=item Contributor (Linked)

=item Page

=over

=item Subtitle

=item Paragraph

=item Pull Quote

=back

=back

=back

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!]

=head2 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.

=over

=item Cover

=item Column One

=item Column Two

=item Column Three

=item Navigation

=item Current Stories

=item Recent Stories

=item Linked Story

=item Linked Story with Teaser

=item Top Story

=item Advertisement

=item Story

=over

=item Deck (single field)

=item Coverline (single field)

=item Teaser (single field)

=back

=item Page

=over

=item Paragraph (multiple field)

=item Pull Quote (multiple field)

=item Subtitle (single)

=back

=back

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.

=head1 Administration

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

=head2 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:

=over

=item 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.

=item 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.

=item Related Story

=item 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.

=item Type

There are only three types that are associated with Element Types: B<Story>,
B<Media>, and B<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
B<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.

=back

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

=head3 Page

Returning to our list, we find that the last element type listed is "Page." In
the navigation bar, go to ADMIN -E<gt> PUBLISHING -E<gt> 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:

=over

=item 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.

=item Label: Pull Quote

This is the label that will be displayed next to the field.

=item 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.

=item Rows: 4

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

=item 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.

=item 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.

=item 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).

=item 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.

=item 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.

=back

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:

=over

=item Key Name: subtitle

=item Label: Subtitle

=item Default Value: [Blank]

=item Size: 32

This option dictates how wide the field will be displayed in the element.

=item Maximum Size: 0

=item Position: 3

=item Required: Checked

All pages should have a subtitle.

=item Repeatable: No

Each page needs but one subtitle.

=back

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.

=head3 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:

=over

=item Coverline: Text Box

=over

=item Key Name: coverline

=item Label: Coverline

=item Default Value: [Your City]

If the coverline is likely to often be the same, you may indeed wish to include a
default value.

=item Size: 32

=item Maximum Size: 0

=item Position: 2

=item Required: Checked

=item Repeatable: Unchecked

=back

=item Teaser: Text Area

=over

=item Key Name: teaser

=item Label: Teaser

=item Default Value: [Blank]

=item Rows: 4

=item Max Size: 0

=item Columns 50

=item Position: 3

=item Required: Checked

=item Repeatable: Unchecked

=back

=back

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.

=head3 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.

=head3 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

=head3 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

=head3 Column One

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

=over

=item *

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

=item *

Key Name: column_one

=item *

Name: Column One

=item *

Description: A column.

=item *

Type: Subelement

=item *

Click the "Next" button.

=item *

Add the "Navigation" element as a Subelement.

=item *

Click the "Save" button.

=back

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

=head1 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!

=head1 Author

David Wheeler <david@kineticode.com>

=head1 See Also

L<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.

=cut
