AX1741

Using the IconConfig data source with Fixed Report components

Fixed Report components can be configured to display icons in the report, along with the data. The icons can be for decoration, or used as conditional indicators, or used to trigger an action.

You can create an IconConfig data source in order to define a list of icons and their corresponding colors, conditions, and actions. You can then reference the data source in either the Icon column or the HoverActions column of the FixedReportColumns data source, in order to display the icons in the report column defined by that row of the data source.

Creating the data source

The tags for the IconConfig data source are as follows:

Primary tag

[IconConfig;DataSourceName]

The DataSourceName identifies this data source so that it can be used in a FixedReportColumns data source. Data source names must be unique within a file and must start with a letter. Names can only contain letters, numbers, and underscores. Names are validated when the file is saved; an invalid name will prevent the save.

The placement of this primary tag defines the control column and the control row for the data source.

  • All column tags must be placed in this row, to the right of the tag.
  • All row tags must be placed in this column, below the tag.

Row tags

[Icon]

Each row flagged with this tag defines an icon to display in the report.

Column tags

[IconName]

The name of an icon to display in the report. The valid icon names are the same names allowed for symbols in Formatted Grid components (as well as Label and Button components). You can use any of these features to look up the desired icon name.

TIP: You can right-click the cell and use Insert Formatted Grid Tag > Symbol, then use the Tag Editor to select a symbol name (such as fa-file-o for a file symbol). You can then copy and paste the symbol name out of the Tag Editor and into the [Icon] column.

[Color]

Optional. A color for the icon. You can specify the color using a web-standard color name or a hexadecimal color code. For an example list of colors and hexadecimal codes, see: http://www.w3.org/TR/css3-color/#svg-color (external link).

You can also use an Axiom style color, such as P6 or A32. The skin of the Axiom form must be set to Axiom2018 in order to use the style colors.

Colors only apply when the data source is used in the Icon column of the FixedReportColumns data source. Colors are not supported for use with hover icons.

[Condition]

Optional. A condition to determine whether the icon displays. The condition is evaluated per row in the report.

For example, imagine that you want to display a green circle to indicate a value that is within acceptable parameters, and a red circle to indicate an unacceptable value. You can set up two different icon rows in the data source (one with the icon set to green and the other with the icon set to red), and set a different condition for each icon so that each row in the report will evaluate to either green or red. One condition could be Difference <= 1000 and the other Difference > 1000 (where Difference is the name of a calculated column in the report).

The condition can use any of the operators that are valid for use in report calculations, as well as the following: greater than (>), greater than or equal to (>=), less than (<), less than or equal to (<=), equals (=), and does not equal (<>). You can use AND or OR to create compound statements. The condition can reference any column that a report calculation can reference.

[Action]

Optional. An action to perform when a user clicks on the icon. This column can contain either of the following:

  • A URL (starting with HTTP/S) to open a web page, Axiom form, or web report.

  • A document shortcut (document://filepath) to a file in the Axiom Software file system.

  • A command to execute when the icon is clicked. For example, you can use the Dialog Panel command to open a dialog with more information about the current row.

    You can use any command that is available for use in forms, though, some commands may not make sense to execute in this context and may not work as expected. To create the command statement, right-click the cell and select Axiom Wizards > Command Wizard. You can then use the Shortcut Target to select a command from the Command Library and configure its shortcut properties, just like you would for a Button component.

For more information on using icons to perform dynamic actions, see Using the current row value in the icon action.

[Confirmation]

Optional. A confirmation message to display before performing the assigned action. The user can click OK to continue, or Cancel to cancel the action and return to the file.

[UseNewWindow]

Optional. Specifies whether a URL action is opened in a new window (True/False). If omitted or blank, True is assumed.

This property only applies when the action is a URL. When the action is a command or a document shortcut, you must use syntax within the command or document shortcut to indicate whether a target document opens in a new window.

[Tooltip]

Optional. Tooltip text to display when the user hovers their cursor over the icon. If the icon has an action, this text should tell the user what action is going to be performed.

NOTES:  

  • The primary tag must be placed in the first 500 rows of the sheet.
  • Formulas can be used to create the tags, as long as the initial bracket and identifying keyword are whole within the formula. For more information, see Using formulas with Axiom feature tags.

Using the current row value in the icon action

You may want to reference the current row value when performing an icon action, so that the action dynamically adjusts for the current row. The way that you do this depends on whether the row action is a URL or a command from the Command Library.

URL actions

If the action is a URL, you can optionally reference the current value of the cell by using the syntax {value} in the URL. This means that the icons must be displayed in the same column that holds the value that you want to reference.

For example, imagine that you want users to be able to launch the Process Routing page for each department listed in the report, so that they can see the current process status for that department. You can assign the icon data source to the column that shows Dept.Dept, and reference the {value} in the URL as follows:

https://mycompany.axiom.cloud/process/16682/planfile?planvalue={value}

This value will be resolved for each row of the report so that the URL references the appropriate value. For example, if the department value in a row is 40000, the URL will be resolved as follows: https://mycompany.axiom.cloud/process/16682/planfile?planvalue=40000

IMPORTANT: Generally speaking, the URL action is only useful if it is a static URL. If you want to use a function such as GetFormDocumentURL to generate a URL, note that the function is not recalculated when the icon is clicked. This means that a function cannot be used to dynamically generate a different URL. If you want to open an Axiom form or a web report using an icon, and you need the target document to change in some way based on the current row, you can use the NavigateToReport command instead.

Command actions

If the action is a command, you can optionally reference any value for the current row, by using the ActionRowValue column in the FixedReportColumns data source.

When the user clicks on an icon to perform a command, the values for the current row are written back to the ActionRowValue column. For example, imagine that a row of the report is configured to show Revenue. When a user clicks on an icon in that row, the value Revenue is written back to the ActionRowValue field for the HeaderColumn row in the FixedReportColumns data source. Additionally, values are written back for all other rows in the data source with assigned table columns or calculations. These values can then be referenced by the command's shortcut parameters directly, or by something else that the command impacts.

NOTE: The value written back to the data source for the HeaderColumn row is the label for that row. If the row values are defined using a Table.Column, but you have chosen to display each value using an additional label column, then the label value is written back instead of the column value.

For example, imagine that you want to use the Dialog Panel command to open a dialog that shows more information about the current row. The child components of the Dialog Panel and the relevant data queries in the form can reference values in the ActionRowValue column, so that the labels and data in the dialog are dynamically updated for the current row.

If you need to reference the current row value in the command's shortcut parameters directly, this is only possible if the parameter supports bracketed cell reference syntax to read the value from the spreadsheet. For example, you can configure a parameter to use [Report!D24], where that is the ActionRowValue cell for the value that you want to reference. When the user clicks on the icon, the current row value would be written back to Report!D24 and used in the command's shortcut parameters.

IMPORTANT: It is not supported to construct the command string using a formula, because the formula will not be recalculated when the icon is clicked. The only way to dynamically reference a value in the command's shortcut parameters is to use the bracketed cell reference syntax to read the value from a designated cell.

In addition to populating the ActionRowValue column, a data filter representing the current row is also written to the Action Row Filter field for the component on the Form Control Sheet. You can optionally reference this filter statement directly instead of building your own. The filter statement is based on the row data definition for the current row plus any section filter, as defined in the FixedReportConfig data source (and the FixedReportSectionConfig data source, if applicable).

The ActionRowValue column and the Action Row Filter field are only populated when:

  • The icon action is a command.
  • The command triggers a form update. Most commands do this, but some don't. For example, the File Attachment command does not trigger a form update, so you cannot use that command on an icon and expect to open the File Attachment dialog for the current row value. Make sure to review the form update behavior for the command that you want to use.

Using the Navigate To Report command to dynamically open a document per row

The Navigate To Report command can be used as an icon action to dynamically open a document per row. For example, you may want to change the document that is opened based on the current row, or you may want to pass different values into the target document based on the current row. The command can be used to open Axiom forms or web reports.

When you use the Navigate To Report command, you specify the following:

  • The path to the document to open, using document shortcut syntax
  • An optional filter to apply to the target document as a sheet filter (Axiom forms only)
  • One or more optional document variables to pass into the target document (Axiom forms only)

Because all three of these properties can use a bracketed cell reference to read the value from the source file, you can dynamically change any of these values based on the current row.

Example 1: Changing the document

You can dynamically change the target document for the command by using a bracketed cell reference in the Document parameter. Imagine that the report contains a column for Dept.Dept, and you want to use that department value to open the plan file for each department.

In order to do this, you would use a bracketed cell reference in the Document parameter, such as [Report!J40].

Then in cell Report!J40, you can create a document path to the plan file that references the Dept.Dept value in the ActionRowValue column. When a user clicks on the row for department 40000, the value 40000 is written to the ActionRowValue column, and the document path updates to point to the plan file for that department.

Example 2: Changing the filter or variable

You can dynamically change the filter applied to the target document by using a bracketed cell reference in the Filter parameter. Similarly, you can dynamically change the variable values that you pass to the target document by using a bracketed cell reference in the Value field for a document variable.

Imagine that the report contains a column for Acct.Acct. You want to open a report to show additional information about that account. To do this, you can pass in a filter criteria statement that references the account, and/or pass in variable values relating to the account.

In this example, both the Filter parameter and the variable value use a bracketed cell reference.

Cell Report!J19 creates a filter criteria statement that references the Acct.Acct value in the ActionRowColumn. When the user clicks on the row for Acct 6000, the cell contents will be Acct.Acct=6000. This filter is then applied to the target document when it is opened.

Cell Report!K6 references the Acct.Description value in the ActionRowColumn directly. This sets the value of the Account variable to its description, so that the account description can be shown in the target document. The target document must use a GetDocumentInfo function to return the value of the Account variable.