Utilizing Sub-Templates

General Usage

Whenever you have template code that can be shared between two or more templates, it makes sense to extract it into its own file. The general format of the tag is:

<xar:template type="module|theme|system" module="modname" file="filename" subdata="$keyarray" /> 	

module= is only needed with type="module" (and defaults to the current template's module, though I recommend putting it in there anyway).

When type="module", BL will first look for themes/mytheme/[modname]/includes/filename.xt If it's not found it will then look for modules/[modname]/xartemplates/includes/filename.xd

When type="theme", BL will look in the themes/mytheme/includes/ directory for the file, with extension ".xt".

When type="system", BL will look in the current template directory for the "filename". Note, in this case you must supply the name extension (e.g. .xt).

Lately I've started making a subdir under includes called "snippets", just to make it easier to find my stuff. So, a template might have the tag,

<xar:template type="theme" file="snippets/mycode" /> 	

And put the code in file

themes/mytheme/includes/snippets/mycode.xt

A few notes. Details of this tag can be found in RFC010. Sub-templates can access any local variables pass into, and/or defined by the calling template. (That is, unless you use the subdata= argument, in which case the only variables available to the sub-template are those defined in the subdata key list array. This lets sub-templates act more like self-contained functions). Also, any variables you define or change in the sub-template are not available in the calling template once it returns.

Articles Summary and Display Alike

I have a simple Articles Pubtype where I only need one way of formatting the contents, in both the Vew/Summary page and the item's own Display page. Rather than cut and paste the template code I decided to just include the summary template in the display one. Thus, user-display-myptype.xt contains

<xar:template type="system" file="user-summary-myptype.xt" />  	

This instructs BL to find the file relative to the parents directly. Note that the file extension is required when using type "system".

Overriding Default Admin Templates

When I need to override default templates, such as admin-new or admin-modify, in an application for (certain) users, I usually still want my admin account to get the full blown template.

For instance, I give some users the ability to submit new articles. They use a customized admin-new-myptype.xt template. I structure the template something like this:

<xar:if condition="xarIsAncestor(  'Administrators',  xarUserGetVar('uname') )"> 	

	<xar:template type="system" file="admin-new.xd" /> 	

<xar:else /> 	

	... custom admin new template here ... 	

</xar:if> 	

And a similar thing for admin-modify. This way, when I'm logged in as Admin, and go through the Articles admin gui, I get the full default admin forms.

However, this doesn't quite work, it's going to look for the default .xd file in the theme directory. (type="module" also won't work in this case). Instead you can copy the .xd files from modules/articles/xartemplates/ to the mytheme/modules/articles/ or create a symlink (which is what I did).

BLTemplate Property

A more advanced technique, configurable via GUI, utilizes the BLTemplate property. For example in an Xarpages pagetype, if you add a Dynamic Data property BLTemplate, you can choose a template file from a dropdown list, and then include it via the custom page template.

See the Vaporbase posting, Dynamic Extendable Templates in Xarpages section heading "Including Other Templates" in the 2nd half of the article.