When exporting data to HTML format, it would be very nice to have a highly customizable output, which can be used directly in front-end without any further tuning.
This can be reached by using a HTML template file. The template file is a regular HTML file, but with some dynamic areas which are filled with data or HTML elements during the export process. These dynamic areas are hidden in HTML comments, so the file looks valid and can be correctly displayed in Web browsers or HTML editors.
Using HTML template gives you the following great advantages:
- having the output HTML document with embedded database data, which looks exactly as you need;
- filling the target document in several export steps, using different source datasets;
- aggregating the data;
- using expressions which return HTML tags; with this feature, you will be able to conditionally format the data, insert comments, or even change the structure of the document;
- using expressions which produce new expressions; these new expressions will be calculated on the next export step.
Notes
- Template file encoding should be ANSI or UTF-8.
- If HTML export process uses a template, all export option will be ignored except template options, document title, row count limit, and row range.
Dynamic data in HTML templates are based on the following elements:
1. Pascal-like expressions which are calculated "on the fly" before they are outputted to target document. These expressions can extract data from database, do arithmetic, logical or text operations, or get some other information, which is known at the exporting application level. The result of expression is embedded into the target HTML document instead of the expression. The expression can also generate new HTML tags, which can be useful for conditional formatting the embedded data.
2. Dynamic image tags. They allow to extract images from the current dataset and build HTML <img> tags. Note: if you don't need to extract images from database, but need to generate image tags dynamically, use expressions instead of dynamic image tags.
3. Loops. Such a loop outputs all HTML elements inside it as many times as count of the loop iterations. The expressions and dynamic image tags inside the loops are calculated and prepared before the outputting loop contents to target document. Note: nested loops are not allowed.
Writing dynamic expressions
Dynamic expression must be declared as a parameter of vle_expr macro, i.e. inside the parentheses following vle_expr keyword. All the construction, in its turn, must be placed inside a HTML comment. The HTML comment should not contain any other elements except one vle_expr macro. After calculation, the result of the expression replaces full parent dynamic area, including comment. If an error occurs during the calculation, the error message is placed inside the comment instead the expression.
Example of the dynamic area that uses an expression:
<!--vle_expr(dataset_field_val(1, 'ProductCode'))-->
Here, dataset_field_val(1, 'ProductCode') is the expression to calculate.
For more information about writing the expressions, please see Expression Engine topic.
Preparing loops
Dynamic area for loop start must be declared using vle_loop_start macro. All the construction, in its turn, must be placed inside a HTML comment. The HTML comment should not contain any other elements except one vle_loop_start macro.
The vle_loop_start macro has four parameters:
1. Export step number (Integer). Export procedure will ignore this loop if this step number does not match the step number, specified in export options. See note 6 here.
2. Loop type (String). Possible values: 'each_row_in_dataset' (loop will iterate through all rows in the current dataset), 'for' (loop will iterate from index, specified in the second macro parameter, to index, specified by third macro parameter).
3. Loop start index (Integer). Can be a constant or expression. Ignored if loop type is 'each_row_in_dataset'.
4. Loop end index (Integer). Can be a constant or expression. Ignored if loop type is 'each_row_in_dataset'.
Examples:
<!--vle_loop_start(1, 'each_row_in_dataset', 0, 0)-->
<!--vle_loop_start(1, 'for', 1, to_number(format_date_time(date, 'dd')))-->
Dynamic area for loop end must be declared using vle_loop_end macro. All the construction, in its turn, must be placed inside a HTML comment. The HTML comment should not contain any other elements except one vle_loop_end macro.
The vle_loop_end macro has no parameters.
Example:
<!--vle_loop_end-->
All HTML elements and expressions between vle_loop_start and vle_loop_end macros are prepared and outputted to target document in each loop iteration.
Writing dynamic image tags
Dynamic area for creating an image tag must be declared using vle_make_img_tag macro. All the construction, in its turn, must be placed inside a HTML comment. The HTML comment should not contain any other elements except one vle_make_img_tag macro.
The vle_make_img_tag macro has nine parameters:
1. Export step number (Integer). Export procedure will ignore this dynamic area if this step number does not match the step number, specified in export options. See note 6 here.
2. Field name (String). Specifies a field name from the current dataset, from which to extract images.
3. Target image format (String). Possible values: 'png', 'jpg', 'gif', '<autodetect>'. In the latter case, the target image format will be determined (if possible) from the database. Can be an expression.
4. Target folder for images (String). If it is left blank, the image will be saved to the folder of target HTML file. If it equals to '<auto>', image will be saved to the folder with name as the target HTML file (without extension) plus the _files suffix. Can be an expression.
5. Basic name for image file name (String). Can be an expression.
6. Target image file name (String). This should not be full file path. If it equals to '<auto>', the file will be named automatically. Can be an expression.
7. Content of alt attribute of img tag (String). Can be an expression.
8. Image width (Integer). If it equals to -1, actual image width will be used. Can be an expression.
9. Image height (Integer). If it equals to -1, actual image height will be used. Can be an expression.
See also
