Report Generation
The general concept of Report Generation is that a report is created by hierarchical selection of a set of data items that are passed through a hierarchy of report templates. The user will select a root template and a collection of filters to down-select the items in the database that they would like to have considered for display in the report. The database is queried and the list of items is passed to the root template. That template may perform additional filtering, data processing or generate specific layout constructs before passing the items on to its child templates. If a template has no children, it will ask the items that were passed to it to display themselves using the properties, context and layout provided by the parent templates.
Several key points are necessary to understand to fully utilize the Nexus report generation system.
In most cases, users will have used the EnSight Nexus API or the External Python API to place data items in a Nexus database (creating a new Nexus database and launching a server for the database is covered here). The various items in the database are often first reviewed via a web browser. The next step is for the user to use the Nexus Template Editor application to define a hierarchical collection of templates that will be used to create a report. From the template editor or via the web browser interface the user may then generate specific reports, displaying (and interacting with) the resulting content in a web browser.
At the root of every report is a top level report template. This template is handed a collection of Data Items which it processes itself or hands off to child templates. At each template the following operations are performed:
The sequence noted above is applied recursively (step 6) until all of the leaf report templates have been visited. The resulting HTML is displayed in the web browser.
There are two very distinct classes of templates, the Layout and Generator template. Note: there are no restrictions on parent/child relationships between layout and generator templates, other than the fact that the hierarchy must represent a non-looping tree of templates (an acyclic graph).
A layout template is primarily concerned with organizing the display of the HTML representation of items or child templates. They can filter, sort and otherwise organize data items, but they do not generate new data items and cannot modify existing data items (with the exception of being able to set display properties).
A generator template can "generate" new items from collections of input data items. It can perform an aggregation operation, perhaps merging rows from multiple tables into a single table for inclusion in a single plot or graph. It could be used to perform a pivot table operation, collapsing table rows/columns into counts/mean/max values, etc. Generator templates have configurable options to control these operations. At runtime, the generator template is passed the data items to apply the operation to and user-selected template options. The generator may then produce any number of new data items (they need not be of the same type as the input items). These new data items are ephemeral and only exist during the HTML generation phase of report generation. They can be displayed in that specific report, but are not stored in the database and must be re-generated if they are to be included in any other reports (including subsequent redisplay of the report currently being generated).
When an item is asked to display itself, it will always be in the context of a report template. The report template supports a number of properties that control how the item should be presented in a report. These properties are collectively referred to as the display context. Each data item type supports a different set of properties that can be used to control the specific display of a data item. These are documented on the documentation pages specific to a data item type.
Context properties are inherited through the report template hierarchy. For example, if a top level layout template set the Table Item property 'title' to 'HELLO', all Table items whose visual representation is generated by that template or a child template will have their 'title' property set to 'HELLO', potentially overriding the specific value placed on the Table Data Item. This can of course be overridden by a child template which might set the 'title' property to 'GOODBYE'. In any case, contexts are inherited from parent report templates and changes in the context only effect children below the current template.
There are a number of common report properties that are specified implicitly for every report. These include:
|
Property |
Value |
|
date_date |
The current date in the system locale representation. |
|
date_datetime |
The current date and time in the system locale representation. |
|
date_iso |
The current date in ISO 8601 representation |
|
date_year |
The current year |
|
pagebreak |
Defaults to 0. If set to 1, a hint will be included in the generated HTML that suggests that the browser try not to put a pagebreak within the content inside of the template. In practice, this tends to result in a pagebreak being inserted before the layout content when the HTML is “printed” if the content would have extended into the next page. |
|
page_col_pixel_width |
1/12 of a page in pixels. Core columns are laid out in 1/12 page increments. |
|
page_dpi |
An estimate of the number of pixels per inch of the output page. |
|
page_number |
The current report page number. |
|
page_width |
The width of the page in inches. |
|
template_name |
The name of the current template being processed |
There are a number of properties that can be useful when debugging templates. These provide the report designer with additional insight into the operation of template generation, property contexts, etc.
If the property 'item_context_debug' is set to 1, the system will insert the guid, the current list of properties and the item tags into the HTML output whenever an item is rendered. This can be very handy when tracking down context/property management issues.
If the property 'template_timing_debug' is set to 1, the system will report timing information collected then report templates are executed. The output include: the total time spent running the template (includes filtering, sorting and children), the amount of time spent executing data item filters in this specific template and the amount of time spent executing the data item sort in this specific template.
Many data items and report templates types support "macro" substitution via properties. For example, if the property "Hello" is set to "How are you?" in the report context and an HTML item contains the text "<h1>Hello is set to: {{Hello}}</h1>", the resulting page will render 'Hello is set to: How are you?' with heading 1 formatting.
Macros can also be used in properties themselves and in that situation, the tags on the current item can also be included in the macro. For example, if the Table Item property 'plot_title' is set to:
My {{my_tag}} Can Use Macros
and the table item being rendered has the tag my_tag='Cool Title' set on it, the title for the plot will read: 'My Cool Title Can Use Macros'.
Tags on the item's associated session and dataset objects can be used. To access the value of a session tag, use the syntax: {{s/session_tag_name}}. For a dataset tag, the syntax is {{d/dataset_tag_name}}. For example, if the dataset associated with an data item has the tag "variable=pressure X=1", the macro string: '{{d/variable}} {{d/X}' will return 'pressure 1'.
Fields on data items, sessions and datasets may also be accessed. The syntax {{if/data_item_field}}, {{sf/session_item_field}} and {{df/dataset_item_field}} are used to access these fields. The following fields are supported:
Note: only one level of macro expansion is supported.
Nexus allows for the report designer to be able to embed links between different portions of the report. This is done by embedded explicit anchors and links in the report. This is performed using the nexus_anchor and nexus_link macros. nexus_anchor specifies a named link target. One or more nexus_link macros can point to the same named target (the 'name' options to the macros make this link).
{{name|nexus_anchor}}
{{name|nexus_link:"link text"}}
LaTeX formated strings are supported in many places in Nexus. If the text is to be displayed in a table plot, the syntax is a little different. In common text, one can use the inline notation by wrapping the LaTeX with the \( and \) character sequences. For example, a custom HTML header that uses this string:
<h2>Inline LaTeX: \(\sqrt{(n_\text{c}(t|{T_\text{early}}))}\), see!</h2>
is displayed in a panel template header as:
Note the \( and )\ sequences around the LaTeX code.
Nexus supports the proper display of equations formatted using the AsciiMath style. In common text, one can use the inline notation by wrapping the AsciiMath expression with the ` characters. For example, a custom HTML header that uses this string:
<h2>Inline ASCIIMath: `sum_(i=1)^n i`</h2>
is displayed in a panel template header as:
