This section details the original format for custom template sources - Zip V1.
New formats will only be created when new features would force a breaking change to an existing format. Wherever possible, existing formats will be extended rather than creating a new format. Adding an extra format adds complexity to the system and therefore to the maintainability of it. They are also likely to force template source creators to make greater changes to their template sources, which we want to avoid.
Core Concepts
The core concepts associated with templating are documented at Core Concepts This is a good starting point for learning how templating in DesiGen is intended to work.
Format Overview
The Zip V1 format is based on a zip archive. Zip Format
This format requires folders with a specific root hierarchy, and files with recognised suffixes. Top-level folder names are fixed but their existence is optional - you can include either one without the other. The file names of contained template definitions and category definitions must end with recognised values to be considered relevant.
Additional files and folders may exist, but are ignored during template registration.
Folder Structure
The following root-level folders are used to contain templates:
- ArtefactTemplates - Searched for artefact templates and artefact template categories
- ArtefactSetTemplates - Searched for artefact set templates and artefact set template categories
Subfolders within these top level folders are optional; use them as you find useful. The name of any subfolder is not relevant; the only limitation is that they be considered valid folder names.
Artefact Templates
An artefact template is made up of two separate files: the JSON definition, and a template text file.
Artefact templates can only exist within the top-level ArtefactTemplates folder (or any subfolder of it, to any folder depth.) We tend to create subfolder structures that match our categories, but that is only a convention and is not a requirement. However; this general usage does lead to a slight inconsistency in naming: no leading period/full stop is required on category definition files.
Template Files
Any file within the ArtefactTemplates folder (or subfolders of it) whose name ends .Template.V1.json (with a leading period/full stop) is considered an artefact template definition, and registration of it is attempted by deserialising its contents from JSON.
An artefact template must also include a template text file, whose path and name is specified in the JSON definition. It is expected that these text files will also be within the same top-level folder - indeed, next to and named similarly to the artefact template definition file - but that is only a convention and is not a fixed requirement.
Template Category Files
Any file within the ArtefactTemplates folder (or subfolders of it) whose name ends Category.V1.json (without a leading period/full stop) is considered an artefact template category definition, and registration of it is attempted by deserialising its contents from JSON. If you follow our convention of using subfolders that match the categories then the filename can simply be Category.V1.json - and this is why no leading period/full stop is required.
No other files within the ArtefactTemplates folder are used in registration.
Artefact Set Templates
An artefact set template is made up of a single file: the JSON definition.
Artefact set templates can only exist within the top-level ArtefactSetTemplates folder (or any subfolder of it, to any folder depth.) We tend to create folder structures that match our categories, but that is only a convention and is not a requirement. However; this general usage does lead to a slight inconsistency in naming that is worth making clear: no leading period/full stop is required in category definition filenames, but is required in template definition filenames.
Template Files
Any file within the ArtefactSetTemplates folder (or subfolders of it) whose name ends .Template.V1.json (with a leading period/full stop) is considered an artefact set template definition, and registration of it is attempted by deserialising its contents from JSON.
An artefact set template plays no part in code generation - its use is limited to creating artefacts during design - so an artefact set template has no associated template text file.
Template Category Files
Any file within the ArtefactSetTemplates folder (or subfolders of it) whose name ends
Category.V1.json (without a leading period/full stop) is considered an artefact set template
category definition, and registration of it is attempted by deserialising its contents from JSON.
If you follow our convention of using subfolders that match the categories then the filename can
simply be Category.V1.json - and this is why no leading period/full stop is required.
No other files within the ArtefactSetTemplates folder are used in registration.