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.

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

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

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

If you want to create a set of if-then-else conditions, then you can define multiple [Icon] rows with different conditions and then assign them all to the same condition group using the [ConditionGroup] property.

[ConditionGroup]

Optional. Specifies whether the row belongs to a condition group to be evaluated as a set of if-then-else conditions. Enter the same group name on all [Icon] rows that you want to be evaluated as a set. Note the following requirements:

  • All rows belonging to the same group must be contiguous. Non-contiguous group names will be evaluated as starting a new group, even when the group name is the same.

  • Any row with a blank condition ends the group, even if the next row down has the same group name.

For example, a condition group could be defined as follows:

This condition group shows an icon based on the Difference value, where Difference is the name of a calculated column defined for the report. If the first condition is true for a row in the report, then the row uses the fa-chevron-circle-up icon, and no further conditions in the group are evaluated. If the first condition is not true, then the second condition is evaluated, and so on. The row with the blank condition serves as a catch-all "else" statement, so that all rows in the report will match one of the icons in this group. The blank condition is not required—if no matches are found in the condition group, then no icons from that group will be used on the row.

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

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 a document using an icon, and you need the target document to change in some way based on the current row, you can use a command instead. See Using commands to dynamically open a document per row.

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 commands to dynamically open a document per row

You can use certain commands with icon actions, in order 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 Navigate to Report command and the Open Plan File command can be used for this purpose.

Both commands support use of bracketed cell references to read values from the source file, so that you can dynamically change the command values based on the current row.

Example 1: Changing the document per row

Imagine that the report contains a column for Dept.Dept, and you want to use that department value to open a plan file for each department. The Open Plan File command can be used for this purpose. This command opens any type of plan file, whether it is form-based or spreadsheet-based.

To open a plan file, you specify the file group that the plan file belongs to, and then you specify the plan file value.

  • The file group can be a file group name, a file group alias name, or the current file group (if the form with the report belongs to a file group).

  • The plan file value can be obtained from a column in the report. In this example, [Report!K6] is the cell in the ActionRowValue column where the Dept value will be written, and Dept is the plan code table for the specified file group.

When the user clicks on the action icon in the row for Dept 24000, the value 24000 is written to cell Report!K6. Axiom Software then opens the plan file for that plan code, in the specified file group.

If instead you wanted to open a different report per row, you could use the Navigate to Report command. In this case, you can use a bracketed cell reference to read the path to the desired document from a designed cell in the source file. When using the Navigate to Report command, the target document must be an Axiom form or a web report.

Example 2: Changing the filter or variable

When using the Navigate to Report command, 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.

For the document variables, 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.