Templates: Difference between revisions

From PHENOM Portal Knowledgebase
Jump to navigation Jump to search
Line 20: Line 20:
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 <tr> tag, which means that code for a new table row will be generated for each measurement.
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 <tr> tag, which means that code for a new table row will be generated for each measurement.


'''Template Syntax'''
<br>
<code><nowiki>
<br>
<table style="width:100%">
[[File:Phenom-generate-templates template syntax.png|none]]
  <tr>
    <td>Name</td>
    <td>Description</td>
    <td>Realizes</td>
    <td>Measurement System (M.S.)</td>
    <td>M.S. Description</td>
    <td>M.S. Orientation</td>
  </tr>
  <#list measurements as meas>
  <tr>
    <td>${meas.name}</td>
    <td>${meas.description}</td>
    <td>${meas.realizes}</td>
    <td>${meas.measurement_system.name}</td>
    <td>${meas.measurement_system.description}</td>
    <td>${meas.measurement_system.orientation}</td>
  </tr>
  </#list>
</table>
</nowiki></code>


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.
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.


'''Generated HTML'''
<br>
<code><nowiki>
[[File:Phenom-generate-templates generated HTML.png|none]]
<table style="width:100%">
 
  <tr>
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.
    <td>Name</td>
    <td>Description</td>
    <td>Realizes</td>
    <td>Measurement System (M.S.)</td>
    <td>M.S. Description</td>
    <td>M.S. Orientation</td>
  </tr>
  <tr>
    <td>ChemicalConcentrationMeasurement</td>
    <td>Measurement used to describe observable properties of a chemical concentration.</td>
    <td>ChemicalConcentration</td>
    <td>AmountOfConcentrationMeasurementSystem</td>
    <td>System for measuring the amount of concentration.</td>
    <td>Values increase as concentration increases</td>
  </tr>
  ...
</table>
</nowiki></code>
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 ===
=== Iterating Over Child Nodes ===

Revision as of 16:13, 15 September 2022

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:

Node Field Extraction Template View_Guid,View_Name,Characteristic_Guid,Characteristic_Name,Source,Path,Measurement,Primitive <#list views as view> <#list view.fields as field> ${view.guid},${view.name},${field.guid},${field.name},${field.source},${field.path},${field.measurement},${field.type}${'\n'} </#list> </#list> 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.


name name name name guid guid guid guid guid guid guid


type name name name name name name name



description type description description description description description



xmitype

realizes id offset



description

measurement_system.name primitive



vector_type

measurement_system.description mask



bound

measurement_system.external_standards_reference condition



source

measurement_system.orientation




path

measurement_system.coordinate_system




measurement