Category Archives: IDE

Clarion T4 template walk-through

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.

AppGen.Net – update

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:

t4editor_cc

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.

t4editor_groupfastaccess

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

t4editor_codefoldingtooltip

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.

t4apptree

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!

Coming up with 7.2

There was a recent thread in the news group where a lot of people were saying how much they used (and missed) the availability of a list of an Applications’ Procedures. Seems that code completion wasn’t the best option when you can’t remember the name of the Procedure. And its quite understandable when you have many many procedures, possibly hundreds, in your .App. So thanks to some quick work by Diego, Scott and Alexey, we were able to slip this this new feature into the 7.2 release; the Data pad now has a “Procedures” node, and when selected it lists all template based procedures, the Procedures node is only activated when you are in any of the editors, and dbl-clicking on a procedure name in the list inserts the procedure name into the editor. The Procedures list also has a Windows Explorer style incremental locator.

proclist

Clarion 7.2 – Menus

We’re getting Clarion 7.2 ready for release, and I thought I’d make a few posts and talk about the changes and new features. Version 7 already has support for creating a very nice UI on your menu’s, and we recently added a couple new menu styles and support for using a 3d vertical separator. Using the Menu Styles lets you provide the exact same UI for your menu’s across all supported operating systems. No matter what OS your application is deployed on you have complete control of the menu colors and overall style.

Now in 7.2 we’ll introduce new support to make your applications use the OS menu’s. The new support doesn’t use the MenuStyleManager class, its only requirement is that your App is properly manifested, and with that your menus will match the menus on the users operating system. Here are some screen shots taken from different operating systems.

osmenuwin7

osmenuvista

osmenuxp

ospopupvista

ospopupwin7

ossystemmenuwin7

and for those who prefer using the C7 MenuStyleManager class you can be sure we’ll continue to enhance it, so that you’ll have complete consistency in your menu’s across operating systems

menustylesbabyblue