HomePortalsTemplates
When composing a page HomePortals uses templates as a blueprint for the overall HTML structure of the final document.
HomePortals uses two types of templates: Page Templates and Module Templates.
- Page templates are used to render the complete document.
- Module templates are used to define the structure of each module or container.
Templates are always referenced by their name and type. A HomePortals application can have any number of templates defined. Every page will use only one page template, and multiple module templates.
Templates do not need to be declared explicitly by every page and module; whenever a template is not defined, HomePortals will use the default templates for each type.
All templates need to be declared on the configuration. You only need to declare a template on your own application if you want to override the default templates provided in the global configuration file.
On [wiki:homePortals-config.xml homePortals-config.xml.cfm] you declare templates on the renderTemplates section:
#!xml
<renderTemplates>
<renderTemplate name="module" type="module" default="true" href="/homePortals/templates/module.htm" />
<renderTemplate name="moduleNoContainer" type="module" href="/homePortals/templates/moduleNoContainer.htm" />
<renderTemplate name="page" type="page" default="true" href="/homePortals/templates/page.htm" />
</renderTemplates>
name: This is the name by which the template will be referenced elsewhere. type: Either 'module' or 'page' href: Path to the location where the template document is located. This path can be either relative to the application directory or if it starts with a '/' then it is relative to the web server's root. default: Indicates whether to use this template as the default for this type of module
HomePortals comes with three pre-defined templates located in the /homePortals/templates/ directory. However, you can create more templates to suit your needs. Also, you can override templates by declaring your own templates but using the same name. Templates defined at the application level will take precedence over templates defined at the global level.
You can indicate which template to use for any page or module.
For pages, you use the element, or the setPageTemplate() method.
Be aware that if the page template does not exist, the HomePortals engine will throw an error and will not be able to render the page at all.
In the case of modules, you use the moduleTemplate attribute. This attribute must use the name of an existing template of type 'module'
#!xml
<page>
<pageTemplate>__template_name__</pageTemplate>
...
<body>
<some_tag ... moduleTemplate="__template_name__" .. />
</body>
</page>
If you don't explicitly indicate which template to use (either page or module), HomePortals will use whichever is defined to be the "default" template for its kind.
Templates are HTML documents with special markers or tokens that get replaced at run-time for specific content or content sections. The tokens available differ by the template type.
The following table illustrates the available template tokens:
||Token_'||'''Template Type'''||'_Description|| ||$PAGE_TITLE$||Page||Title of the page|| ||$PAGE_HTMLHEAD$||Page||Indicates the position where any content belonging to the HTML's Head section should be rendered. This includes for example any stylesheets, Javascript files, or Javascript code fragments.|| ||$PAGE_ONLOAD$||Page||A Javascript function to be executed when the HTML page finishes loading. This token should go on the onLoad property of the body tag|| ||$PAGE_CUSTOMSECTION[ "base resource type''" ]$||Page||Indicates the position where all base resources of type ''base resource type should be placed. This is typically used for including ColdFusion or HTML templates.|| ||$PAGE_LAYOUTSECTION[ "section name''" ][ "''tag name''" ]$||Page||Indicates the position where all modules or containers on a page belonging to the given section should be rendered. If ''tag name is given, then each module or section will be enclosed in the given tag. Section names are declared on the layout section of a homePortalsPage|| ||$PAGE_PROPERTY$[ "property name" ]||Page, Module||Replaces the token for the value of the given page property. If the page does not contain a property of the given name, then the token is replaced by an empty string|| ||$MODULE_ID$||Module||The ID of the current module as given on the containing homePortalsPage|| ||$MODULE_ICON$||Module||An image used as an icon. The image is given by the icon property of the module|| ||$MODULE_XYZ$||Module||This token is replaced by the contents of a property of name XYZ, where XYZ can be any of the standard module properties, such as title, class or style, or can be a custom/user-defined property. If no matching property is found an empty string is sent to the output|| ||$MODULE_CONTENT$||Module||Rendered output of the module||
When HomePortals renders a page, it needs to know in which of the layout regions defined on a template it needs to render each module or content block. Normally, each page has a section in which it defines which regions it will use. This allows the page to customize its layout even further.
However, specially when using your own custom templates, you can omit entirely the layout declaration and just reference the layout regions on your page template directly from the modules on your page. This is called an "implicit layout".
When using implicit layouts, the "location" attribute of your modules can point to the names you gave to the layout regions on your page template.
For example, given the following page template:
#!xml
<html>
<head>...</head>
<body>
<div style="width:800px;margin:0 auto;">
$PAGE_LAYOUTSECTION["Header"]["div"]$
<div style="float:left;width:200px;">
$PAGE_LAYOUTSECTION["LeftNav"]["div"]$
</div>
<div style="margin-left:210px;">
$PAGE_LAYOUTSECTION["Main"]["div"]$
</div>
<div style="clear:both;">
$PAGE_LAYOUTSECTION["Footer"]["div"]$
</div>
</div>
</body>
</html>
Your pages can benefit from implicit layouts like this:
#!xml
<page>
<body>
<text value="this goes on the header" location="Header" />
<text value="this goes on the left nav" location="LeftNav" />
<text value="this goes on the main area" location="Main" />
<text value="this goes on the footer" location="Footer" />
</body>
</page>
When using customized page templates, you can use implicit layout to greatly simplify your pages. Also, note that you cannot mix implicit and explicit layouts on the same page. If you use the block on a page, then all page locations used on modules need to map to any of the declared layout regions on the block. Unmapped locations are not displayed.
Within your application you can access the current templates by obtaining a reference to the Template Manager (homePortals.components.templateManager). This is a component that handles access to the defined templates on an application.
You can get a reference to this component via the HomePortals engine instance:
#!xml
tm = application.homePortals.getTemplateManager();
The template manager caches the body of any template the first time it is used, so that subsequent uses of the same template do not need to read the template file again.