Table of Contents
The dmBridge template engine attempts to strike a balance between ease of use, advanced customization potential, and upgrade-safety (meaning that underlying implementation changes in either dmBridge or CONTENTdm® won't break your page templates). The high-level HTML layout is left entirely up to the web designer, while some smaller bits - rendered by the template helpers - render HTML in a fixed structure that can be styled, but not customized. (This is the price to pay for the ease of being able to use "one-liners" to call up sophisticated functionality.) The default functionality of any of the template helper methods can be overridden by custom helpers, but this is generally a job for a programmer.
In practice, even without custom helpers, the template development process is much more flexible than that for the CONTENTdm® templates. (Originally, this was the number-one design priority for dmBridge.) However, it is also completely different, so there is a necessary learning curve.
A single set of dmBridge templates can be used with a single collection, multiple collections, or all collections. Conventionally, a "single collection" set of templates would be customized for that collection, and an "all-collections" set of templates would be styled to harmonize with the digital collections department or organization. That's just an idea, and you are free to do whatever you want. It is easy to reassign which collections appear in which set of templates at any time via the Template Sets section of the Control Panel.
dmBridge templates can coexist peacefully with CONTENTdm® default templates, as the two do not interfere with each other.
You should never delete your default templates, as they are required by the CONTENTdm® administration module.
Template sets are self-contained in their own folders, located inside the
dm/templates folder. The required elements of a template
set folder are as follows:
templates/ error/ view.html.php favorite/ index.html.php object/ compound_results.html.php no_results.html.php results_faceted.html.php results.html.php view_compound.html.php view_simple.html.php search/ index.html.php user/ login.html.php
"No results" view, resulting from a search that returned no results
Results view, when facets are available for display
Results view, when no facets are available for display
Compound object view
"Simple", non-compound object view
Search view. Note that this displays only the search form; results are displayed in one of the object results templates.
These are only the required elements of a template set. It
is perfectly acceptable to add additional folders containing any other kind of
files used by the template set. For example, many template sets will include
folders such as a top-level
scripts folder; additional HTML/PHP files to include;
In deciding which template set to load for a given URL, dmBridge parses the URL to determine whether a collection alias is present. If it is, it will load the template set that has been associated with that collection in the Template Sets section of the Control Panel. If it is not, it will use the template set that has been specified as the system-wide default.
Also in this section, it is possible to specify collections that are not allowed to appear in a given template set. This will prevent these collections from appearing in search forms, and it will prevent objects from these collections from appearing in search results.
The dmBridge distribution includes two template sets. One, called "Clean White," is already styled. The other, called "Basic," is deliberately spartan, intended to be a starting point for your own creations, rather than a finished set of templates itself.
The dmBridge templates can be designed like any other HTML page using the text or WYSIWYG editor of your choice. The only extra consideration is styling the dynamically-generated content produced by the template helper methods. Obviously, you need to see the HTML code they produce in order to style it. One way to do this is by viewing the source of the generated page in your web browser. A better way is using a DOM inspection tool such as:
The Firebug extension for Firefox
The Developer Tools built into IE
The Web Inspector built into Safari
All of these will enable you to "zoom in" on a specific element in order to find CSS classes or IDs that your CSS rules can "grab onto," which makes writing them relatively easy.
The following is a walkthrough of the template customization process:
dm/templates, make a copy of the
basic folder. Give it a descriptive alphanumeric
name in all-lowercase (substitute underscores for spaces). Here, we'll call
Register the new template set in the Control Panel, and assign one or more collections to it.
Navigate to your
dm folder in your web browser,
appending the collection alias you wish to view to the URL like so:
newtpls/templates folder. Notice
favorite, etc. Take a look inside any one of them
and notice one or more files with the
extension. These are dmBridge template files. Open one up and notice that
it's an HTML file, with some
<?php ?> tags in it. Each
one of these files corresponds to one of the main views in the dmBridge
templates: object view, results view, favorites view, etc. It should be
fairly clear just by looking at them which one is which; check the
<title> tag inside them if you're not sure.
If you have inspected any of the template files, you may be wondering about the
code within the
<?php ?> tags. These are calls to methods in
the PHP API. The PHP API enables access to all
dmBridge functionality from within the templates.