render:calltemplate

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
        c="asset type"
        cid="asset id"
        tname="called Template name"
        [d="Device Group Suffix"]
        [resolvetemplatefordevice="A boolean value indicating whether parameter 'd' should be ignored or not."]
        [style="pagelet|element|embedded"]
        [args="variable1,variable2,..."]
        [packedargs="packed arguments"]
        [site="site name"]
        [ttype="Template|CSElement"]
        [tid="caller Template or CSElement id"]
        [context="context override"]
        [elementpath="absolute"]
        >

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

</render:calltemplate>

Attributes

c (required): The type of the asset to be rendered by the called Template. The value of this attribute will be passed to the called code.
cid (required): The id of the asset to be rendered by the called Template. The value of this attribute will be passed to the called code.
tname (required): The name of the Template to be called. If tname refers to a typeless template, prefix the template name with '/'.
d (optional): Device Group Suffix(a string that is common suffix of all the templates written for current device group). For example, if d ='Touch' and parameter tname = 'HomeLayout', the tag will try to find a template with name tname_d i.e. HomeLayout_Touch. If it exists, the tag will call this template, otherwise will simply call the template 'HomeLayout' i.e. actual tname provided.
resolvetemplatefordevice (optional): true|false. Default is true. If 'false' is provided explicitly, the tag will ignore the parameter 'd' and will not try to re-direct to device group specific template.
style (optional): Flag that indicates that the called Template should be called as an element or as a pagelet, and if it is to be called as a pagelet, should it be embedded in the parent for Satellite Server or should it be an independent 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. When the style is set to embedded, the nested template is invoked as a pagelet without using Satellite Server. This causes the pagelet to be independently rendered (and possibly cached) by Sites but the result of the pagelet is embedded in the caller, just as if it had been called as an element. Satellite Server does not see embedded pagelets as separate from their caller; they are simply part of the output of the caller. Note that if this is set to element or embedded, 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).
args (optional): A comma-separated list of Sites variables to be passed as arguments
packedargs (optional): This attribute contains a series of arguments (name-value pairs) URL-encoded as a string.; Flag that indicates that the called Template should be called as an element or as a pagelet, and if it is to be called as a pagelet, should it be embedded in the parent for Satellite Server or should it be an independent 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. When the style is set to embedded, the nested template is invoked as a pagelet without using Satellite Server. This causes the pagelet to be independently rendered (and possibly cached) by Sites but the result of the pagelet is embedded in the caller, just as if it had been called as an element. Satellite Server does not see embedded pagelets as separate from their caller; they are simply part of the output of the caller. Note that if this is set to element or embedded, 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).
site (optional): The name of the site containing the Template to be invoked. This value does not need to be provided in most cases, as it is automatically retrieved by Sites from the ICS scope if not specified explicitly (the site name is always contained in the Sites site variable)
ttype (optional): This attribute identifies whether the code that contains this tag is a Template or a CSElement asset. The default value is Template. This value must be set to CSElement if the code is a CSElement asset. See also: tid.
tid (optional): 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. The proper value is automatically retrieved by Sites from the ICS scope if it is not explicitly specified: if ttype is set to CSElement, tid is given by the Sites variable eid. It is given by the Sites variables tid in all other cases.
context (optional): This attributes contains a context override parameter. It is only meaningful if the called templates contains code which define a presentation slot, using the insite:calltemplate tag. See insite:calltemplate for more information.
elementpath (optional): This attribute is used when the style attribute is set to element. When the root element of the template is different from the default value, this attribute can be used to indicate that the path provided in the tname refers to absolute path of the element.

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.

Description

This tag causes a specific asset, identified by the tag attributes c and cid, to be rendered by a specific template, specified by the tname tag attribute.

Since several Templates with the same name can coexist (as long as they are applicable to distinct asset types), the following convention applies for tname:

If tname starts with "/" then the typeless template corresponding to tname will be called. For example: <render:calltemplate tname="/Foo" c="Article" .../> will result in the typeless Template with name "Foo" to be called.
Otherwise, the Template corresponding to the specified tname and asset type (designated by the tag attribute "c") will be called. For example: <render:calltemplate tname="Foo" c="Article" .../> will invoke the Template with name "Foo", applicable to the asset type "Article".

From a caching point of view, the template can be rendered either as an inline element or as a nested pagelet (see the style attribute 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). Note that Sites only requires ttype to be set in the case of a CSElement (ttype="CSElement"). The value of tid and ttype are implicitly determined by Sites in all other cases.

This tag is the preferred method for invoking a template. Here are some general guidelines in order to render something other than a Template:

render:callelement is generally used to render a CSElement or standalone ElementCatalog entry rendering markup
ics:callelement is generally used to render a CSElement or standalone ElementCatalog entry processing arbitrary logic, but not necessarily rendering markup
render:satellitepage is used to render a SiteEntry or standalone SiteCatalog entry as a nested pagelet (i.e. equivalent to using render:calltemplate with style="pagelet")
render:contentserver is used to render a SiteEntry or standalone SiteCatalog entry as an embedded pagelet (i.e. equivalent to using render:calltemplate with style="embedded")

Error Numbers

The possible values of errno include:


Value	Description
-10004	A required parameter is missing .

Example 1: basic example

The following example calls the Detail template of the incoming asset, i.e. the asset which type and id are determined by the value of the c and cid Sites variables.

<render:calltemplate tname="Detail" args="c,cid" />

This syntax is strictly equivalent to the following:

<render:calltemplate tname="Detail" c='<%=ics.GetVar("c")%>' cid='<%=ics.GetVar("cid")%>' />

Example 2: passing extra arguments

Extra template arguments can be passed as follows:

<render:calltemplate tname="Detail" args="c,cid,foo" >
    <render:argument name="variable1" value="value1" />
    <render:argument name="variable2" value="value2" />
</render:calltemplate>

which results in:

foo being passed with the corresponding Sites variable value, i.e. the value returned by: ics.GetVar("foo").
c being passed with the corresponding Sites variable value, i.e. the value returned by: ics.GetVar("c").
cid being passed with the corresponding Sites variable value, i.e. the value returned by: ics.GetVar("cid").
variable1 being passed with value value1
variable1 being passed with value value1

Note that this example assumes that foo, variable1, variable2 are defined as cache criteria for the corresponding Detail template.

Deprecated attributes

The following tag attributes are deprecated:

slotname
variant