This section details some core code generation concepts that will help you get started with creating your first custom code generation text template.
Artefact Template Definitions and Text Templates
As detailed in the Templating section, there are two types of templates in DesiGen: Artefact Templates and Artefact Set Templates. Only one of these is directly associated with code generation: Artefact Templates. An Artefact Template consists of two parts: the definition of how to create an artefact, and the textual template that is used to generate an artefact associated with that template definition.
This section specifically deals with the textual template that is used for generation.
The Code Generator: Scriban
As with a lot of software solutions, DesiGen is not completely proprietary work. Instead, we stand on the shoulders of giants by using well-respected open source packages to achieve some of the functionality we provide. This is nowhere more true than when considering code generation.
The mechanics of code generation is not our area of expertise. It would make little sense to try to build a code generator if we could reuse one that offered as much functionality as we needed, or more. In researching code generation we discovered the excellent open source library Scriban, written and maintained by Alexandre Mutel. Proof of concept work in our early days indicated that this was a highly functional, reliable and consistent library, and that it was an excellent candidate for our purposes.
Scriban is not only well written and maintained, but also extremely well documented. This ensures that our users have good information at their fingertips when developing their code gen templates.
We strongly recommend that our users make good use of the documentation available on GitHub. Bookmark the Scriban documentation site and immerse yourself in its detail to gain knowledge on how to customise your generation templates.
Our thanks go to the team behind writing and maintaining Scriban, especially Alexandre. We would not be able to offer the sophisticated code generation available in DesiGen without their work. You can learn more about The Scriban team on GitHub.
If you appreciate the code generation functionality we have packaged then consider giving Scriban a star, and sponsoring their work. With your help, Scriban can be made even better.
Getting Started
We think there is no better way to learn how to create a custom template than by referring to a working example. DesiGen has some built in templates that should offer a good starting point for your path to creating custom templates of your own. Furthermore, the functionality we provide ensure that these templates can be easily reused.
An ideal way to start with creating your own templates is to export an existing template and then modify it. Refer to the Export Templates feature in the Templating section of the application to export the template on which you want to base your own, and then modify the contents of the export to suit your needs. Then, create a custom Template Source by referring to the modified file to reimport your templates and make them available for use during design and code generation.
Custom Properties
Custom properties are defined as part of the definition of an Artefact Template. These are used to capture input from the user for use in outputting in specific locations within the generated code. If you need for your user to enter a piece of information to make your template more flexible, then you will do that by defining a Custom Property.
As an example, a lot of the C# templates have a custom property of 'namespace'. Namespaces are a required part of a C# class, so it is important that the user enter the namespace somewhere for the generated code to be valid.
Custom properties can be inherited from a parent Artefact. This is one of the main reasons why Artefacts can be defined in a hierarchical tree structure, rather than just a flat list. inheriting a property value from a parent can dramatically reduce the number of times the data needs to be entered, which speeds up the process of design significantly.
Referring back to our previous example, C# namespaces are generally inherited from their container. The top level default namespace in a C# project is the name of the project, and the default for a folder within the project is the project name plus the folder name. By allowing all of our classes to inherit their namespaces from their parent, we need enter the data in a single place - against the project - and have all of our classes inherit the value and 'do the right thing' automatically, following the defacto convention for C# throughout.
Data entered against a custom property is made available for use through the Artefact.Properties collection. Numerous examples of the use of Custom Properties can be seen in our built in templates.
Artefact Template Helpers
Sometimes, code generation template text can be made much simpler by leaning on custom .NET code to do conversions and generate fragments for output. Artefact Template Helpers exist to fulfil this role. These are specially-designed classes created in a way that they are compatible with the code generator which allows them to be called just like they were built in functions provided by the code generator.
At the moment, DesiGen is limited to built in types to fulfil this role. In the future, you will be able to create your own custom helpers and import them alongside the Artefact Templates that make use of them.
A number of built in helpers are available for your use; these are detailed in the topic entitled Built In Helpers.
Template Registration
At the moment, templates are only registered as the application starts up. If you add a new Code Gen Template Source then you should restart the application to have your template source inspected for changes. New and modified templates are registered as they are found.
The date and time of the file containing your templates is used for versioning purposes. Template sources are only inspected for changes if their date and time is newer at startup than on the previous check. While the date and time remains the same or older than the last check, registration is bypassed.
Happy templating!