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:
| style | description |
|---|---|
| [ [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:
| code | description |
|---|---|
| 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 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 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.
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).