Version 4 > Developer Guides > Content Model > Formatted views

Formatted views

Many content types (those with their display type set to "formatted") use a flexible formatting system to decide how to lay themselves out.

Formatted content generates an HTML snippet (partial document) which is then inserted into a page skeleton where the content tags specify. If the content is the primary content, it is generally substituted into the page where the body would go. For example, when viewing an article, the article is first formatted according to the rules below, and then the formatted article is placed into the page skeleton as the "body".

In addition to the standard views, you can define your own views using templates with merge codes. The following styles of merge code are supported:

styledescription
[ [foo] ] insert foo here
[ [?foo] ]TEXT[ [/?foo] ] include TEXT if foo is defined
[ [!foo] ]TEXT[ [/!foo] ] include TEXT if foo is not defined
[ [>foo] ] insert content object foo (eg. find foo in a library) 
[ [>>foo] ] similar, but find foo in the current content's path
[ [.foo] ] insert another format named foo
[ [#N] ]TEXT[ [/#N] ] include TEXT if viewer is at least access level N

The recognized merge codes are:

codedescription
title, label, name, language taken from the content record
id, about, author, caption, description, icon, index, info, navpath, summary, tools, height, width obtained by calling the given method
type the content type, eg. “page”, “article”
date the posting date
curl the canonical URL to the content
url the URL to the content
purl permalink to the content
html the HTML to display the content
attachments links to any sub-content downloads
gallery a thumbnail gallery of images under this content
secondary_gallery like gallery, but excludes the first image
price the price of the item (formatted)
price_value the price amount (unformatted)
tags a list of tags the content has been tagged with
contacts contact information for the content
parent the title of the parent content
site the title of the website or section
mime_type the MIME type of the content, eg. image/jpeg
mime_descr friendly description of the MIME type, eg. "JPEG image"
mime_category general description of the MIME type, eg. "image"
meta_X, eg. meta_author metadata ‘X’
url_VIEW, eg. url_thumbnail the URL to a particular VIEW (eg. thumbnail)
html_VIEW, eg. html_thumbnail the HTML for a particular VIEW (eg. thumbnail)
index_TYPE, eg. index_profile an index (summarized listing) of just the named subtype
contact_FIELD, eg. contact_city a contact field value
contents_TYPE, eg. contents_profile a full listing of just the named subtype
CONTENT:..., eg. logo:url_thumbnail any of the above parameters for CONTENT
_FIRST:..., eg. _FIRST:title any of the above parameters for the first subcontent item
_LAST:..., eg. _LAST:title any of the above parameters for the last subcontent item
_IMG:..., eg. _IMG:html any of the above parameters for the first image of the subcontent items
_PARENT:... any of the above parameters for the parent content
_REF:... any of the above parameters for the reference content (first ancestor of a different type)

Additionally, any content class can define special methods of the form param_NAME() which will be used to resolve merge codes of the form "NAME". For example, location objects can generate their own maps. They also define a parameter method for this, $loc->param_map(), which means you can include [[map]] merge codes in location formats.

Default views

Default formats are predefined. You can override these using the configuration settings content.format.TYPE, for example:

content.format.article = ...

You can also install arbitrarily named formats using a similar method, eg.

content.format.special_format = ...

and then make use of them in your own calls, eg.

$out = $c->show_formatted($format,%data)

where $format is either the name of a preconfigured format (eg. "special_format"), or a complete template, and %data is any merge code values you want to override.

If no type-specific view is defined, the CMS will fall back on the generic view for "content", ie.

content.format.content = ...

Summary views

Summary views are used in content listings. For example, when viewing a blog, you will be shown the default view of the blog (using content.format.blog, if it is defined), and a listing of the current postings, each of which is displayed in a summary view.

The summary views will use their own formats, content.format.TYPE_summary, for example:

content.format.article_summary = ...

This is typically an abbreviated view, suited for quick scanning rather than in-depth reading.

Contextual views

You can make your formats more specific by including a container object type in the format name. For example:

content.format.article_comment_summary = ...
content.format.forum_comment_summary = ...

will define different formats for comments in forums vs. comment on articles (eg. blog postings).