Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.



Data Keys

The most critical part of any report is data.  Without data, there is nothing to report!  In In the Reporting Module, we use Data Keys and (optionally) Keychain Expressions to feed the report from the data sources. The Keys to pull values from data sources and show them on the report. In simple terms, Data Keys are placeholders for your data. The simplest reference to data is a simple Data Key.  A Data Key is a reference that points to the data it represents. At  At report generation time, these keys resolve to the values (or sets of values) provided by the data source. In simple termsAdditionally, Data Keys are placeholders for your data.

Expand
titleData Key Example
If we created a data source named Countries, we can experiment with Data Keys to see how they resolve. Create a table in the Report Designer.  Drag the Countries datasource from the Key Browser to the Data Key field in the Design Panel as shown below. In the Property Inspector, you can also see that we enabled the Table's Header, and typed header descriptions for each column we wanted to display. Next, we dragged and dropped keys from the Key Browser into the Details columns.  We can tell which items in the Report Designer reference data keys because they are surrounded by "@" symbols.
Code Block
languagejs
title"Countries" Data Source
Country, Capital, Population
"China", "Beijing", 20693000
"Japan", "Tokyo", 13189000
"Russia", "Moscow", 11541000
"South Korea", "Seoul", 10528774
"Mexico", "Mexico City", 8851080
"Italy", "Rome", 2858104
"Germany", "Berlin", 3520000

Image Removed

Click the Preview Panel, to see a simple table that neatly displays a row for each entry in Countries datasource. Looking at the XML, you can see that the Countries datasource sent a single row of data for each entry.  You'll notice that the headers are printed exactly as they were in the Design Panel.  As an experiment, you can surround these header values with "@" symbols to see what happens.

Image Removed

Data Key Usage

All text fields in Report Design elements are able to resolve Data Keys.  In fact, you can freely mix plain text and data keys anywhere. In our table example above, we could substitute "@Population@" with "@Population@ people" and the data key portion would be swapped out for the appropriate data.  This can be a very powerful feature when trying to create reports. For example, you could have a text field at the bottom of a report that displays "@Page@ of @PageMax@".   If for some reason your Data Key can't be found, your report will display a Substitution String (which defaults to "<N/A>" but can be configured in the Report's Property Table by selecting the Report in the Project Browser).   

For more information on Data Key syntax, lease see the Key Calculations page. 

Data Keys as Paths

Data Keys are relative, and use 'dot notation' to reference children.   Meaning, if we have a nested data structure, we can use Data Key paths (also known as Keychains) to reference the nested data.  In the key browser image below, we have a nested data source called Downtime.  Downtime contains a number of columns, and then contains a reference to additional data called runInfo.  If we wanted to access the highlighted operator data, we could use the keychain dot notation in the Designer - @Downtime.runInfo.operator@ .  Nested datasources are outside the scope of this page, but you can learn about Datasource nesting in the Nested Queries section.

Image Removed

Array Index of Data

You can reference an individual object in a list using standard array indexing syntax (brackets) like this: @Data[0].firstName@, where Data is a data source that contains a child data key named firstName. In this case, we would be accessing the first firstName in the set of data.

On_this_page

 

 

may be used as expressions, which are referred to Keychain Expressions. 

As you add Parameters and Data Sources to the Data section of your report, they will appear in the Key Browser's Parameters and Datasources folders. 

Image Added


On_this_page

 


Data Keys on the Report

Data Keys are enclosed in the "@" character when utilized by components in the report. They may be typed manually, or dragged directly from the Key Browser. 

Keys that contain a single value will create a Text Shape when dragged onto the report. 

Image Added


Keys that represent datasets will create a Table component, and configure the Data Key property to use the key. 

Image Added


Built-In Keys

Built-In Keys provide a lot of useful information on your report at a glance. The Built-In keys are found in the Key Browser. Expand the Built-In folder and you'll see all the default keys, including a Report folder. The keys in the Report folder are specifically related to the report: Gateway name that the report is located in, report name, folder path from the Project Browser to the report, and the Timestamp of the Gateway.  The other Data Keys are related to information you may want to add to a report like the date you are viewing or printing the report, page number, number of total pages, and more.

Here's a screenshot of the Key Browser showing all the default Built-In Keys that can be used on a report.

     

The tables below show the Built-In Report Data Keys and Built-in Data Keys along with a brief description of each key. 

Built-In

Report

Data

Keys

Key Description

KeyDescription
Key Description
Report

This key has multiple sub-keys that provide meta-data about the report.

Key Description 
GatewayName of the Report's Ignition Gateway
NameName of the Report
PathPath to the Report in the Project Browser
TimestampThe Gateway's current timestamp

Built-In Data Keys


DateThe current date/time
PageThe current page
PageMaxThe total number of pages in the generated report
Page of PageMaxShows current page number and the total number of pages in the report
PageBreakThe number of explicit page breaks encountered
PageBreakMaxThe total number of explicit page breaks in generated report
PageBreakPageThe number of pages since last explicit page break
PageBreakPageMaxThe total number of pages in current explicit page break
RowShows the current row number. Must be used in a table

 

In the Design Panel, simply drag any of the data keys anywhere on to your report. Move them around on your report until you find the best location. The Preview Panel shows exactly how the report will look when it is generated. If you don't like the way it looks, go back to the Design Panel to modify it.


Scroll HTML Exporter Ignore


Iulink
URLhttps://inductiveuniversity.com/video/built-in-keys
NameBuilt-in Keys

 

Design Panel

Image Removed

Preview Panel

Image Removed

 




Show Calculations Property

Another important property is Show Calculations. In the Key Browser, set the Show Calculations property to 'true' and expand Datasources.  You'll see the 'count' key was added under Datasources. A 'count' is the total number of rows in your Datasource. Expand your columns and you'll see that a number of built-in keys were added. For each column you can calculate the following: value, total of all the values in that column, average, maximum value, minimum value, running total, and running average. These keys are available for each column that you bring into your table once you set Show Calculations to 'true'. The Show Calculations property can come in pretty handy once you're familiar with how it works.
Image Removed
Show Calculations is not recommended for text strings, but is great for showing numerical calculations.

Expand
titleShow Calculations Example

By dragging any one of the calculation keys from the Key Browser on to a report, you will see the result of that calculation in the Preview Panel using the dataset below.

In this example, we'll use the following dataset containing several cities along with their populations to show how the Show Calculations property and associated keys work.
Image Removed
From the Report Components palette, drag a table into the Design Panel. Next, drag your datasources to columns in your table.
Image Removed
Image Removed
In the Key Browser, set the Show Calculations property. You'll notice that the 'count' key was added under Datasources and the calculation keys were added to each column in your datasource. Expand any of your datasources to see see the calculation keys.
Image Removed
In the Design Panel, drag any of the calculation keys to your table. You can see we randomly placed the 'max' and and 'average' keys on the report. The calculation keys were converted to keychain expressions (i.e., '@Countries.max.Population@,' and '@Countries.average.Population@') in the report. One thing to keep in mind if you are using the Show Calculations property, is you may need to do some formatting of your table rows and headers so your calculations are displayed nicely on your report. You'll notice that Header and Summary rows were added. The Summary row contains the '@total.Population@' so it will look nice in the report.
Image Removed
Once you add your calculation keys to your table, go to the Preview Panel to see what your report looks like. It's not unusual to have to go back to the Design Panel to tweak the formatting. If you don't like the number format, you can go to the Property Inspector and change the format of the Number property. Number and Date formats are discussed later in this page.
Image Removed

 

 

Use Dynamic Data Keys

Dynamic Data Keys allow you to make changes to a report allowing you to tailor a report to a specific need or requirement at a given time. You can bind properties on Reporting components to parameters. It's as simple as dragging-and-dropping the parameter to the property, or right clicking the property and clicking on 'Use dynamic data key'.

   Image Removed

Dynamic keys are very powerful. You can bind report parameters to components on a window allowing you to change a report based on a specific need.

Date and Number Formats

Date Format and Number Format properties accept Dynamic Data Keys. String values should be used for these properties, such as "#0.00##" for number format.

Each property has several predefined format strings to choose from for displaying Dates and Numbers. Click on the icon on the right side of the property name to select a format string, and press OK

Image Removed

 

Scroll HTML Exporter Ignore
Iulink
URLhttps://www.inductiveuniversity.com/video/use-dynamic-data-key
NameUse Dynamic Data Key

 

will add several aggregates to each key. These allow your reports to easily display things like the total of a key. These calculations are typically used in the summary row on the Table component. 

Once Show Calculations is enabled, the Key Browser will refresh, and each key will be expandable. Expanding a key will show the available calculations. 

Section


Column
width400px

Show Calculations Disabled

Image Added


Column

Show Calculations Enabled

Image Added


Calculation Keys work like any other key: they may be dragged onto the report, and utilized in Keychain Expressions.


Dynamic Data Keys

Normally, Data Keys may only be used to display the value of a key, such as the Text property on a Text Shape component. However, they can not be used in the same manner to modify other properties on a report component. Instead, you can utilize Dynamic Data Keys. 

Dynamic Data Keys allow you to use the value of a Data Key on a non-string property. With Dynamic Data Keys, you can modify properties on report components, such as the background color or width, based on the value of a key. This is very similar to the binding system used by components in the Vision Module.


Scroll HTML Exporter Ignore


Iulink
URLhttps://www.inductiveuniversity.com/video/use-dynamic-data-key
NameUse Dynamic Data Key

 



Configuring a Dynamic Data Key

There are two ways to configure a dynamic data key. Note that the syntax of keys differs in Dynamic Data Keys: the "@" are omitted, as demonstrated below.

Drag-and-Drop

The easiest approach is by simply dragging a data key from the Key Browser directly to a property on a report component. 

Image Added

Right-Click

  1. With a report component selected, look in the Property Inspector, and left click on the name of a property you wish to place the dynamic data key on. 

  2. Once selected, you can right-click on the property name and a menu will appear.

  3. Click on the Use dynamic data key menu item. 

    Image Added

  4. This will place a dynamic data key on the property. An icon of a link (Image Added) will appear next to the property name, and a default key will be applied to the property. 

  5. Next we will want to override the default value with one of the keys from the Key Browser. Simply left click on the value field and a magnifying glass (Image Added) icon will appear.

    Image Added

  6. Click on the (Image Added) icon. From here a popup of available keys will appear. Select the key you wish to use, and then click OK. 



Data Key Usage

Data Keys as Paths

Data Keys are relative, and use 'dot notation' to reference children.  Meaning, if we have a nested data structure, we can use Data Key paths (also known as Keychains) to reference the nested data.  In the key browser image below, we have a nested data source called Downtime. Downtime contains a number of columns, and then contains a reference to additional data called runInfo.  If we wanted to access the highlighted operator data, we could use the keychain dot notation in the Designer - @Downtime.runInfo.operator@Nested data sources are outside the scope of this page, but you can learn about Data source nesting in the Nested Queries section.

Array Index of Data

You can reference an individual object in a list using standard array indexing syntax (brackets) like this: @dataSource[0].columnName@, where "dataSource" is a data source that contains a child data key named columnName. Assuming a data source with the values listed below, we can retrieve the value of "Second Row" by specifying index 1 and the column stringValue: @static_data[1].stringValue@


Code Block
languagepowershell
titlestatic_data Example
indexColumn, stringValue
0, "First Row"
1, "Second Row"
2, "Third Row"
4, "Fourth Row"


Section


Column
width300px

Image Added


Column

Image Added


Colors in Expressions

Colors may be references in Keychain Expressions in several ways.

Section

Colors in Hexadecimal

First, hexadecimal case-insensitive color codes may be used. The code must be wrapped in quotation marks to be evaluated correctly. Note that the color change will only appear when the report is executed. The easiest way to test the expression is to switch to the Preview Panel.

Below we see a Blue hexadecimal code of "0000FF" is used on the Fill Color of a Rectangle. The Fill Color on the Rectangle was originally set to White. Because the expression will not evaluate in the Design Panel, the Rectangle will appear as a White color.

However, switching over to the Design Panel will generate the report, and evaluate the expression. This in turn returns a Blue Fill Color. 

Column
width470px

Image Added


Column

Image Added



The 7th and 8th digits may be added to specify an alpha channel, or the opacity of the color: 00  is fully transparent, while  FF  is fully opaque. Below, we see a similar rectangle overlapping an ellipse, but with a code of  "0000FF40" . This represents ~25% opacity, so objects behind the rectangle will be visible, and the fill color will only be slightly opaque. 

Image Added

Section

Parameters as Colors

You may also leverage Report Parameters to specify colors. This typically involves creating a parameter with a string datatype, and using the color expression function. Once created, you can simply create a dynamic data key reference on the property by dragging the parameter from the Key Browser onto the property in the Property Inspector. This way, you can have several components use the same color, and modify the color in a single location. 

Column
width400px

Image Added


Column

Image Added


Strings as Colors

Additionally, case-insensitive string color names may be used to return a color. Again, the value must be wrapped in quotation marks. 

Image Added

The following string values may be used:

Panel
titleString Value Color Reference


ValueExampleValueExampleValueExampleValueExampleValueExample


"beige"


Panel
bgColor#F5F5DC




"gold"


Panel
bgColor#FFD700




"lavender"


Panel
bgColor#E6E6FA




"pink"


Panel
bgColorpink




"tan"


Panel
bgColor#D2B48C




"black"


Panel
bgColorblack




"goldenRod"


Panel
bgColor#DAA520




"lightGray"


Panel
bgColorlightGray




"plum"


Panel
bgColor#DDA0DD




"teal"


Panel
bgColor#008080




"blue"


Panel
bgColorblue




"gray"


Panel
bgColorgray




"lime"


Panel
bgColor#00FF00




"powderBlue"


Panel
bgColor#B0E0E6




"violet"


Panel
bgColor#EE82EE




"brown"


Panel
bgColor#A52A2A




"green"


Panel
bgColorgreen




"magenta"


Panel
bgColormagenta




"purple"


Panel
bgColor#800080




"white"


Panel
bgColorwhite




"crimson"


Panel
bgColor#DC143C




"hotPink"


Panel
bgColor#FF69B4




"maroon"


Panel
bgColor#800000




"salmon"


Panel
bgColor#FA8072




"yellow"


Panel
bgColoryellow




"cyan"


Panel
bgColorcyan




"indigo"


Panel
bgColor#4B0082




"navy"


Panel
bgColor#000080




"silver"


Panel
bgColor#C0C0C0




"clear"

Zero opacity. Similar to disabling the Fill property.



"darkGray"


Panel
bgColordarkGray




"ivory"


Panel
bgColor#FFFFF0




"olive"


Panel
bgColor#808000




"skyBlue"


Panel
bgColor#87CEEB






"fuchsia"


Panel
bgColor#FF00FF




"khaki"


Panel
bgColor#F0E68C




"orange"


Panel
bgColororange




"red"


Panel
bgColorred







 

 


Next_link