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.

Report Generation Overview#

Several key points are necessary to understand to fully utilize the Ansys Dynamic Reporting 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 Ansys Dynamic Reporting 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 ADR Nexus server interface and display in web pages

In most cases, users will have used the EnSight Ansys Dynamic Reporting API or the External Python API to place data items in a Ansys Dynamic Reporting database (creating a new Ansys Dynamic Reporting 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 Ansys Dynamic Reporting 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

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.

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

Explicit Anchors#

Ansys Dynamic Reporting 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"}}

Macro Formatting Filters#

The macro substitution engine supports generic formatting. Formatting filters are specified using the vertical bar '|'. For example:

{{name|floatformat:1}}

Will attempt to convert the 'name' tag to numeric form and if successful, format the number using the floatformat filter. In addition to the built-in Django filters, there are some filters provided by Ansys Dynamic Reporting itself. These include:

  • |simple_sprintf:"{name}" - Apply simple numeric formatting. If the input value is not a valid number, the value will be passed through verbatim. The "name" string can have the following values:

    Format name

    Description

    floatdotX

    X is [0-9] which is the equivalent of printf "%0.Xf".

    scientific

    The equivalent of printf "%e".

    scientificX

    X is [0-9] which is the equivalent of printf "%0.Xe".

    sigfigsX

    X is [0-9] which is the equivalent of printf "%.Xg".

    For example, to use scientific notion with 4 digits after the decimal:

    {{name|simple_sprintf:"scientific4"}}

  • |numeric_comp:"{value},{less},{equal},{greater}" - Convert the input value to numeric form and compare it the the numeric representation of 'value'. If the input is less than the value, return the 'less' string. If the input is equal to the value, return the 'equal' string. If the input is greater than the value, return the 'greater' string. If any of the less, equal or greater values are '_', then the original value will be used.

  • |lexical_comp:"{value},{less},{equal},{greater}" - This filter operates the same as numeric_comp, but does not convert the input nor value to numeric form, so all comparisons are done as strings instead of numeric values.

Formatting Filter Chains#

Formatting filters can be "chained" for more complex formatting. It is legal to follow one formatting filter with another. The output of the previous serving as the input for the next. For example:

{{value|numeric_comp:"0.,Too low,_,_"|simple_sprintf:"floatdot2"}}

This example exploits the "non-numeric pass-through" feature of simple_sprintf to customize the display of a number. If the number is greater than or equal to 0.0, the number is passed on to the next filter, otherwise the string "Too low" is passed on to simple_sprintf. For a number like 3.452453, the output would be 3.45. For a number like -1.24, the output would be Too low.

General LaTeX Support#

LaTeX formatted strings are supported in many places in Ansys Dynamic Reporting. 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:

Image

Note the \( and )\ sequences around the LaTeX code.

AsciiMath Support#

Ansys Dynamic Reporting 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:

Image