A Zoology of Templates

From TechWiki

Within the Open Semantic Framework, the term "template" is used in many different ways and contexts. (Wikipedia also has many explanations, ranging from page layouts, to file templates to Web (page) templates.) The purpose of this article is to explain these differences and to provide examples.

Should terminology get confusing, please refer to the Presentation Glossary.

Uses Specific to the OSF Stack

The first category we tackle are "templates" used within the components specific to the OSF stack.

Basic Taxonomy

Though somewhat arbitrary, here is a basic taxonomy of "template" types within the OSF stack, proceeding from the most complicated (page-level) to the most individual (record-level).

• Content-type Layouts - these are specific layouts that combine Drupal content types with record displays driven from the underlying OSF stack. All of these constitute what are basically "page-level" layouts or presentations
• Resultset (compound or mixed) Templates - specific conStruct modules, namely Browse, Search and View, can present listings of multiple records at one time. Depending on the actual types of the records being displayed, this may invoke a mixture (compound) of record templates
• Record Templates - record templates are specific presentations formatted for specific record types. They may be either:
  • conStruct (Smarty) Templates - PHP-based templates for displaying records in multiple locations across the OSF stack, or
  • Semantic Component (Pure JS) Templates - these are record templates to support those semantic components written in JavaScript
  • (Flash Templates) - though these are individually coded, they are not, as yet, strictly template-driven. This last record category is provided here for completeness.

We'll take these categories in reverse order.

Record Templates

"Record templates" are a combination of specific display widgets and display formats that are organized according to record "types". The types of records within an OSF installation may be organized hierarchically. At the root is 'Thing', a generic placeholder for any kind of record. Below that record types increasing specialize, in a tree-like structure. For example, one might see this kind of hierarchy:

Thing
  |- Product
        Camera
           Digital Camera
        DVD
  |- Service
  |- etc.

If a specific display format for a given record type is defined, then records of that type will use that format. Failing a specific record template being available for a given type, the next format type checked is the parent. If a specific record template is available for the parent, that is used. If not, the check is then made for the next parent, and so on. Failing to find any specific record template (format) types up the parental chain results in the record being displayed with the generic "thing" format.

How these specific record formats by type may be designed or modified depends on what kind of widget is being invoked for the display.

conStruct (Smarty) Templates

The most common record template system is based on the PHP Smarty templating engine. The specific Smarty record templates presently available for any given OSF installation may generally be found under the following directory:

/usr/share/drupal/sites/all/modules/conStruct/templates/

Generally, this kind of record template is used by the various conStruct tools and is based on the PHP language. There is a useful overview document for how to build these record templates.

Code for sample example templates using the Smarty approach may be found under these documents, most with screen captures that show how the code is rendered:

• Sample Generic 'Thing' Record Template

(As noted above, absent a specific record template, the system defaults to the generic one.)

• Sample Bus Stop Record Template
• Sample Swimming Pool Record Template
• Sample Heritage Image Record Template

Semantic Component (Pure JS) Templates

Individual records may also be displayed by using JavaScript for the semantic components that use it. The JS templating system is based on Pure. Currently, this library, or modifications to it, is what is used to theme various record types presented via the sWebMap control.

Code for for sample example templates using the JavaScript approach may be found under this general directory:

 /usr/share/drupal/sites/mysite/themes/mytheme/js/sWebMap-templates.js

The current library of JS templates is further listed in this document:

• Sample Semantic Component JS Library Templates

Resultset Templates

There are three, fixed conStruct components -- View, Browse and Search -- that present results set lists or portions thereof by virtue of their design and operation.

Because these tools operate a generic functionality, depending on context and prior selections of data, the types of records that get presented to them for display both may span all available record types in the system and may result in a mixture of record types requiring display. For these reasons, this kind of template is called a resultset template (which means it needs to present either "compound" or "mixed" results).

Thus, in presentation mode, the format of the actual records presented through these tools may employ different widgets or presentation aspects. The net result is that the individual record template displays noted in the previous section may also be seen -- singly or in combination -- during the display of these templates.

Because of this nature, this kind of OSF template is actually intermediary between what are known as record templates and layouts. Each of the three tools -- View, Browse or Search -- is itself a special layout, but the records and their formats that get displayed depend on the context and query(ies) that generated the current results sets.

These templates do NOT rely on Smarty, but do use a combination of PHP + HTML.

There is a useful guide on how to build these resultset templates, as well as a rendered display of how one of these look as mixed record results.

Content-type Layouts

Layouts represent dedicated page displays that have a fixed format and a fixed set of display widgets. Generally, layouts are associated with a Drupal content type, via which it is possible to enter specific parameter values for each page in order to "drive" (populate with data) its display.

Layouts may be created either with the Smarty templating engine or directly in PHP + HTML coding. Layouts tend to block the display page into fixed display regions, in which a particular widget or record template may be displayed (and rendered).

Layouts are the preferred option when there are entire site branches or repeated sections for which display is desired to be fixed, but for which the actual data driving the display(s) may need to constantly vary. A common design approach is to have sub-menu links actually drive the queries that cause the data display to vary (say, by region, locale or topic, as set in the sub-menu).

Because of their highly repeated (duplicated) nature, layouts tend to be one of the more predominant displays types across an OSF installation.

Currently, here is the documentation on the set up and configuration of some of the more notable examples of layouts:

• Configuration: Charts Layout
• Configuration: Images Layout
• Configuration: Stories Layout
• Configuration: Topics Layout
• Configuration: WebMaps Layout

Example Layout Templates

We also see here the actual code examples that drive the display aspects associated with these various layouts:

• Sample Neighborhood Template

(This example is more oriented to a Smarty display framework; the next options are more related to embedded semantic components:

• Sample Chart Template
• Sample Image Template
• Sample Topic Template
• Sample WebMap Template.

Use in Third-party Applications

Two of the third-party apps that are part of the OSF stack -- Drupal and MediaWiki (used within the TechWiki) -- have their own conventions for the definition and use of "templates".

Drupal

A "template" as defined in Drupal is a specific page layout type associated with a particular node or page type in the system. (Defining new content types in Drupal allows a special template file to be created.) It is also possible to create templates for individual pages or nodes within a Drupal Web site, for example a different template for a site's "home page", as the example below shows.

"Templates" within Drupal are shown via the *.tpl.php extension in the main directory of its Web site. All Drupal templates are written in PHP code, often with various embedded HTML elements or sections.

This is an example of a Drupal template, in this case for the main page type within the OpenStructs.org Web site. Drupal template files are actually more akin to the OSF definition of "layouts" as presented above.

Mediawiki

In MediaWiki, the software used to host and manage the TechWiki content, "templates" are standard wiki pages whose content is designed to be transcluded (embedded) inside other pages. Templates are useful when you want to have repeated content or layouts across multiple other pages.

MediaWiki templates may themselves embed other templates; many of the more complicated pieces on Wikipedia, such as its infoboxes, are made up of a cascade of templates to create standard and reusable forms.

Embedding a template occurs via the double squiggly bracket convention:

 {{SampleTemplate}}

Any existing MediaWiki page may be embedded in that manner.

Most often, though, MediaWiki templates are used to create standard forms or headers or other common inclusions. In those cases, it is best to follow the convention that the name is prefixed with "Template:". This prefix acts to assign it to the Templates namespace.

MediaWiki templates are created like any other wiki page. However, as noted, often more complicated templates tend to nest still other templates.

Example Template

Here is an example of a MediaWiki template (actually two in series) used on this site; in this case, for referring to a linked Wikipedia page. The name of these templates are <code>{{WP}}</code> and <code>{{Prettytableb}}</code>.

You can go to the Template Concept page to see how this is rendered.