Content Repository Developer Guide: Applying Templates

Applying Templates

Content Repository : Developer Guide

The content repository allows you to associate templates with both content types and individual content items. A template determines how a content item is rendered when exported to the filesystem or served directly to a client.

The content repository does not make any assumptions about the type of templating system used by the application server with which it is being used. Templates are simply made available to the application server as text objects. The server is responsible for merging the template with the actual content.

Creating templates

The content repository handle templates as a special class of text object. The interface for handling templates builds on that of simple content items:

template_id := content_template.new(
    name          => 'image_template',
    parent_id     => :parent_id
);

The name represents the tail of the location for that content template. The parent ID must be another content item, or a subclass of content item such as a folder.

The content_template.new function accepts the standard creation_date, creation_user, and creation_ip auditing parameters.

Content items and templates are organized in two separate hierarchies within the content repository. For example, you may place all your press releases in the press folder under the item root (having the ID returned by content_item.get_root_folder). You may have 5 different templates used to render press releases. These my be stored in the press folder under the template root (having the ID returned by content_template.get_root_folder).

Templates are placed under their own root to ensures that bare templates are never accessible via a public URL. This is also done because the relationship with the filesystem may be different for templates than for content items. For example, templates may be associated with additional code or resource files that developers maintain under separate source control.

Associating templates with content types

You use the content_type.register_template procedure to associate a template with a particular content type:

content_type.register_template(
  content_type => 'content_revision',
  template_id  => :template_id,
  use_context  => 'public',
  is_default   => 't'
);

The use_context is a simple keyword that specifies the situation in which the template is appropriate. One general context, public, is loaded when the content repository is installed. Templates in this context are for presenting content to users of the site. Some sites may wish to distinguish this further, for example using intranet, extranet and public contexts.

The is_default flag specifies that this template will serve as the default template in the case that no template is registered to a content item of this content type and this use context. Any content type/context pair may have any number of templates registered to it, but there can be only one default template per pair.

To make a template the default template for a content type/context pair:

content_type.set_default_template(
    content_type => 'content_revision',
    template_id  => :template_id,
    use_context  => 'public'
);

Associating templates with content items

Individual items may also be associated with templates using the content_item.register_template procedure:

content_item.register_template(
  item_id     => :item_id,
  template_id => :template_id,
  use_context => 'intranet'
);

Unlike the case with content types, only one template may be registered with a content item for a particular context.

The content management system uses this functionality to allow publishers to choose templates for each content they create. For example, a company may have three different templates for presenting press releases. Depending on the subject, geographic region or any other criterion, a different template may be used for each press release.

Retrieving the template for a content item

The application server (AOLserver or servlet container) may use the content_item.get_template function to determine the proper template to use for rendering a page in any particular context:

template_id := content_item.get_template(
    item_id     => :item_id, 
    use_context => 'public'
);

template_path := content_template.get_path(
    template_id => :template_id
);

In the case that no template is registered to given item/context pair, content_item.get_template will return the default template (if it exists) for the related content type/context pair.

Unregistering templates

The procedure for disassociating templates with content types is as follows:

content_type.unregister_template(
    content_type => 'content_revision',
    template_id  => :template_id,
    use_context  => 'intranet'
);

The corresponding procedure to disassociate templates with content items is:

content_item.unregister_template(
    item_id     => :item_id,
    template_id => :template_id,
    use_context => 'admin'
);

karlg@arsdigita.com

Last Modified: $‌Id: template.html,v 1.2.2.1 2021/04/05 19:49:49 gustafn Exp $