-
Notifications
You must be signed in to change notification settings - Fork 51
Definitions
All content in Bricolage is some sort of Story. Stories are to Bricolage as instances of a class are to Java (or any object-oriented language).
A Category in Bricolage can be thought of as a public directory on a web server. Bricolage starts off with just one category: the root category, which is modeled /. If a second category with a name of “test” was created, then that category would be modeled as /test/. Categories can be created within other categories or at the root level, just as directories can be created within other directories or at the root level. If a certain story is published in the “test” category, then that story will be accessible by a URL of the form “/test/slug.html” or “/test/slug/index.html.” Similarly, if a different story is published in the root (/) category, then that story will be accessible by a URL of the form “/slug.html” or “/slug/index.html.” Categories can also be aliases of other categories. Aliases function similar to sym links in UNIX.
Slug is a Bricolage field that goes along with a story. It is used to distinguish separate stories that occur in the same category. Slug is used to either define a sub-category or to define a filename (see the description above).
Element Types are schemas that define the makeup of a story. Element types are to Bricolage as classes are to Java (or any other object-oriented page). Element types are made up of two different building blocks: plain fields and sub elements (both defined below).
Plain Fields are input fields such as textboxes, radio buttons, and drop downs.
Sub Elements are made up of other sub elements and plain fields. The most basic example of a sub element is a link. A link is made up of two different plain fields: an URL and a name. Sub elements can also contain other sub elements. For example, if we have a sub element that represents a given object A, then A can contain sub elements of type A or some other type, B. Other example sub elements are bullet lists, headings, page titles, etc.
Related Stories in Bricolage allow a contributor to reference other stories. This is the only way within Bricolage to related one story to another outside of templating APIs, which will be covered later. Related stories are defined at the element type level. If an element type allows for related stories, then the contributor can include a single related story in the story that they’re authoring.
Related Media in Bricolage is a way to include media such as images or videos within a story. In practice, related media is usually attached to a sub element type. For example, one might define a sub element “image,” that has a caption, alt text, and a related media (the actual image).
A Template in Bricolage is a Mason (Perl) file that pays attention to a given element type and generates output (for example HTML, XML, JSON, etc) for stories of that element type. Templates only correspond to a single element type. Moreover, if stories of the same element type are being produced in different categories, then an individual template needs to be in place in each category.
Template changing is best explained through an example:
Suppose we have an element type “sample” and a category “/test.” The simplest way to associate a template is to create an element template in the /test category, which will be called sample.mc. Element templates are templates that are directly correlated to element types, which is why the name of the file is the name of the element type. In this simple example, Bricolage will use the sample.mc file in the /test category. Suppose that the template engineer did not create an element template in /test but instead created the template in / (/sample.mc). This scenario will function the same way as the previous, because Bricolage first looks for an element template in the same category that a story is published to. If the category does not have an element type template that matches the element type, then the parent directory is searched. This recursive process repeats until an element template is found.
On top of element templates, there are also category templates. These are called autohandlers and are named “autohandler” within Bricolage. Autohandlers allow template engineers to share template code across all element types within a category or across all categories within a category. For example, if a template engineer defines an autohandler in root (/), then that autohandler can generate HTML for all elements within the root category and all elements in sub categories of root. This is especially useful when defining header and footer HTML, because it allows the template engineer to avoid copy-paste and multiple edits.
See slide 26 from David Wheeler’s Discover Bricolage
A Destination is a local directory on a server where all stories will be dumped once they’ve all been burned by the Mason templating engine. Destinations are accessible by FTP and through the local file system.
An Output Channel is a way to relate stories to destinations, where templates are bridges in between. For example, let’s suppose that there is one single destination called “Web.” Let’s also suppose that there is an element type “page” that contains one single plain field called “page_title.” An output channel can be defined to point all page stories through a HTML template, while another output channel can be defined to point all page stories through a JSON template. If two destinations are present, then output channels can be defined to work with either or both of the destinations. Output channels should not be confused with categories, though. They only have to do with the server that a story should go to and the template that should burn that story. They don’t have to do with URL structures. They also define the naming convention for files, which includes file extensions.
A Desk is a location in Bricolage were documents in draft can be stored. Desks are the makeups of a workflow and can be thought of as real desks. For example, a story will be created on one user’s desk, and once that story is finished, the story will be moved to the desk of the reviewer. The reviewer can then move the story to any other desk until finally the story is placed on the publish desk and published. Stories, templates, and related media are controller by desks.
Some stories will reference other stories. For example, if you are using Bricolage to manage press releases, then you will have a story for each press release and a story for the aggregate of all press releases. There are two ways to do this:
First: at an element type level using related stories
- very clunky in the Bricolage admin tool
- are limiting because only one story can be referenced at a time. This can be worked around, but makes it even more clunky.
- are editable by any editor at any time
Second: at a templating level, the Bricolage templating API is used.
- much more robust, because they allow the data being referenced to be in any category and of any quantity.
- Read more here: http://bricolage.cc/docs/current/api/Bric/Biz/Asset/Business/Story.html
Keywords in Bricolage are used to help users find stories that are already published. They are not used at all when a story is published.