|
1 User guide for Template Configuration File Markup Language (TemplateML) Plugin |
|
2 ------------------------------------------------------------------------------ |
|
3 |
|
4 Introduction |
|
5 ''''''''''''' |
|
6 This page describes how to use and configure Template Configuration File Markup Language |
|
7 (TemplateML) plugin fo ConE. TemplateML is one of the implementation mapping languages for |
|
8 Configuration Markup Language (ConfML). This plugin is used to generate arbitrary text file |
|
9 formats. It doesn't have a specific extension or encoding. Currently |
|
10 this language uses `Jinja 2 template engine <http://jinja.pocoo.org/2/>`_ to generate |
|
11 output files. |
|
12 |
|
13 Templates are based on Jinja syntax and semantics that are described in detail `Jinja 2 Template Designer Documentation <http://jinja.pocoo.org/2/documentation/templates>`_ |
|
14 One important concept in Jinja is `template inheritance <http://jinja.pocoo.org/2/documentation/templates#template-inheritance>`_, which means that you can overwrite only specific blocks within a template, customizing it while also keeping the changes at a minimum. |
|
15 |
|
16 Templateml plugin supports also `XML Inclusions (XInclude) <http://www.w3.org/TR/xinclude/>`_ |
|
17 that allows a mechanism for merging XML documents. By writing inclusion tags in a "main" |
|
18 document it automatically includes other documents. |
|
19 |
|
20 TemplateML files are executed by default in **normal** :ref:`invocation phase <implml-common-invocation-phase>`. |
|
21 |
|
22 Template Configuration File ML |
|
23 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
24 |
|
25 The TemplateML syntax is a extension of Configuration markup language (confml). The term in confml for this extension |
|
26 is implementation method language (implml), which in TemplateML case is a xml file. |
|
27 |
|
28 All input values, excluding template and filter elements text content, can be given as ConfML refs. |
|
29 |
|
30 * Namespace: ``http://www.s60.com/xml/templateml/1`` |
|
31 * File extension: ``templateml`` |
|
32 |
|
33 .. note:: |
|
34 |
|
35 More information about :ref:`file extensions <implml-file-extensions>`. |
|
36 |
|
37 TemplateML Elements |
|
38 ................... |
|
39 |
|
40 The TemplateML model is drawn out as a uml model in below picture. |
|
41 |
|
42 .. image:: templateml.jpg |
|
43 |
|
44 .. note:: |
|
45 |
|
46 TemplateML supports also common ImplML elements. More information about :ref:`ImplML elements <implml-common-elements>`. |
|
47 |
|
48 |
|
49 templateml element |
|
50 ************************** |
|
51 |
|
52 The root element of the templateml file is always templateml, which defines the xml namespace (xmlns) |
|
53 to http://www.s60.com/xml/templateml/1 in the current version. |
|
54 |
|
55 **templateml example**: |
|
56 |
|
57 .. code-block:: xml |
|
58 |
|
59 <templateml xmlns="http://www.s60.com/xml/templateml/1"> |
|
60 |
|
61 desc element |
|
62 ************************** |
|
63 |
|
64 Description element's content is not used in output file generation, but it can be used to describe temlplateml file. |
|
65 |
|
66 **desc example**: |
|
67 |
|
68 .. code-block:: xml |
|
69 |
|
70 <desc>Description field text</desc> |
|
71 |
|
72 output element |
|
73 ************************** |
|
74 |
|
75 Output element describes how one output file is generated. Output has one mandatory attribute 'file' that defines filename for output file. If you want to generate output file to some other than default folder, it can be done by defining a output directory to 'dir' attribute. Default encoding for output file is 'UTF-8', if some other encoding is wanted, it can be defined by 'encoding' attribute. This encoding should be one of the standard Python codecs encoding (see http://docs.python.org/library/codecs.html#standard-encodings). |
|
76 |
|
77 Template element is mandatory child element for output element. One output element can have only one template element. |
|
78 Output element can also contain optional filter elements that are specific just for this output file. Global filters that are common for all output files should be defined under root templateml element. |
|
79 |
|
80 **output example**: |
|
81 |
|
82 .. code-block:: xml |
|
83 |
|
84 <output file="my_output.txt" encoding="UTF-8" dir="output"> |
|
85 <template>Hello world!</template> |
|
86 <filter name="filter1">lambda a,b: a+b</filter> |
|
87 <filter name="filter2">lambda a,b: a*b</filter> |
|
88 </output> |
|
89 |
|
90 For unicode transformation formats, control over the BOM is provided by the attribute ``bom``. |
|
91 This attribute defines whether the BOM is written to the output or not. If the attribute is not |
|
92 defined, the default behavior of the encoding is used (i.e. BOM is written for UTF-16, but not for UTF-16-BE, |
|
93 UTF-16-BE or UTF-8). For encodings where the BOM makes no sense (e.g. ASCII), the attribute does nothing. |
|
94 |
|
95 **Examples**: |
|
96 |
|
97 .. code-block:: xml |
|
98 |
|
99 <output file="test.txt" encoding="UTF-8" bom="true"> |
|
100 <template>test</template> |
|
101 <output> |
|
102 |
|
103 <output file="test.txt" encoding="UTF-8" bom="false"> |
|
104 <template>test</template> |
|
105 <output> |
|
106 |
|
107 template element |
|
108 **************** |
|
109 |
|
110 Template can be defined in template element or in external file. If both are defined file attribute overwrites. |
|
111 |
|
112 **template example 1:**: |
|
113 |
|
114 .. code-block:: xml |
|
115 |
|
116 <template>Some Jinja template goes here</template> |
|
117 |
|
118 Notice that if you want to define create xml output files and you don't want to encode special characters you can use CDATA section http://www.w3schools.com/xmL/xml_cdata.asp. |
|
119 |
|
120 .. code-block:: xml |
|
121 |
|
122 <template> |
|
123 <![CDATA[ |
|
124 <xml name="xml temp">Some Jinja xml template</xml> |
|
125 ]]> |
|
126 </template> |
|
127 |
|
128 **template example 2:**: |
|
129 |
|
130 .. code-block:: xml |
|
131 |
|
132 <template file="../../templates/template.txt"/> |
|
133 <template file="${feat1.tempfile_setting}"/> |
|
134 |
|
135 With template's file attribute template is defined relatively to templateml file. |
|
136 |
|
137 filter element |
|
138 ************************** |
|
139 |
|
140 With filter element you can define custom filters. Custom filters are just regular Python functions that take the left side of the filter as first argument and the the arguments passed to the filter as extra arguments or keyword arguments. Filter element has mandatory 'name' attribute that defines the name of the filter. Name is used in template to refer to that filter. Filter can be defined in filter element or in external file. If both are defined file attribute overwrites. |
|
141 |
|
142 `Jinja has built-in filters <http://jinja.pocoo.org/2/documentation/templates#builtin-filters>`_ (e.g. capitalize, replace, trim, urlize, format, escape) that can be utilized without any extra definitions templateml file. |
|
143 |
|
144 **filter example**: |
|
145 |
|
146 .. code-block:: xml |
|
147 |
|
148 <filter name="minus">lambda a,b: a-b</filter> |
|
149 |
|
150 With filter's file attribute filter is defined relatively to templateml file. |
|
151 |
|
152 Variables |
|
153 +++++++++ |
|
154 |
|
155 The TemplateML plugin passes variables to the templates you can mess around in the template. Every feature has |
|
156 following attributes: |
|
157 |
|
158 * _name |
|
159 * _namespace |
|
160 * _value |
|
161 * _fqr |
|
162 * _type |
|
163 |
|
164 Currently TempleML plugin passes features in three different structure: feat_tree, feat_list and configuration. |
|
165 |
|
166 feat_tree |
|
167 +++++++++ |
|
168 |
|
169 Variable 'feat_tree' contains features in a tree structure. It allows easy access to features attributes, |
|
170 when feature explicitly known: |
|
171 |
|
172 .. literalinclude:: templateml_example2.txt |
|
173 :language: xml |
|
174 |
|
175 feat_list |
|
176 ++++++++++++++++++++++++++ |
|
177 |
|
178 Variable 'feat_tree' contains features in an array and allows easy access to all features e.g. in loops: |
|
179 |
|
180 .. literalinclude:: templateml_example1.txt |
|
181 :language: xml |
|
182 |
|
183 Generates to output file e.g following content: |
|
184 |
|
185 .. literalinclude:: templateml_example1_result.txt |
|
186 :language: xml |
|
187 |
|
188 configuration |
|
189 ++++++++++++++++++++++ |
|
190 |
|
191 Configuration object that is defined ConE API can be accessed also inside template. |
|
192 |
|
193 .. code-block:: xml |
|
194 |
|
195 <template>Configuration name: {{ configuration.get_path() }} |
|
196 {% for feature in configuration.get_default_view().get_features('**') %} |
|
197 {{ feature.fqr }} |
|
198 {% endfor %} |
|
199 </template> |
|
200 |
|
201 |
|
202 Examples |
|
203 ''''''''' |
|
204 |
|
205 An example of templateml file, that generates two output files, utilizes XInclude and defines two custom filters: |
|
206 |
|
207 .. literalinclude:: templateml_example0.txt |
|
208 :language: xml |
|
209 |
|
210 XSD |
|
211 ''' |
|
212 |
|
213 Download: :download:`templateml.xsd </xsd/templateml.xsd>` |
|
214 |
|
215 |
|
216 FAQ |
|
217 ''''''''' |
|
218 This will be updated based on the questions. |
|
219 |
|
220 |