AX1480
The Button component can be used to execute command shortcuts when the button is clicked. This provides a way for users to perform certain actions from within the form.
For buttons, the primary use of command shortcuts is to execute a command from the Command Library. This is the same Command Library that is available for use in custom task panes and ribbon tabs, although only a subset of these commands can be used within Axiom forms.
When the user clicks the button in the Axiom form, one or more actions will be performed according to the specified commands. The commands are performed in addition to the standard form update process that is normally triggered by clicking the button. Specific commands may be executed at different points in the update process.
Command shortcuts can also be used to open files in the Axiom Software file system.
Configuring a Button component to use a command from the Command Library
This is a generic discussion of how to configure a Button component to use a command shortcut. For more information about how to use specific commands and design considerations, see the individual topics for each command.
-
In the Button component properties (accessible in the Form Designer or in the Form Assistant), click the Browse [...] button to the right of the Command box.
-
In the Shortcut Properties dialog, click the Browse [...] button to the right of the Shortcut Target box.
This opens the Axiom Explorer dialog, which is filtered to only show items that are eligible for use in command shortcuts within Axiom forms.
-
In the Axiom Explorer dialog, go to the Command Library. Select the desired command shortcut and then click Open.
This returns you to the Shortcut Properties dialog, with your selected item listed as the Shortcut Target.
-
If the selected item has Shortcut Parameters, configure these parameters as desired.
Example shortcut parameters
The available shortcut parameters depend on the selected command. For more information, see the individual topics on using each command in a form.
In addition to the command-specific parameters, each command has a designated Processing Step that determines the timing and context of the command execution. This processing step may be display-only for your information, or it may be configurable. For more information, see Timing of command execution.
- Click OK to close the Shortcut Properties dialog and return to the button properties.
The button is now configured to use the specified command shortcut.
Using a Button tag in a Formatted Grid component
Button tags in thematic Formatted Grid components can also be configured to run commands. In this case, you use the Command parameter within the tag to assign the command to the button. The easiest way to do this is to use the Tag Editor dialog or the Data Source Assistant to create the tag and edit the tag parameters. When using these helper dialogs, you can select the command and configure the shortcut parameters using the same method described previously for the Button component.
When a Button component is configured to execute a command, this command is performed during the normal form update process. The command has two properties that determine when and where it is executed:
-
The processing context determines whether the command is executed on the form (meaning on the form's source file on the application server), or on the active client spreadsheet within the Excel Client or Windows Client. The active client spreadsheet context only applies when the form is being used as a dialog or task pane in the Excel Client or Windows Client.
Some commands can only be performed in one context or the other, whereas other commands can run in either context.
-
The processing step determines when the command is executed within the designated context. The available processing steps relate to the form update process that occurs each time a button is used in a form. Some commands are "hard-coded" to only run at a certain processing step, whereas other commands are configurable.
For example, if the processing context is the form, is the command executed After Updating Values or After Processing? If the processing context is the active client spreadsheet, is the command executed Before Processing or After Processing?
When configuring a command for a button, this information is presented in the shortcut parameters as processing context — processing step. If this timing is configurable for a command, you can select the appropriate context / step combination from the Processing Step drop-down list.
The following table details the default processing step for each command that can be used in Axiom forms. For more information on the full form update process and the timing of these processing steps, see Axiom form update process.
| Command | Processing Step (Default) | Configurable? | Notes |
|---|---|---|---|
|
Form - After Updating Values |
Yes |
||
|
Form - After Processing |
Yes |
||
|
Form - After Updating Values |
No |
If the Add Rows command causes a calc method dialog to display, then no further commands will be executed after the Add Rows command. |
|
|
Active Client Spreadsheet - After Processing |
No |
||
|
Form - After Updating Values |
No | ||
|
Active Client Spreadsheet - After Processing |
Yes |
If the processing step for this command is changed to Before Processing, then this command aborts the form update process. No further actions occur after the command is executed. |
|
|
Download Form as PDF |
Form - Before Processing | No |
This command aborts the form update process. No further actions occur after the command is executed. Other commands cannot be combined with this command. NOTE: This command is available for backward-compatibility only. Going forward, you should enable the PDF icon on the task bar for any form where you want to allow users to generate a PDF. For more information, see Configuring an Axiom form for printing to PDF. |
| Form - After Updating Values | Yes | ||
|
Form - After Processing |
No |
Although a form update occurs on the server (for purposes of determining the grid state before export), this update is not reflected in the open form. The user will not see any change to the open form. |
|
| Form - Before Processing | No | This command aborts the form update process. No further actions occur after the command is executed. Other commands cannot be combined with this command. | |
| Form - After Processing | Yes | ||
|
Form - After Updating Values |
No |
This command has special update behavior. See the detailed topic for more information. |
|
|
Form - Before Processing |
No |
This command aborts the form update process. No further actions occur after the command is executed. Other commands cannot be combined with this command. |
|
|
Active Client Spreadsheet - After Processing |
Yes |
||
|
Form - After Updating Values |
No |
If the target document is opened in the same window as the current document, then the form update process does not proceed beyond the After Updating Values step. If the target document is opened in a new window, the original form will continue and complete its update cycle. |
|
|
Form - After Updating Values |
No |
If the target document is opened in the same window as the current document, then the form update process does not proceed beyond the After Updating Values step. If the target document is opened in a new window, the original form will continue and complete its update cycle. | |
|
Form - After Updating Values |
No |
If the directory is opened in the same window as the current document, then the form update process does not proceed beyond the After Updating Values step. If the directory is opened in a new window, the original form will continue and complete its update cycle. |
|
|
Form - After AQ Refresh |
Yes |
||
|
Form - After Updating Values |
No |
If the directory is opened in the same window as the current document, then the form update process does not proceed beyond the After Updating Values step. If the directory is opened in a new window, the original form will continue and complete its update cycle. |
|
|
Active Client Spreadsheet - After Processing |
No |
||
|
Form - After Updating Values |
Yes |
||
|
Form - After Updating Values |
Yes |
This command essentially performs the same action as the Show Dialog Panel button behavior. For more information, see Dialog Panel component for Axiom forms. |
Configuring a Button component to open a document
Command shortcuts can also be used to open a document in the Axiom Software file system. To do this, use the same steps as described previously to set the shortcut target. Then in the Axiom Explorer dialog, select a document instead of selecting a command in the Command Library.
You can select spreadsheet Axiom files, form-enabled files, or web reports. The shortcut parameters for the file depend on the file type and whether the file is form-enabled.
If the shortcut is to a form-enabled file, then you must complete the following shortcut parameters:
-
View as Form: Enable this option to open the file as an Axiom form (instead of as a spreadsheet Axiom file).
-
Use New Window: Enable this option if you want the form to open in a new window. If this option is not enabled, then the form opens within the same window, replacing the current form.
-
Processing Step: Specify the processing step to determine the point in the update process when the form is opened. See the previous section for more information on processing steps.
Note that if the form is opened in the same window, no further form processing occurs on the original form once the new form is opened. Therefore if you want the original form to fully complete the update cycle before opening the new form, you must set the processing step to Form - After Processing. If the form is opened in a new window, the original form will continue and complete its update cycle regardless of the selected processing step.
If the shortcut is for a spreadsheet Axiom file, that file will be opened in the Excel Client or the Windows Client. If the Desktop Client is not already installed on the user's computer, Axiom Software will attempt to install it. Therefore you should only link to spreadsheet Axiom files if either of the following is true:
- Users will view the Axiom form within the Excel Client or Windows Client.
- Users will use the Web Client on a Windows PC, and either the Excel Client or Windows Client is already installed on that machine or it is acceptable for the user to install it.
Using multiple commands on a button
Button components can perform multiple commands. By default, the button properties only have one command box, but you can add more command boxes to accommodate multiple commands.
To add more commands to a button, click the Add link below the Command box in either the Form Assistant or the Form Designer. This will add another command box to the component, where you can configure another command. You can add as many commands as necessary.
Click Add to add more commands
New blank box becomes available for additional command
If a button uses multiple commands, then each command is performed according to its configured or built-in processing step (see the previous sections for more details). For example, a button could have two commands: Process Action Codes and Run Event. The Process Action Codes command could be configured to run After Updating Values, and the RunEvent command could be configured to run After Processing. Both commands would be performed during the normal update process, at their assigned points in the process.
If each command is performed at a different processing step, then the order of the commands within the button properties is irrelevant. However, if multiple commands will be performed at the same processing step—for example if two commands will both be processed After Updating Values—then the commands will be performed in the order they appear in the button properties.
NOTE: Certain commands have special update behavior and/or cause the update process to stop after executing the command. This may mean that other commands cannot be executed or that the other commands must be executed before the command that uses special behavior.
Currently, there is no way to reorder commands for a Button component using the Form Assistant or the Form Designer. If you need to reorder commands, you can go to the Form Control Sheet and do one of the following:
-
Swap the contents of the Command boxes for the commands that you want to reorder. For example, copy and paste the contents of the top command to a temporary location. Then copy and paste the contents of the bottom command to the top command. Then go back the temporary location and copy and paste the original contents of the top command to the bottom command.
-
Alternatively, you can manually change the order number of the commands as detailed in column A of the Form Control Sheet. The command tags in column A use the following syntax:
[CommandItem;XX]
Where XX is a number from 00 to 99. The numbers are relative to the current component only.
To do this, clear the freeze panes for the Form Control Sheet and then move to column A. Locate the command tags and then change the numbers as desired. For example, if the first command is 00 and the second command is 01, swap the numbers for each command.
