IncludeTemplating System : Designer Guide : Tag Reference : Include
The include tag is used to include a dynamic subtemplate into the current template. Subtemplates are evaluated in the same fashion as any other dynamic template; the developer may associate data sources and other properties to them.
<include src="subtemplate" attribute="value" ...>or
<include src="/packages/packagename/www/lib/subtemplate" attribute="value" ...>
- Arguments may be passed to the subtemplate by specifying
additional attributes to the include tag. All attributes
except for src are assumed to be arguments and are set
as variables which the subtemplate may reference using the
var tag. To pass a dynamic variable to the subtemplate,
specify the variable name surrounded by at signs as the value:
<include src="subtemplate" source_id="@source_id@" ...>Note that passing an html string to a subtemplate via
@var@will result in passing an html-escaped and internationalized string. To prevent this, use
@var;literal@when passing html to subtemplates. Alternatively the variable can by passed by name (similar to call-by-reference) causing a variable alias to be created in the scope of the subtemplate. This variant is necessary for e.g. passing a Tcl array like a templating datasource. To pass e.g.
usersby reference, use this notation:
<include src="subtemplate" &persons="users" ...>This is particularly useful for passing onerow and multirow data sourced. Note that in this case, if the subtemplate modifies the value this will affect the includer. When the datasource in the included page has the same name (
&users="users"), you can use the shorthand
- It is important to note that variables passed through
include become available to the .tcl and .adp files
being include'd, but it does not make them
settable through ad_page_contract.
So if you'd like to have a template that will return a fragment of a page that you'd like to include in other pages, make sure its .tcl component does not call ad_page_contract.
If you'd like to include a full page (that is, one which calls ad_page_contract) then instead of passing a parameter through <include>, you could use rp_form_put to add the variable to that page's form. For additional references, see how message-chunk is used throughout the forums package.
- If the src attribute begins with a slash, the path is assumed to be relative to the server root, the parent directory of the Tcl library. If not, the path is assumed to be relative to the current template, not the URL of the page request.
- If the page layout is sensitive to additional whitespace surrounding the subtemplate, then care must be taken that the subtemplate does not contain any blank lines at the beginning or end of the file.