Home > Contents > Index >
Template Tags TOC   |    Alpha TOC   |    Tag Family TOC   |    Purpose TOC   |    Annotated TOC   |    Index 

 

render:calltemplate

Invokes a Template, as either a pagelet or an element, for the purpose of rendering an asset.

Syntax

<render:calltemplate
        site="site name"
        slotname="name of slot"
        tid="caller Template or CSElement id"
       [ttype="caller Template or CSElement"]
       [c="asset type"]
       [cid="asset id"]
       [tname="target Template or CSElement name"]
       [context="context override"]
       [style="pagelet or element"]
       [variant="template variant name"]
       [packedargs="packed arguments"]>

   [<render:argument name="variable1" value="value1"/>]

</render:calltemplate>

Attributes

site (required)
The name of the site containing the Template to be invoked.
slotname (required)
This attribute defines an identifier for the "slot" that is being filled with the called template. It should be reasonably easy to understand for humans and should be unique across all templates. Future versions of CS Direct will make extensive use of the slotname attribute.
tid (required)
The id of the template in which this tag is located. If this tag is located in a CSElement, then the value of this attribute should be the id of the CSElement, and ttype should be set to CSElement.
ttype (optional)
This attribute identifies whether the code that contains this tag is a Template or a CSElement. The default value is Template, and CSElement is the other legal value. See tid.
c (optional)
The asset type to be rendered by the called Template. The value of this attribute will be passed to the called code. If c, cid, and tname are set, then context data is ignored.
cid (optional)
The id of the asset to be rendered by the called Template. The value of this attribute will be passed to the called code. This is required if c is set.
tname (optional)
The name of the Template to be called. This is required if c and cid are set. If these three attributes are not set, the called template will be determined by looking at context data.
context (optional)
This attributes contains a context override parameter. If c, cid, and tname are not specified, then this attribute value will be examined to determine which template to call and which asset to render using the specified template. If this value is not specified, then an ICS variable of the same name will be examined for the same purpose. If no context value can be located, then the slot will be not be populated, and this tag will do nothing. Future versions of CS Direct will provide an interface that allows the context data to be set automatically. Manually overriding this value should be considered an advanced technique.
style (optional)
Flag that indicates that the called Template should be called as an element or as a pagelet. The default value is pagelet. Setting this attribute value to element will result in the template being called as an element. This is useful if a nested pagelet is not necessary or desireable (i.e. would be overkill) for the target Template. When the style is element, the scope of the called element is local: only variables specified as arguments and attributes will be accessible to the called element, and variable values in the caller will not be affected. Note that if this is set to element, then the invoked Template will be embedded in the caller, and this can have performance, dependency, and caching implications, which can be good or bad depending on your code).
variant (optional)
This attribute specifies the name of the Template variant to render. Template variants enable multiple code implementations of a Template (for example, WEP vs XHTML). Future versions of CS Direct may implement this feature; as of the current release it is not yet supported.
packedargs (optional)
This attribute contains a series of arguments (name-value pairs) URL-encoded as a string.

Parameters

render:argument (optional)
Nested parameter tag. The render:calltemplate tag allows arbitrary argument tags to be added in order to pass name/value pairs to the called Template or CSElement.

Description

This tag is the preferred method for invoking a template. It effectively replaces render:satellitepage, render:contentserver, and render:callelement in most (but certainly not all) cases. It causes a specific asset to be rendered by a specific template. The template can be rendered either as an inline element or as a nested pagelet (see style, above).

Instances of this tag must contain information about who the caller is in order to operate correctly. The caller must be either another Template or a CSElement. This tag will not operate correctly without valid information about the caller. (see tid & ttype above).

render:calltemplate operates in two modes: explicit mode and context mode.

In explicit mode, c, cid, and tname are explicitly specified as attributes to the tag. In essence, the asset identified by c and cid will be rendered by the template corresponding to the template named tname. If tname starts with "/" then the typeless template corresponding to tname will be called. Otherwise, the template corresponding to the specified tname and asset type ("c") will be called. Explicit mode is the only mode that is currently supported.

In context mode, the context attribute (which defaults to an ICS variable of the same name if not present) will be examined to determine the template and asset to be rendered. Context mode support is not currently enabled in the CS Direct interface, however future versions may include it.

errno

The possible values of errno include:

Value
Description
-10004
A required parameter is missing .

Example

The following example, taken from the FirstSite Mark II Layout template, calls a template to render the html head tag. This tag displays the html title tag containing the description of the asset being rendered.

In this tag, most of the attribute values are set from other variables in the variable space, either because they have been passed in, or because they have been explicitly looked up.

The following table describes the origin of the ICS variables referenced below.

Variable origins
Variable name Origin
site The site variable is set as a resarg in all of the templates and SiteEntry assets. As such, it can be expected to be set correctly to the name of the current site.
tid The tid variable is set in the resargs of the called template. Because this code is in a Template, the tid attribute is set to the value of the tid variable. If this code had been located in a CSElement, this attribute would have been set to the value of the eid variable and the ttype attribute would also have been set to CSElement. See above for details.
c The c variable is specified on the URL and is passed unchanged into the Layout template.
cid The cid variable is specified on the URL and is passed unchanged into the Layout template.
tname The tname variable is set immediately above the render:calltemplate tag in the Layout template. It is set using the render:lookup tag, which effectively looks up the actual value of the template name to be rendered. For reasons relating to template replication, it's not a good idea to hard-code asset names in templates. The render:lookup tag provides an abstraction around hard-coding attribute values. Out of the box, however, the FSIILayout template sets the name of the head template as FSIIHead, and as such the variable tname resolves to FSIIHead.
p The variable p is specified on the URL and is passed unchanged into the layout template.
<render:calltemplate
        site='<%=ics.GetVar("site")%>'
        slotname="Head" 
        tid='<%=ics.GetVar("tid")%>' 
        c='<%=ics.GetVar("c")%>' 
        cid='<%=ics.GetVar("cid")%>'
        tname='<%=ics.GetVar("HeadVar")%>'>
    <render:argument name="p" value='<%=ics.GetVar("p")%>' />
</render:calltemplate>

See Also

render:lookup

  Home > Contents > Index >

FatWire JSP Tag Reference
Copyright 2005,2006,2007 by FatWire Software
All rights reserved.