Bricolage Element System Redesign Functional Specification
This document describes the functional requirements for a revision to Bricolage's element system. These should be regarded as abstract functionality goals, independent of any particular implementation. For the implementation details, please consult the ElementRevision::TechnicalSpec.
Please note that this document is not meant as an attack on the 1.5.0 and earlier element system or its designers. Where we identify short-comings we are doing so only in order to explain why we believe change is warranted. The current system is one of Bricolage's strongest features and these changes should be viewed as evolutionary rather than revolutionary.
As of version 1.5.0, Bricolage's element system, in our understanding, consists of the following pieces:
In the element administration interface, elements have the following properties:
Element types can be marked as ``fixed'', ``page'', ``related story'' or ``related media''.
In no particular order, here are the changes we propose:
Bricolage's element system goes by many names. Here's a rough overview of the naming schemes in the system:
The API also refers to container and data elements as ``Asset Parts'', element types as ``Asset Types'' and element type types as ``Asset Type Types'' or ``ATTypes''. Also, remnants of an earlier naming system of ``tiles'' remain deep in the API.
Unifying the naming conventions around elements will have numerous benefits. Communication between users, administrators, and programmers will be easier with a common vocabulary. Also, new features will be easier to conceive if the system has a consistent internal model for elements.
We therefore propose that the following naming convention be adopted and used throughout the API, interface, and documentation:
In the current system, elements are controlled by a number of different constraints, such as whether they're repeatable and what types of data they contain. We propose that this system be extended in a number of ways.
In the current system, it is possible to mark a field as ``required''. This means that the field shows up automatically whenever that element is created and it cannot be deleted. Also supported is ``repeatable''. This option allows a field to be repeated any number of times.
We suggest that the system be extended to allow a generalized occurrence constraint, and that this constraint also be extended to apply to subelements. We propose to create two fields - ``Minimum Occurrence'' and ``Maximum Occurrence.'' Either can take numeric values (0, 1, 2 ...) or be empty (or zero) to specify no constraint. Example uses:
min: 0, max: null => equiv. to "repeatable".
min: 0, max: 1 => equiv. to normal case.
min: 1, max: 1 => equiv. to "required".
min: 1, max: null => equiv. to "required" and "repeatable".
min: 3, max: 10 => 3 created initially, 10 allowed
The implication of extending occurrence specification to subelements is that element trees can essentially be fully pre-populated. This should provide a significant enhancement to the Document profile when editing complex Document Types.
It should be possible to mark an element of either type as sortable or non-sortable when adding it as a subelement in an Element Definition. Non-sortable subelements would have their own area in the Document Profile where they could be handled separately from sortable Elements.
Currently the element administration system is heavily slanted toward interface-definition and provides few tools for data schema specification. Adding field data constraints would allow the Document profile to catch invalid data entry when the data is entered. Currently the only place to catch invalid data is in the template, which may be many steps down the workflow from the initial data entry.
We propose to create an extensible system of different field data types, each with constraints relevant to the type of data it contains. For example, we might offer a ``Number'' data type with the following constraints (among others):
And we might provide a ``Text'' data type with the following constraints (among others):
New field data types can contain whatever constraints they require, but all must be triggered either automatically or through a single interface.
Some possible field data types we might want to implement:
This section documents a range of other ways in which we propose that fields be revised and expanded.
In the current implementation, related stories and related media are implemented as a special type of Container Element. This is awkward in practice because it is unusual to add subelements to a related element. The result is an extra level of indirection for users since Container Elements require the user to access a separate edit screen. In the case where subelements are desired they can be added to the same container as the related element.
Creating a Related Object field element will result in a simpler interface for users as well as simpler element trees. Additionally, the interface for template developers can be simplified - related elements become simply a field element that contains an ID of the appropriate type. A convenience method, ``get_related_object()'', will provide a single interface for constructing and retrieving related objects. The existing special-case methods, ``get_related_media()'' and ``get_related_document()'', will become synonyms for backward compatibility (and should probably issue warnings).
As a separate interface, each different type of field (number, text, etc.) will provide a number of user interface widget options. For example, the ``Text'' data type may allow the data to be entered as a text field, a text area field, a check box, a select list, etc. A ``Number'' data type may allow different widget types. A ``Related Object'' data type, on the other hand, would likely allow only a select list of types to choose from, or a shopping-cart type widget to allow users to search for and select the object to relate.
But the point is that the type of data that can be entered and the interface through which it can be entered will be maintained as conceptually different concepts. This will enforce the separation of schema definition from UI building while providing much greater flexibility for defining field data types and methods of input.
Often it is desirable to be able to relate a list of objects to a Document. Building covers often boils down to this task. With related objects as field elements, it should be possible to allow such fields to use an interface that allows users to collect a group of objects quickly, up to the number allowed by the Max Occurrence property.
The model for the Related Bulk Edit will be the existing Contributors interface in the Story Profile. This is a shopping-cart model with a box at the top to collect selections and a search interface at the bottom.
One of the most problematic issues with the current editing system is that media must be uploaded first, through a separate interface, before they can be used in stories. By providing a media upload field in-line within a Document, users won't have to go two places to create a multimedia document. Furthermore, such a field can have a property limiting the media types that can be uploaded, for example, ``image/jpeg'', ``text/html'', etc.
Those who wish to continue to manage media assets as separate documents can create Document Types specifically to manage particular types of media files, and include a single upload field in that Document Type. Then, when a user wishes to create a relation to an instance of such a media document, they can use a Related Object field to find the document and link to it. Thus element administrators have the option of allowing media to be added directly to a document as fields in the document, or to have separate media Document Types so that important media assets can still be managed through workflow independent of the workflow of other types of documents.
The current ability of Media assets to auto-populate fields will be subsumed by properties of Media file subclasses. When a file is uploaded, Bricolage will detect the file's media type (for example, ``image/jpeg'') and construct an object of the appropriate subclass (for example, ``Media::Image''). That object will then detect and auto-populate the properties relevant to media files of that type (for example, ``width'' and ``height''). These will be first-class properties of the object, just as ``file size'' currently is. If users wish to have fields override those values, they should create the relevant fields for users to enter data into (for example, ``Override Width'').
Right now field elements can only be edited by deleting and recreating. To rectify this shortcoming, we suggest that a new ``Field Profile'' be added to Bricolage, to allow fields to be fully editable (with the exception of the ``key_name'' property).
In this section, we discuss features that we recommend be added to the behavior of Container Elements.
Like Field Elements, Container Elements should have display names that are
distinct from their unique names. In addition, unique names will now be known
as ``key_name'' rather than just name to make the distinction clearer. As a
result the existing has_name() method for fields and containers will be
deprecated since key_names can be safely compared directly.
A radio button will be included in the Element Definition profile to indicate which Field Element in that Element Definition may be used to provide more information about a Container Element in the Document Profile. For example, in a ``Page'' Container Element, someone may wish add a Field Element named ``Page Header'', and then check the radio button next to it. Then, while editing an element based on that Element Definition profile, instead of seeing this:
Page: [Edit] Page: [Edit] Page: [Edit] Page: [Edit]
The document editor might see this:
Page: "Lead-in to page one" [Edit] Page: "More on this page" [Edit] Page: "More and more, three" [Edit] Page: "And we wrap it up!" [Edit]
...Where the text displayed between the Container Element Label (``Page'') and the ``Edit'' button is from the first instance of the ``Page Header'' field in each ``Page'' element. This will make it easier for users to see which is which and thus decide which to edit, how to reorder, etc.
In this section, we address some of the issues that will be affected by the element revision.
Adding configurable documentation to elements will allow us to implement tool-tips and/or context-sensitive help for elements later. We might need ``short description'' and ``long description'' or a single field might suffice.
Since the current distinction between stories and media will be eliminated, so too will the need for separate workflows for the two different types of assets. A future revision of the Workflow design, however, may allow a workflow to limit the Document Types that can be managed in a given workflow. This functionality will allow administrators to determine what kinds of documents can be managed in what workflows, rather than that determination being imposed by the developers. This topic will be covered in a future Workflow Revision Functional Specification.
Burners should be assigned at the output-channel level. This is because it makes no sense to mix burners in the same output channel. Furthermore, output channels should only be able to include other output channels that use the same burner.
The current element and template set does not demonstrate our system well and the output it generates is rather ugly. Since we'll have to update them to work with the new element system, we should take the chance to do a little spring cleaning.
We should also see if we can find a way to ship Bricolage with a default set of templates for all supported burners, and not just Mason, although perhaps only the Mason templates will be installed by default.
The initial design is to have the element system work with documents. However, we should keep the design open-ended enough so that users can create element hierarchies for other kinds of objects, too. The objects most in need of such support for the addition of content elements are Contributors and Categories.
Once the support is in place, we can perhaps allow an Element Definition to be created for all Contributors and All Categories. Perhaps further down the line we can allow the creation of Contributor Types and Category Types, so that the meta data for a given contributor or category can correspond to a particular type.
But we see these additions as being further down the road. The upshot is to a) Allow Element Definitions to be applied to other types of objects; b) Later, allow a few other types of objects to have a single definition apply to all instances of those objects; and c) Still later, allow those different types of objects to have their own types.
One should be able to preview the current Document from any of its Subelements. This will greatly improve data-entry efficiency in nested Subelements. [Note: We can probably add this functionality to the current design quite simply, and we probably ought to.]
It should be possible to search by or limit the display of returned items to ``Cover'' or ``Story'' or ``Whatever'' Document Type. [Note: We can probably add this functionality to the current design quite simply, and we probably ought to.]
An ``Input Channel'' is a construction that allows users to input multiple kinds of content into the same Bricolage objects. This is intended primarily to allow one to enter content in multiple languages, although there may be other uses.
By default, a single input channel will be defined, in which case Bricolage will behave exactly as it always has, which is to say the user could safely ignore the Input Channel concept.
It will, however, be possible to configure multiple Input Channels, in much the same way as one can configure multiple Output Channels now. Also like Output Channels, a Document Type may have multiple potential Input Channels assigned to it, and a Document based on that Document Type can use Input Channels from that list as it sees fit and as is allowed by the Document Type.
Each Input Channel will have a key name and a display name (or Label). To define an Input Channel for French, for instance, a Bricolage setup might use the ISO 639 two letter language code as the name, and the actual name of the language as the display name.
If Input Channels other than default have been defined, there will be a new button widget along the top of the Document and Element profiles that will show the display name of the current Input Channel. Clicking on the button will allow the user to change the current Input Channel context. This could be done at any time during a given session. Content entered into any field will be flagged as belonging to the current Input Channel.
In the template space, the API will offer an interface for a template developer to set the Input Channel to be other than the primary Input Channel defined for the document:
$element->set_input_channel($input_channel_key_name);
All of the following calls within that template will then use that input channel.
$element->get_field_data($field_name, $order);
If the developer wants to switch input channels for a single access, however, an optional third argument may be supplied to the method call:
$element->get_field_data($field_name, $order,
$input_channel_key_name);
Input Channels may optionally include other Input Channels, just as Output Channels can now include other Output Channels. This will allow the template accessor methods to return fall-back data from another Input Channel when a field isn't filled in for the current Input Channel.
For example, Say a French Input Channel includes (inherits from?) an English Input Channel. If someone didn't put a value in a field in the French Input Channel, then the value from the English Input Channel will be used instead.
However, this includes/inherits feature will be optional, as the French field may be intentionally blank, and the template developer can always switch input channels manually to fetch missing data. Whether to use this feature or not will depend on the demands of the organization using Input Channels.
Sam Tregar <sam@tregar.com>
Mark Jaroski <mark@geekhive.net>
David Wheeler <david@wheeler.net>