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 Nexus as a table.
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. Unlike the layout template case, it does not filter the list of items passed to children of the generator. Instead, the item(s) produced by the generator are merged into the input item list and the result is passed on to the generator template children. The "Generated Items" option menu determines how the generator produced items are merged into the input data itme list. The "Filter mode" allows the filter to be applied directly to the raw database instead of to the input data itme list, with the resulting items either replacing the incoming items or augmenting the data item list.
In any case, incoming data items are filtered down by the item filter and that list of items is passed to the generator. The generator then produces some number of additional items. The 'Generator items' option menu controls how these new items are merged with the filtered 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.
The UI for the filter editor is outlined here.
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.
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.