Generator Templates#
The generator converts a collection of items into other items. For example, it can convert an image item into an HTML representation of the item. It can convert a collection of vectors into a table. It can convert a table into HTML. It could be used to perform a table pivot operation, converting a vector into a mean value, etc. A generator has configurable options to control these operations and generator parent template passes a list of data items to apply the configured operation to those items.
There are a number of different types of generators available:
Table Merge Generator - takes a collection of tables and merges the rows and columns into a single output table.
Table Reduction Generator - fold the rows and columns of a table into new rows/columns via various data reduction operations (e.g. counting, maximum/minimum, averages, etc).
Table Row/Column Filter Generator - extract or remove a collection of rows/columns from a table by selecting specific rows and/or columns.
Table Value Filter Generator - extract or remove rows/columns from a table using values in another row/column as a filter.
Table Row/Column Sort - sort the rows/columns of a table using the values in a column/row or the column/row labels.
SQL query generator - runs SQL queries against an SQL or PostgreSQL database, bringing the result into Ansys Dynamic Reporting as a table.
Tree Merge Generator - combines multiple tree items into a single, multi-column tree item.
Common Generator Options#
All generator templates share a number of common options. These options can be configured using this portion of the template editor dialog:
Data item filtering for a generator differs fundamentally from that for a layout template. The filtering options control which data items will be processed by the generator. The filters do not filter the list of items passed to children of the generator (unlike the layout templates). Instead, item(s) produced by the generator are merged into the input item list and the result is passed on to child templates of the generator template.
As noted, the item filter selects a subset of the incoming data items that the generator is applied to. The "Filter mode" allows the filter to be applied directly to the raw database instead of to the input data item list, with the resulting items either replacing the incoming items or augmenting the data item list. The generator then produces some number of additional items based on the items selected by the filter. The 'Generator items' option menu controls how generated items are merged with the original data item list that was passed to the generator. The 'Append' option causes the generated items to be added to the list. The 'Replace' option causes the item list to be replaced with the items produced by the generator. The resulting list of data items is passed on to any template children of the generator template (or if the template has no child templates, they are rendered sequentially into the output).
When a generator produces new items, the tags on the items are generally preserved from the input items. The 'Append template tags to new items' causes the generator to walk all of the tags on the generator itself and add/replace tags on all of the generated items to match those on the generator.
For example, consider a Tree Merge Generator where the specified item filter does not select any generator source items. The generator does not see any inputs to process and will not generate any new items. With the "Generated items", "Append" option selected, while the generator won't generate any new tree items, the output will still show all the items inherited from the parent template. This is because the "Generated items" option merges the (original) input item list and the (empty) output item list produced by the generator. Under these conditions, the generator is effectively a 'null' operation. This configuration can be useful as it allows generator pipelines to be conditionally applied to a filtered list of items, informing child layout templates.
Filtering#
The UI for the filter editor is outlined here.
Properties#
After the collections data items have been filtered the layout can override various properties which control specific display attributes. The "Edit properties..." button allows this list to be edited. The editor is simple and looks like this:
The dialog allows for new properties to be added and existing ones to be removed. There are no inherent limits on the names of the properties other than they cannot include spaces or punctuation other than the '_'. Generic properties can be used in the macro substitution mechanism described here to customize various displays. Predefined properties also exist and are documented with the specific data items, but right clicking on the property field will bring up a list (organized by item type) of the various properties and in many cases, simple examples of the values that can be changed.
Sorting#
The filtered collection of items can also be sorted using a multi-key sort to change the order that the generator encounters the various items. This feature might be used to control the order of output rows in a table aggregation operation for example. The dialog to set the sorting order can be accessed using the 'Edit item sorting rules...' button.
The buttons in the lower left corner allow one to change the number of fields to use as keys. Right clicking on a key allows one to select specific Item, Session or Dataset keys. Sorting is performed top to bottom in the dialog, so in the example, items are primarily sorted by the dataset format field and in cases where they are the same, the item date field is used, etc. The order can be changed by dragging the fields up and down within the dialog. Individual keys can be sorted in different directions by clicking on the triangles to the left of the key names.
Once a specific sorting sequence has been established, the 'Sort Selection' option allows for the template to further down-select the list of items to only the first or last item in the sorted sequence. This can be useful when designing a report that displays the most recent values for some piece of data.