Chapter 7. Template engine

Table of Contents

Template sets
Physical structure
Collection access
Custom template sets
Error view
Favorites view
Object view
Object-results view
Results view
Search view
Login view
URI routes
Content representations
Using the PHP API in the templates

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.

Template sets

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.

Physical structure

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:



Error view


Favorites view


Object results view


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


Login view

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 images and/or scripts folder; additional HTML/PHP files to include; etc.

Collection access

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.

Custom template sets

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:

  1. In 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 it newtpls.

  2. Register the new template set in the Control Panel, and assign one or more collections to it.

  3. Navigate to your dm folder in your web browser, appending the collection alias you wish to view to the URL like so:


    Your collection should come up, displaying results view. Click on a result and object view will load, and so on.

  4. Enter the newtpls/templates folder. Notice subfolders like object, error, favorite, etc. Take a look inside any one of them and notice one or more files with the .html.php 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.