Pattern Template Syntax

Unofficial Content

Template files are basically composed by output intermixed with processing instructions. The processing instructions are delimited by tags (<% and %>). In particular, for Pattern Templates the output is an XPZ (GeneXus export file) file and the processing instructions are in C#. The goal of this document is to provide a reference to the various tags and objects that can be used during the creation of template files.

Directives

Template Directive

Every template file is required to start with a Template directive. It specifies general properties of the template, such as the template Language (the language in which the processing instructions are written, which can be either C# or VB.Net), the TargetLanguage (the language of the generated code, for syntax highlighting), and a brief Description of the template (for documentation purposes).

<%@ Template Language="C#" TargetLanguage="GX" Description="Main Template" %>

Import Directive

The Import directive adds a using statement in C#, or an Import statement in Visual Basic .NET, to the template code. This, along with the assembly directive is needed to invoke C# classes. The Namespace parameter indicates the namespace to be imported.

<%@ Import Namespace="System.XML" %>

Assembly Directive

The Assembly directive tells the Template Engine which external assemblies should be referenced for the template. For example, if you want to use the .NET XML classes in the template, you need to reference the ?System.Xml? assembly. The Name parameter is the fully qualified name of the assembly. The assembly must exist in the Global Assembly Cache, in the directory where the template is located, or in a directory above the one the template is located.

<%@ Assembly Name="System.XML" %>

The references to the System, System.Data, System.Drawing, System.Design and System.Windows.Forms assemblies are automatically included.

Property Directive

The property directive declares properties that will be used as parameters by the template. The needed parameters are the Name and Type for the property, which must correspond to a valid .Net datatype (class, enum, etc, and in particular for "primitive" datatypes their .Net full names must be used, such as ''System.Int32'' for integers instead of just ''int'').

<%@ Property Name="Filename" Type="System.String" %>

Subtemplate Directive

To apply the same "template fragment" in several places, you can create a sub template and invoke it. Using a sub template is a two-step process: first you need to declare it at the top of the main template. Then, you need to invoke it in the template using the CallSubTemplate directive. For example:

<%@ SubTemplate Name="GridAttributes" Name="GridAttributes.dkt" MergeProperties="False" %>

The Name parameter determines the 'logical name' of the subtemplate, while the File parameter indicates the template's actual filename. It must be located in the same folder as the calling template. If the MergeProperties boolean parameter is set to ''True'', all of the parent templates properties are automatically assigned to the subtemplate if it has declared properties of the same name.

CallSubTemplate Directive

The CallSubTemplate directive is used to invoke a sub-template.

<%@ CallSubTemplate GridAttributes AttributesList="attributesList" DeleteMode="true" %>

The CallSubTemplate directive requires the logical name of the subtemplate (as declared in the SubTemplate directive) and the values to set in the subtemplate's properties.

Code Tags

Code tags are used to include .NET code in the body of the template.

<% and %> Tags

These tags are used for any amount of code that does not directly provide output for the template.

<%foreach (GXAttribute attribute in transaction.AllAttributes())%>

<%{%>

1

<%}%>

This sample will loop through each item in the collection, and output a 1 to the template. This is not very useful, as we probably want to output something like the name of the attribute; that is where the next tag comes into the picture.

<%= and %> Tags

These tags are used to output a string to the template, whatever code is used between these tags must resolve to a simple string. Here is an example of these tags:

<%foreach (GXAttribute attribute in transaction.AllAttributes()%>

<%{%>

   Attribute Name is <%= attribute.Name %>

<%}%>

Script Tags

Script tags are used to include a piece of code in your template that is not used to directly affect the output of the template. This is the best place to put helper methods that you might call throughout the rest of your template. Using script tags you can minimize the amount of code that is included between the <% %> tags, making your templates more readable and manageable.

Though still supported, script tags are considered superseded by the Include directive (see above)

Comment Tags

Comment tags can be used to include comments in your template without affecting the output of your template. The comment character is "--" and can be used inside the <% %> code tags.

<%-- This is a comment --%>

Pattern Specific Notes

The main template for a pattern must have at least one parameter called "FileName". It will be used to specify the instance file to be applied to. In order to load this file, use the LoadXmlDocument method of the InstanceManager class (to get the instance as an XML document), or the LoadInstance method (to get it as a PatternInstance object).