Templates
Templates allow users to define a custom format in which to extract data from their project, using Apache FreeMarker syntax. These can be used either directly from the editing page or in the Data Model tab of the Generate mode as a means to expand generation options beyond the defaults and help to support unique user requirements.
User Interface
Templates can be created, reviewed, and edited in the Templates tab of the Generate page. After editing a template, the user can:
- Save: saves a new template or any changes to an existing template.
- Clear: erases the content of the code window
- Reset: reverts all of the changes made when editing an existing template or erases any progress made when creating a new template
The Filter By dropdown at the bottom is used to filter the nodes that will be generated if the user wants to generate a model from this page using the selected template.
Template Syntax
Generally, templates are not used to extract or display data about a particular project node, but are rather used to format the reporting or indexing of a type or several types of node within the project. At some point in the template, a user will indicate what type or types of node will be used to fill in the contents of the file to be generated. The user will then be able to use a special syntax as placeholder for the data to be extracted from the project, surrounding the placeholders is any additional code necessary for the user's requirements.
Basic Template Syntax
PHENOM's templates use Apache FreeMarker, a full-featured template engine. You can reference their documentation for features that are not covered below.
To use a particular type of node to fill a template with data, declare the type and an alias for it in the following format: <#list type as alias></#list> Any code that go between the opening and closing list tags will be repeated for each node of the type, much like a loop iterating and writing out the contents of the list tag, each time using data from a new node of the requested type. The following code taken from logical_model.html (a default template) will create an HTML table with a header row followed by a row for each measurement found in the project. Note how the <#list> tags surround the tag, which means that code for a new table row will be generated for each measurement.
While the <#list> (ln. 11, 19) tags indicate a type of node to use and iterate over to generate code, the ${alias.attribute} (ln. 13 - 18) syntax is the placeholder which, at time of generation gets replaced with the value of the requested attribute of a particular node. Below is some HTML that the example template would generate.
Note how the attributes inside of the curly brackets get replaced with data particular to a measurement node (ln. 11-16) . Also note that the "..." in the code (ln. 18) indicates all of the rows which would have been generated for the other measurements in the project.
Iterating Over Child Nodes
Some nodes which can be used for generating templates may contain one or more child nodes or fields. A user can generate code for each one of these fields while iterating over the parent node by nesting list tags as follows:
<#list type as alias><#list alias.field as fieldAlias></#list><#list>
In this case, any code placed inside the internal <#list> tag would repeat for every field node of each type node. The code below (taken from view_comma_export.csv) is used to export data about each view field in the project:
Note that because calls like ${view.name} are placed inside the <#list> for the view field, this data will be repeated for each of the a given view's characteristic's rows.
Available Node Types / Attributes
The following tables summarizes all of the node types which can be referenced using template syntax, accessible attributes, as well as attributes of any possible field nodes.
| enums (Enumeration) | enums.fields (Enum Literals) | structs (IDLStructs) | structs.fields | views | views.fields | observables | units | measurements | constraints | entities | entities.attributes | uops | uop.fields |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| name | name | name | name | guid | guid | guid | guid | guid | guid | guid | guid | uop_name | port_name |
| description | description | modelName | xmitype | name | name | name | name | name | name | name | name | uop_desc | port_desc |
| measurement | type | description | type | description | description | description | description | description | description | pattern | |||
| measurement-guid | modelName | xmitype | realizes | type | specializes | type | message_request_type | ||||||
| observable | parent_view | description | measurement_system.name | upperBound | specializes | response_type | |||||||
| observable-guid | is_union | vector_type | measurement_system.description | lowerBound | synchronization | ||||||||
| fields | switch | bound | measurement_system.external_standards_reference | upperBoundInclusive | communication_style | ||||||||
| enum_switch | source | measurement_system.orientation | lowerBoundInclusive | period | |||||||||
| is_composite | path | measurement_system.coordinate_system | |||||||||||
| measurement | |||||||||||||
| type_model | |||||||||||||
| type_parent | |||||||||||||
| type_size | |||||||||||||
| c_type | |||||||||||||
| c_type_model | |||||||||||||
| c_type_parent | |||||||||||||
| source_name | |||||||||||||
| string_path | |||||||||||||
| is_foreign | |||||||||||||
| viewType | |||||||||||||
| optional | |||||||||||||
| union_cases | |||||||||||||
| imported | |||||||||||||
| c_imported | |||||||||||||
| switch |