Chapter 7. Template engine

Table of Contents

Template sets
Physical structure
Supported markup languages
Collection access
Custom template sets
Views
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.

[Caution]Caution

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:

templates/
    error/
        view.html.php1
    favorite/
        index.html.php2
    object/
        compound_results.html.php3
        no_results.html.php4
        results_faceted.html.php5
        results.html.php6
        view_compound.html.php7
        view_simple.html.php8
    search/
        index.html.php9
    user/
        login.html.php10

1

Error view

2

Favorites view

3

Object results view

4

"No results" view, resulting from a search that returned no results

5

Results view, when facets are available for display

6

Results view, when no facets are available for display

7

Compound object view

8

"Simple", non-compound object view

9

Search view. Note that this displays only the search form; results are displayed in one of the object results templates.

10

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.

Supported markup languages

Although the template author is theoretically free to write templates using any markup language, the dmBridge template helper methods currently return markup exclusively in HTML. This means:

  1. The templates themselves must be written in HTML in order to be valid.

  2. The templates must be served with a Content-Type header of "text/html."

Often, web pages are written in XHTML and served with a Content-Type of "text/html" -- an improper configuration that causes them to be parsed as HTML. This will "work" in that browsers will render the resulting pages, but the end result will be little different from serving plain HTML.

It is a goal of dmBridge that all template helper methods should pass W3C validation. This is not always achieved. But the more important thing is that the markup is at least good enough to trigger web browsers' "standards mode," which optimizes the accuracy and compatibility with which they will render the markup.

HTML5

HTML5 is an evolving standard for the next version of HTML after 4.01. HTML5 templates will work with dmBridge without any issues.

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:

    http://my_cdm_server/dm/objects/alias

    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.