<html>
-<title>Magic Smoke ODT Templates</title>
+<title>Magic Smoke ODF Templates</title>
<body>
-<h1>Magic Smoke ODT Templates</h1>
+<h1>Magic Smoke ODF Templates</h1>
-This text describes how ODT templates are generated and which ones exist. ODT templates always use the suffix ".odtt".
+This text describes how ODF templates are generated and which ones exist. ODT templates always use the suffix ".odtt" for text templates and ".odst" for spreadsheet templates.
<h2>Creating a Template</h2>
This process needs some knowledge in XML.<p>
<ol>
-<li>Write an OD file that meets your expectations for what you want to template. It is recommended that you already put all variables (@VAR@, see below) into the file to make it easier to find each location.</li>
+<li>Write an OD file that meets your expectations for what you want to template. It is recommended that you already put all variables (@VAR@, see below) or at least some markers into the file to make it easier to find each location. Alternatively you can go through the "Edit Templates" dialog to retrieve an existing template.</li>
-<li>Unzip it into a clean directory - make sure the directory structure of the ODT-ZIP-file is kept intact.<br/>Eg. under Linux to extract example.odt: <tt>mkdir example; cd example; unzip ../example.odt</tt></li>
+<li>Open MagicSmoke and log into your system (this is necessary to test localization and to have data available for testing the template).</li>
-<li>Reformat content.xml to make it readable for yourself. You can use any XML tool that suits your need.<br/>Eg. <tt>xmllint --format content.xml >content2.xml; mv content2.xml content.xml</tt></li>
+<li>Go to the menu "Actions" - "Templates" - "ODF Editor", then go to "File" - "Import ODF File" and load your file.</li>
-<li>Enter all missing variables and loops. Note that the Template language is line based, while XML is not.</li>
+<li>Enter all missing variables and loops. See below.</li>
-<li>Zip the result into a template file.<br/>Eg.: <tt>cd example; zip -r ../example.odtt .</tt></li>
+<li>Test the template:
+ <ol><li>Go to "Test" - "Test with..."; depending on what kind of template you are constructing chose the correct type.</li>
+ <li>MagicSmoke asks for the Order ID or Event to use as a template - it is best if you check beforehand to have a few examples handy that fulfill your requirements for testing a template (e.g. one order with multiple different tickets, one with vouchers, one paid, one partly paid...)</li>
+ <li>A window opens that contains the example information - it behaves just the same as in normal mode except that it always uses the template you just created for printing. Warning: if you make changes to an order in this window, they WILL end up in the system!</li>
+ <li>Go to the print or save function and test the template, it is recommended to use a virtual PDF printer or to just save as ODF file for testing to avoid wasting paper.</li>
+ <li>Close the window, continue to change the file or save it.</li>
+ </ol>
-<li>Upload the template file to the server</li>
+<li>Save the template locally. It is recommended to keep this saved file around to have a backup for later reference.</li>
+
+<li>Upload the template file to the server: "Templates" - "Edit Templates", use the "Upload new Variant" button to upload your file.</li>
</ol>
<h2>Syntax</h2>
-<h3>Variables</h3>
-
-Variable names are enclosed in two "@" signs and contain only upper-case letters. Any syntax violation results in the template parser interpreting the text as simple non-variable text and dumping it as is. To create a single "@" you can simply enter "@@".<p>
-
-If a variable exists it is replaced by the value that Magic Smoke intended for it. If it does not exist it is replaced by an empty string.<p>
+ODF templates use a pure XML syntax, they are actually ODF files that have been enhanced with some XML tags that allow to create special behavior.<p>
-If a value contains special characters they are replaced by the correct XML sequences (eg. < by &lt;).
-
-<h3>Loops and Loop Variables</h3>
+You have the following syntactic elements at your disposal:
+<ul>
+<li>Variables - allow you to insert data from MagicSmoke into your document.</li>
+<li>Formulas - allow you to format and change those values.</li>
+<li>Loops - allow you to iterate over lists of data.</li>
+<li>Conditionals - allow you to conditionally insert or omit data.</li>
+</ul>
-Some templates use repeating elements. These are expressed as loops. Loops are sections of text that are repeated for every iteration of the internal loop, eg.:
+<h3>Variables and Formulas</h3>
-<pre>
-#LOOP:EXAMPLE
-<markup>this value changes with each iteration: @EXAMPLE:VAR@</markup>
-#ENDLOOP
-</pre>
+Variables and Formulas can be added to any text element by enclosing them in two "@" signs. Predefined variables contain only upper-case letters, you can assign variables with any combination of upper- and lower-case. The parser is case sensitive. Any syntax violation results in empty text. To create a single "@" you can simply enter "@@".<p>
-Each loop begins with a line that starts "#LOOP:" and finishes with the loop name. It ends with a line that contains only "#ENDLOOP". If a loop does not exist this deletes the content in between, if it does exist the content is replicated as often as the loop iterates.<p>
-
-Loop variable names are enclosed in "@", and contain the loop name and the variable name separated by a colon. In each iteration the loop variables are set to the current iterations value. Variables from different loops are handled like unknown variables: they are replaced by empty strings.<p>
-
-Loops cannot be nested.
-
-<h3>Conditional Output</h3>
+If a variable exists it is replaced by the value that Magic Smoke intended for it.<p>
-The output of parsed lines can be suppressed:
+If a value contains special characters they are replaced by the correct XML sequences (eg. < by &lt;).<p>
-<pre>
-#IF:MYVAR < 66
-output if the value is smaller than 66
-#ELSE
-output otherwise
-#ENDIF
-</pre>
-
-A condition consists of exactly two values (both may be variables) and an operator. More complex expressions are not possible at the moment. If the condition evaluates to false, then the output and calculation of all lines until #ELSE or #ENDIF is suppressed.<p>
-
-At the moment the #ELSE statement reverses the output suppression between #IF and #ENDIF. Multiple #ELSEs are possible at the moment, but should not be relied upon in case the logic changes in subsequent versions.<p>
-
-Conditions cannot be nested, but conditions can be embedded in loops or be put around loops. If a condition is put around a loop, it does not prevent the processor from evaluating the loop, only the output and internal calculations are suppressed.<p>
+You can use the usual mathematical operations to add, subtract, multiply or divide. There are a number of functions available to convert values.<p>
+Operators and functions:<br/>
<table frame="1" border="1">
-<tr><td><b>Operator</b></td><td><b>Description</b></td></tr>
-<tr><td><</td><td>lighter than</td></tr>
-<tr><td><=</td><td>lighter or equal</td></tr>
-<tr><td>></td><td>greater than</td></tr>
-<tr><td>>=</td><td>greater or equal</td></tr>
-<tr><td><></td><td>not equal</td></tr>
-<tr><td>!=</td><td>not equal</td></tr>
-<tr><td>=</td><td>equal</td></tr>
-<tr><td>==</td><td>equal</td></tr>
-</table>
-
-
-<h3>Calculations</h3>
-
-Numeric variables allow some very simple calculations in place:
+<tr><td>@123@<td>literal integer value 123 - rendered as number 123
+<tr><td>@"hello"@<td>literal string value rendered as hello (without "quotes")
+<tr><td>@VAR@<td>tries to find the variable VAR and replaces it by its value
+<tr><td>@VAR1 + VAR2@<td>add the value of two variables VAR1 and VAR2, or if one of them is string: concatenate them
+<tr><td>@VAR1 + 9@<td>add 9 to the value of the variable VAR1 and display the result
+<tr><td>@VAR1 - VAR2@<td>subtract the value of VAR2 from VAR1
+<tr><td>@VAR1 * VAR2@<td>multiply two values
+<tr><td>@VAR1 / VAR2@<td>divide two values
+<tr><td>@VAR1 == 12@<td>compare two values for equality, yields a boolean usable in if(...), other operators are != (non-equality), < (less than), <= (less or equal), > (greater), >= (greater or equal)
+<tr><td>@VAR1 || true@<td>logical OR of the value of VAR1 and the literal boolean true, other logical operators are: && (AND), and ^^ (XOR)
+<tr><td>@VAR = 123@<td>assign a value to variable VAR and also print this value
+<tr><td>@int(VAR)@<td>try to convert the value of VAR into a numeric value, succeeds for integers, floats and all strings that contain digits only
+<tr><td>@float(VAR)@<td>try to convert to a floating point number
+<tr><td>@bool(VAR)@<td>try to convert to a boolean (succeeds for numbers: zero is false, anything else is true)
+<tr><td>@string(VAR)@<td>converts a value to string (after this numbers can be concatenated, but not multiplied anymore)
+<tr><td>@strlen(VAR)@<td>returns the number of characters of the variable
+<tr><td>@concat(VAR1,VAR2,...)@<td>concatenate multiple values into one string
+<tr><td>@null@<td>a literal value for "invalid value", cannot be used as variable name
+<tr><td>@true@, @false@<td>literal truth values
+<tr><td>@!true@<td>inverts a boolean value
+<tr><td>@if(BOOL, IFTRUEEXPR [,IFFALSEEXPR])@<td>if the first parameters evaluates to true, the result is the second parameter, otherwise the (optional) third parameter (if omitted: null)
+<tr><td>@isNull(EXPR)@<td>evaluates to true if the parameter is null (invalid)
+<tr><td>@isException(EXPR)@<td>evaluates to true if the parameter yields an exception (i.e. the operation is not permitted on those values or a variable or function is unknown)
+<tr><td>@isExceptionOrNull(EXPR)<td>evaluates to true if the parameter is null or yields an exception
+<tr><td>@catch(EXPR [, IFEXC [, IFOK]] )@<td>if the EXPR yields and exception returns the second paramter (IFEXC) or true, otherwise the third parameter or false
+<tr><td>@toMoney(INTVAL)@<td>converts a value in cents to a normal monetary value, including currency sign
+<tr><td>@toMoneyLocal(INTVAL)@<td>converts a value in cents to a normal monetary value, including currency sign in its localized form
+<tr><td>@toMoneyNL(INTVAL)@<td>converts a value in cents to a normal monetary value, including currency sign in its non-localized form
+<tr><td>@fromMoney(STRVAL)@<td>converts a string representing a monetary value to a number in cents (inverse of toMoney(..); also: fromMoneyLocal(..), fromMoneyNL(..))
+<tr><td>@unix2date(INTVAL [,LOCAL])@<td>converts a numeric Unix time to a human readable date value, per default localized, the optional parameter means: true=localized, false=non-localized
+<tr><td>@unix2time(INTVAL [,LOCAL])@<td>converts a numeric Unix time to a human readable time (without date) value
+<tr><td>@unix2dateTime(INTVAL [,LOCAL])@<td>converts a numeric Unix time to a human readable date and time value
+<tr><td>@cent2str(INTVAL)@, @str2cent(STRVAL)@<td>aliases for toMoney() and fromMoney()
+</table><p>
-<pre>
-@VARONE+11@
-@VARTWO-77@
-</pre>
-
-In the above example the first line will be replaced by the amount of VARONE plus 11 and the second line by the amount of VARTWO minus 77.<p>
-
-For integer variables this works on the plain integer value. For money values it adds/subtracts cents.<p>
-
-More complex calculations can be done with the #CALC statement:
+<h3>Loops and Loop Variables</h3>
-<pre>
-#CALC:TVAR/MONEY:VAR1 * VAR2 + 4
-</pre>
+Some templates use repeating elements. These are expressed as loops. Loops are sections of XML that are repeated for every iteration of the internal loop.<p>
-The above creates the temporary variable "@#TVAR@" that is the product of @VAR1@ and @VAR2@'s content plus 4. It is marked as a monetary value. Please note that the variables are not enclosed in "@".<p>
+If you want to repeat some XML elements multiple times mark them all (using Shift + Click) and then select "Edit" - "Wrap in Loop" from the menu. The loop element will be placed where those wrapped elements were and the wrapped elements will be placed inside the loop. This can be used to loop through text, table rows, or other XML elements.<p>
-Calculations are restricted to the operators below and are always done from left to right - more complex formulas require several lines. Tokens must be space separated. If no type or a non-existing type is requested INT is assumed. All calculations are done using 64bit signed integers. If the processor comes across an illegal token it sets the variable to "error".<p>
+You have to select a loop variable. See below for valid choices. The elements of the loop will be repeated for each iteration of the loop variable, this can be zero, one or multiple times.<p>
-Literals (above: "4") must be integers.<p>
+Loops can be nested, but nesting the same loop variable may lead to undesired results.
-<table frame="1" border="1">
-<tr><td><b>Operator</b></td><td><b>Description</b></td></tr>
-<tr><td>+</td><td>adding</td></tr>
-<tr><td>-</td><td>subtracting</td></tr>
-<tr><td>*</td><td>multiplication</td></tr>
-<tr><td>/</td><td>division</td></tr>
-<tr><td>%</td><td>modulo</td></tr>
-</table>
-
-<table frame="1" border="1">
-<tr><td><b>Type</b></td><td><b>Description</b></td></tr>
-<tr><td>INT</td><td>integer number</td></tr>
-<tr><td>MONEY</td><td>monetary value (the number is interpreted as cents)</td></tr>
-<tr><td>DATE</td><td>a unix timestamp to be shown as date</td></tr>
-<tr><td>TIME</td><td>a unix timestamp to be shown as its time component</td></tr>
-<tr><td>DATETIME</td><td>a unix timestamp to be shown as date plus time</td></tr>
-</table>
-
-<h3>Newline Replacement</h3>
-
-The #SETNEWLINE statement can be used to create a macro that will replace newline in variables:
-
-<pre>
-#SETNEWLINE:</text:p><text:p text:style-name="Text_20_body">
-</pre>
+<h3>Conditional Output</h3>
-The default is a single space character, which can be restored by using "#SETNEWLINE:" without parameters.
+You can wrap elements in a condition. The condition can be any expression described above, excluding the "@" signs - the expression must yield a value that can be converted to boolean (bool, or numeric result).<p>
-<h3>Generic Variables</h3>
+To wrap some elements in a conditional mark them with Shift + Click, then go to the menu and select "Edit" - "Wrap in condition". All elements inside this new condition element will now only appear in the document if the condition expression yields boolean "true".<p>
-There are a few variables that always exist:
+You can make some elements appear on "true" and some on "false" if you insert an "else" tag: mark the element directly before the position where you want to insert the "else" tag and then select "Edit" - "Insert else behind current". It is permissible to insert several "else" tag - each one inverting the one that came before it, but this is not recommended, since it can become quite confusing.<p>
-<table frame="1" border="1">
-<tr><td><b>Variable</b></td><td><b>Description</b></td></tr>
-<tr><td>@TODAY@</td><td>the current date</td></tr>
-<tr><td>@NOW@</td><td>the current time</td></tr>
-<tr><td>@anyloop:ITERATION@</td><td>for an active loop ("anyloop") the current iteration (0..n)</td></tr>
-</table>
+<h3>Calculations</h3>
-<h3>Localization</h3>
+You can insert calculations anywhere in the document. Calculations are formulas that are evaluated, but whose result is not displayed. It makes sense to use them for calculating values that you want to use later on or to split up complex calculations into simpler steps. The syntax is the same as for formulas above, but without the enclosing "@" signs.<p>
-Per default all variables are localized before they get inserted into the document. To suppress localization prefix the variable with a "$"-sign (eg. @$TODAY@ instead of @TODAY@).
+Calculations inside conditionals are only executed if visible tags inside the conditional would be displayed (i.e. the condition is "true", or if behind an "else" tag: the condition is "false"). Calculations inside loops are executed for each iteration of the loop.<p>
<hr/>
<h2>Event Summary</h2>
projects / web/konrad/smoke.git / commitdiff