T4 templates have a simple ASP.NET-like syntax and consist of processing directives, text blocks and code blocks. For this discussion we’re using the attached DCTTreeWizard.tt file which is a Utility template. Download it from here
We have two types of Utility Templates; DCT Utility Templates and ApplicationUtility Templates. Within the IDE when the “Document” tab that has focus is a .DCT or an .APPX the “Run Utility Template” menu item under the File menu is enabled, and depending on the type of the active document, the “Run Utility Template” Menu item will show a Selection Dialog displaying the appropriate Utility Templates for the document (DCT Utility Templates or Application Utility Templates) The big difference between a standard template and a Utility Template, is that the when the Utility Template is executed, the code will not output any text/code automatically. The template developer must define the output using the built-in Open/Close or Create/Close methods.
The DCT Utility template focuses on the DataDictionary object. The DataDictionary object is of type IDataDictionary, and using the IDE’s code completion we can learn how to use it; seeing its properties and methods with the complete descriptions. The DataDictionary object is very straight forward and easy to undertand. For example, it’s likely pretty clear that “this.DataDictionary.Tables” returns all the tables defined in the Dictionary.
The Application Utility template also has the DataDictionary object, but it has another object called “Application”. And of course you can query “this.Application.Procedures”, and guess what that returns? Yes you guessed it, all the procedures defined in that .APPX file.
Let’s do a walk-through of our simple DCT Utility template.
We’ll start with a look at Directives. The syntax of a directive is:
<#@ DirectiveName [ParameterName = “ParameterValue”] #>
for an example look at line 1 from the attached template:
<#@ template language=”C#” debug=”true” type=”Utility” name = “DCTTreeWizard” chain=”Clarion.File”#>
The “language” parameter specifies which language is used in the code blocks of the template, and in this case we specify C#.
The “debug” paramater allows you to debug templates. When that parameter is on, and the corresponding IDE option is also on, the template source code files are copied to the %root%..Templatesdotnet folder. And when there is an error in compiling the template (compilation occurs when you register the template), the error is displayed in the Error pad, and you can then double-click on the error and the .TT file with the error is opened for editing at the line with the error.
The “type” parameter specifies the type of template, current possible types are:
Application,
Procedure,
ApplicationExtension,
ProcedureExtension,
Utility,
UtilityApplication,
WizardApplication,
WizardProcedure
The “name” parameter assigns a name to this template, and finally the “chain” parameter specifies the template family.
Lines 2-6 use the “assembly” directive:
<#@ assembly name=”mscorlib.dll” #>
<#@ assembly name=”System.dll” #>
<#@ assembly name=”System.Drawing.dll” #>
<#@ assembly name=”System.Design.dll” #>
<#@ assembly name=”System.Drawing.Design.dll” #>
The “assembly” directive identifies an assembly to be referenced by the template so that you can use types within that assembly from within the code in your template. Using the assembly directive is equivalent to using the Add Reference feature in the Clarion# IDE. The “assembly” directive does not affect the source code of the compiled template.
Lines 7-12 use the “import” directive.
<#@ import namespace=”System.Collections.Generic” #>
<#@ import namespace=”System” #>
<#@ import namespace=”SoftVelocity.TextTemplating” #>
<#@ import namespace=”System.Drawing” #>
<#@ import namespace=”System.Drawing.Design” #>
<#@ import namespace=”SoftVelocity.DataDictionary.Design” #>
The import directive allows you to refer to types within a text template without providing a fully qualified name. The “namespace” parameter is transformed into a .Net “using” directive in the compiled template.
Now look at line 13:
<#@ property processor=”PropertyProcessor” name=”OutputFile” type=”System.String” defaultValue=”none” editor=”System.Windows.Forms.Design.FileNameEditor”#>
The “property” directive defines an editable property of the template. It corresponds to #PROMPT in our Win32 template language. The parameters are probably self-explanatory; “name” is the name that is displayed in the property grid, “type” defines what type of value is accepted, “defaultValue” is exactly as the name suggests, and “editor” is the object that is used to visually edit the property. The “editor” can be just the default; a simple text string, but it can also be a dialog window, a dropList, a checkbox, or by default a simple textBox.
Line 14 is interesting: <#+ string _OutputFile = “”;#>
the <#+ tag indicates a template helper block. The helper block allows the template developer to add code at the TextTransformation Class level. The code added can be a Method, a Field, or a Property declaration.
If a Method is declared within the helper block, it can be compared to a #GROUP from our Win32 template language. Embeds can also be declared inside a helper block.
for example:
<#+ void MyPseudoGroup() {#> <#% MyEmbed #> <#+}#>
In this case when the method MyPseudoGroup is called, the content of the MyEmbed will be also executed.
Line 15: <# this._OutputFile = this.OutputFile;#>
just the value set in the “OutputFile” within the property directive to the internal _OutputFile variable.
Line 16: <# Create(this._OutputFile);#>
calls an internal method that creates a file on disk to receive the generated text (code or other text). It corresponds to our Win32 counterpart #CREATE.
Line 17:
*************************
is a text block, as there are no template directives surrounding it. Text blocks are copied to the output “as is”, with no further processing.
Line 18: – Listing for Dictionary: <#= this.DataDictionary.FileName #>
mixes a text block: ‘– Listing for Dictionary: ‘ with an expression block:
<#= this.DataDictionary.FileName #>
You use expression blocks in text templates to add strings to the generated text output. In this case we’re asking for the name of the Dictionary that we’re processing. Expression blocks are delineated by using the <#= template tag. The syntax is: <#= ExpressionCode #>
Lines 19-49 use code blocks. The syntax for a code block is: <# Code block #>
Code blocks can generate template output. In our template the code block uses a few nested foreach loops to walk the dictionary. We’re using a mix of text blocks and expression blocks to write the details of the dictionary to the output file. Code blocks can use any available .NET APIs. In this template we’re using the DataDictionary API to output the Dictionaries collections and properties; Tables, Columns, Keys and Relationships.
I hope this walk-through has provided a good introduction to the new template syntax used in AppGen.Net. For those who are thinking of writing some T4 templates the attached example is a good starting point to get familiar with the essentials. Next time we’ll go a bit deeper into the template syntax.
