This section details a simple way to get started with the creation of your own templates.
Overview
The simplest way to create your own custom templates is to export a built in template, and then modify it. This has the advantage that the set of files and folders necessary are created for you, giving you an example of what is required, and saving you some time.
For a newcomer to the templating process, the steps required are roughly as follows:
- Understand the template types
- Choose the appropriate format
- Export a built-in template
- Customise the exported files
- Register your template source
- Restart DesiGen
- Resolve any issues reported during startup
- Test your template
These steps are covered in more detail below.
Understand the Template Types
The first step is to make sure you understand the different types of templates that can be created - there is more than one type. This is detailed on the Core Concepts page. Having a good understanding of the different types of templates is an important part of being successful with creating your own.
If you haven't read about the difference between artefact templates and artefact set templates, now is the time.
Choose the Appropriate Format
At the moment, this is simple - there is only one format: Zip V1. However, as the system evolves, there may become a need to add extra formats, so the system already has some limited support for the concept. As a result, I have chosen to structure the documentation to cater for this expansion from the outset. I know this might look a bit odd and feel a bit disjointed at the moment, but it is an attempt to avoid any breaks to the URIs of the docs pages.
A new format would be added if an enhancement to the system is not possible without a breaking change to the old formats. Our intention is to avoid forcing breaking changes to your template sources, as that would stop you being able to complete designs. However, we will always prefer to add features in a way that can be supported by extending an existing format if possible. Fewer formats means a simpler system, as well as simpler adjustments to existing template sources to benefit from new features.
In practice, what this means is that you should not assume that the formats are fixed and unchanging. They may well be extended, but they will not be broken.
See the appropriate section for the details of a specific format.
Export a Built-in Template
The file formats for the creation of custom code generation templates are somewhat complex. At the moment, these file formats are in flux; as we add more features, we may need to change the file formats slightly. As a result, the documentation on the file formats may not be complete.
Exporting one or more code generation templates is a good starting point to understanding the required file and folder structures; seeing a working example is often a simple approach. Having determined the type of template you wish to create and the format most appropriate, use the 'Export Templates' feature from the 'Templating' menu to export an appropriate template. This creates all of the definitions in the format you need, so you can modify them to get the desired results.
Customise the Exported Files
Have a poke around the files that were created and get a feel for them. Look at the file names and, where appropriate, the folder structures. Inspect the contents of the files with a text editor of your choice, comparing them with the documentation of the format in which you are working.
Now modify those files to represent the template you need. Check the definition matches what you want, and for artefact templates alter the code generation template text to generate the output you will require.
Getting the correct code generation template text is probably the most difficult part. The requirements for code generation template text are detailed in the Code Generation section of the docs.
Register your Template Source
Templates must be contained within a template source. Out of the box, DesiGen provides a single template source - it's own, built in source. To have DesiGen look for your additional templates, you must tell it where to look, by registering a template source that points to the file or folder in which your new templates reside.
Use the 'Manage Template Sources' feature within the 'Templating' menu to define the location of your shiny new template/templates.
Restart DesiGen
At the moment, templates are only registered at startup, so you must restart the application to initiate the process of having your templates registered from the template source.
You are likely to find that some issues are reported during startup, suggesting that you need to make some changes. Your entire template source is marked as unavailable for use until these issues are resolved and the registration process completes successfully.
Fix Any Reported Issues
Use the error messages displayed during registration to find and fix issues. One common issue you may encounter is attempting to register a template into an unrecognised category.
All templates must exist within a category, and it is your job to define the categories for your template source as part of your definition. The category definitions for the exported templates are created for you, so hopefully you just need to change the template or category definitions to fix the issue.
You cannot register your templates to categories defined in other template sources. Category template codes must be unique, and to make the creation of unique codes easier, we have decided that they will be unique to your template source.
Call us bold, but we imagine a future in which the community choose to share their templates with others. It is this vision that has led us to limiting the uniqueness problem to a single template source.
Test Your Template
The testing of a template depends on the type of template that you want to test.
The code generation of an artefact template can be quickly tested using the 'Testing' screen in the 'Templating' menu. This runs an in-memory code generation using a built-in/hard-coded data structure, and displays the generation results on the screen.
Testing of the defaulting of artefact names and properties can currently only be done by creating an artefact in a design.
Artefact set templates are design-only features, so these can only be tested by using them to add artefacts to a design.