Substitution Keys
| Top | Previous | Next |
|
|
|
The most important part of any reporting system is data substitution. Ignition Reporting uses a familiar mail-merge paradigm, allowing the user to intermingle keys with static text. Keys are delineated by "@" symbols, for example: @Date@ or @myVariable@. An example of mixed keys and text, might be "@Page@ of @PageMax@", perhaps resulting in the text "1 of 10". An interesting thing about keys is that they can be @anything@! You can type any string between two "@" symbols and the Reporting engine will treat it as a key. At run-time it evaluate the key to your dynamic property or a built in key. The syntax for keys follows the rules of Java expressions, described here If a key cannot be evaluated it will return the String for Null property on the document inspector (set to "N/A" by default) .
Your keys are the most important data in the report! Browse through them with the Keys Attribute Panel. Read more about dynamic properties the way to bring data into the report.
The following builtin keys may be typed or dragged from the keys panel
Keys that return: dates, currency, or numbers can be formatted by highlighting then using the formatter.
You can reference an individual object in a list using standard array indexing syntax (brackets) like this: "@Data[0].firstName@".
Aggregates (totals, min/max, average, count) The Keys Browser contains a list of built-in keys at the bottom of any given list: total, average, min, max and count. These allow the user to easily specify aggregate calculations on a set of objects. Suppose we want to see @Data.total.revenue@ or the @data.min.runtime@ or perhaps just @data.count@. When performing an aggregate calculation on the objects in a table the DataSet Data is set as the Dataset Key so you can use @total.revenue@ instead of @Data.total.revenue@.
An aggregate calculation will result in null if any of the individual values are null (rather than return a value that is technically incorrect). You can work around this by implementing a derived method that returns a default value if the original attribute is null and aggregating using that key/method. Also, most of the aggregates contain a second version ("total2") that assume that null is equal to zero.
The "count" and "countDeep" keys The count keys tell us how many objects are in a given list or group. This is most commonly used for tables with one or more levels of grouping. If, for instance, you have a table of Movies grouped by their studio and you add the @count@ key to the studio details, it will display the number of movies for each studio. So it might make sense to have a text field with "@studio.name@ has released @count@ movies" (Warner Brothers has released 15 movies). The count key only counts the next level of grouping. If you have multiple levels of grouping and want to count all the root entities use the countDeep key. Suppose you have movies grouped by their category and their studio, and want to display a top level summary. You could use: "@studio.name@ has released @countDeep@ movies in @count@ different categories" (Warner Brothers has released 36 movies in 7 categories).
Heritage Keys (Running Totals, percentage totals) There is an additional set of keys in the Attributes Browser which are used to access upper level groups: Up, Running, Remaining. @Up.count@ would tell us how many objects are in the current level of grouping. The text field "Row @Row@ of @Up.count@" might show "Row 1 of 5". By doing some simple arithmetic and using the "Up" key, we can calculate a percentage total: "% Total: @revenue/Up.total.revenue@" The running key references a virtual array containing all of the objects processed thus far in a lower level grouping. This is useful to get a running total. For example, in a ledger: "Credit/Debit: @amount@ Current balance: @Running.total.amount@" The remaining key is conceptually the same, but results in a virtual array of remaining objects.For example: "Credit/Debit: @amount@ Remaining Activity: @Remaining.total.amount@"
|
