Clarion

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%\..\Templates\dotnet 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.

We just released an update for 7.2 with a nice mix of fixes and changes to both the IDE and the RTL. If you are a template writer then note that we’ve bumped the template version number to 7.2/7200.

You can check the readme list here

As we move forward in getting the new AppGen.Net and the new template families ready for you, we are simultaneously working to make writing the new T4 templates (much) easier. That task involves creating a specialized editor and supporting hybrid code completion. What’s hybrid code completion? Well to write a T4 styled template you need both code completion for the template directives and the template constructs (embeds, properties, ATs, etc), and code completion for the template language used (as we mentioned before that will be C# for the first release, and later we’ll support Clarion#). So the editor and parser must work together and determine whether the code being written or parsed is template directive or template language. Sounds simple enough but changing the context can happen almost anywhere, including on a line that starts in one context and mid-way through switches to another context and then back again.

Here’s an animated GIF that shows the code completion (CC) in action:

And here’s another one that shows the editor Drop list of “Methods” – equivalent to what in the Win32 templates we call #GROUPs (the drop lists also contains the equivalent to #ATs). All in all it makes for a very powerful template writing environment.

Of course the editor supports all the standard features we all depend on, like syntax coloring and code folding.

The T4 editor and hybrid code completion will make for much faster learning of the interfaces available in the templates, and will make it so much easier to write templates. We are also planning for the code completion to make available “Embed” names when you are in the equivalent to the Win32 #AT tag.
Well as you can see a considerable effort has been put into making writing and modifying templates a better experience. Writing templates is a bit of an art, not everyone can think in the abstract of translating lines of template code into lines of generated code, but writing good templates is much easier when you have the right tools available. As we got deeper into writing the T4 style templates we quickly saw that the syntax highlighting just wasn’t going to be enough. And though we hadn’t planned on support for code completion and code navigation in the T4 templates as critical for a first release, we decided from our own experience that it was actually going to be critical, for us and for you. We’re getting very close to finishing with that task, and doing so moves us that much closer to the end goal.

But enough on writing the templates, now let’s take a quick look at the user interface for using the templates in the new AppGen.Net. This screenshot shows a lot of key areas; central we have the Application Tree dialog. The dialog is split into the tree view on the left side, and the details view on the right. In the details view we can see the Properties, Extensions, Embeds and Procedures tabs. This is the main area you’ll be working from when not in the Designers or Editor. You can also see at the bottom right the new .Net Applications pad which has equivalent functionality the Win32 Applications pad; i.e. you can generate, generate/make or generate/make and run your applications.

We had hoped for an early June beta, and while we’ve decided the system isn’t quite ready today for a beta release you can see how much closer we’re getting. We’ll try to post weekly updates on the new AppGen.Net right here, and we’ll keep you informed as the beta release moves closer. And Thanks for your patience!

In case you didn’t receive the email (and with the sea of spam I’ll bet many of you didn’t get it), and if you haven’t visited the “Special Offers” page on the website, you should know that we have some really nice offers going on right now; for a limited time - you can save up to $450 (ends on June 21st).

And not only are we offering great discounts on Core Subscription renewals, we’re also giving away free copies of our new training course “Inside the Clarion 7 IDE”, and offering free access to our new Application Migrations Assist (AMA) service. The new Application Migrations Assist service provides you with the option to invite one of our support technicians to log into your machine, and help you work through any migration issue you might run into – it’s expert help and advice right on your desktop.

And if you hadn’t heard, we brought back the Simple Maintenance Plan (SMP), and we have a one-time offer of $75 off that subscription (and you get the new Training course and AMA service). Hop on over to the special offers page, and get the full details on the new training course, and the discounts available. But you better do it soon, because these offers expire June 21, 2010

The new Clarion 7.2 IDE is the platform for the future of all Clarion development, now is your best chance to get into it and keep pace with the future of Clarion.

We just released an update for 7.2, this release fixes a couple regressions that slipped past us in the initial release, and introduces some very good optimizations to the App Recovery logging. You should see a very nice improvement in performance across the board (Opening Apps, Generating code, editing Embeds and Closing Apps) when working with the App Recovery feature turned ON.  Its a short list since we just released a week ago, you can check the readme list here