Report Generation Overview

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.

Report Generation

Several key points are necessary to understand to fully utilize the Nexus report generation system.


    • Reports are generated from collections of Data Items (features of specific data items and their display are covered here)
    • Report templates define how a report is generated and laid out (generator templates and layout templates)
    • Report templates may filter, sort or creatively arrange lists of data items
    • The Nexus Template Editor tool is used to create and edit report templates
    • Data items know how to display themselves within boundaries specified by the layout templates
    • Reports are generated via the web browser Nexus interface and display in web pages


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.

Template Operation

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:

 

    1. Filter the incoming items, potentially removing some items from the list or perform a direct query of the database, merging the new items with the incoming items or replacing them.
    2. Sort the items using various data item fields.
    3. After sorting, one can choose to restrict the item list down to only the first or last item (by default, all items are retained).
    4. Set some properties that should be applied to all of the items.
    5. Begin a layout for how items should be displayed.  This will generate an HTML block that organizes and lays out the HTML generated in steps 6 and/or 7.
    6. If the report template has child report templates, pass the filtered item list to each of the report template children in order. Each child layout will display its results inside of the parent layout.
    7. If the report template has no report template children, draw each of the items in the current layout.  Each Data item is asked to provide an HTML representation of itself that are placed sequentially within the block generated in step 5 according to the template layout rule (e.g. 2 columns, etc).


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).

Layout Templates

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).

Generator Templates

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).

Common Report Properties

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

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.

Property Macro Substitution

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:


  • Data items: if/date, if/name, if/sequence, if/name, if/source
  • Session items: sf/application, sf/date, sf/hostname, sf/platform, sf/version
  • Dataset items: df/dirname, df/filename, df/format


Note: only one level of macro expansion is supported.

General LaTeX Support

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.


AsciiMath Support

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: