If users are interacting with plan files as Axiom forms, then limited functionality is available to allow Axiom form users to insert new rows using calc methods. However, the "change calc method" functionality is not available in Axiom forms.
To insert rows, use the Add Rows command with a Button component, or with a Button tag in a Formatted Grid component. The user clicks on the button in the Axiom form to insert the new row.
As normal, the user must have the Allow Calc Method Insert security permission for the file in order to perform this action.
Requirements and limitations
To use calc method insert functionality in an Axiom form, your template and calc methods must be set up as follows. This applies regardless of which method is used to allow insertion within the Axiom form.
-
An InsertCMColumn must be defined, and the tag must have a defined header label. Dynamic insertion controls are not supported in Axiom forms.
For example:
[InsertCMColumn;CMInsert] -
An InsertCM tag must be placed on the row where you want to allow insertion. This tag must have a defined insertion point label, and must allow insertion. You can specify one or more calc methods or groups to allow for insertion, or you can leave those parameters blank to allow any calc method.
For example:
[InsertCM;InsertNewRow;New Row] -
In most cases, the calc method to be inserted should contain both a
[row]tag and a[save]tag in the appropriate columns, so that the newly inserted row displays in the Formatted Grid component, and so that the data for the newly inserted row gets saved to the database. Remember that the source file itself is not saved when the Axiom form triggers a save, so the newly inserted row will not be retained in the source file, only its data can be saved.NOTE: Neither of these tags are strictly required if you have a use case where you want to insert a row that does not subsequently display in the Axiom form, or does not get saved to the database. For example, perhaps the data for the new row impacts another component, or the data gets summed and saved from a different row.
-
Only one instance of the calc method can be inserted at a time within Axiom forms. The Axiom form environment does not provide an option to insert multiple instances of the calc method at a time. The MaxInsertCount parameter on the InsertCM tag will be ignored.
-
If the calc method uses calc method variables, the user can only set the values of these variables once, when the calc method is originally inserted. If you need the user to be able to edit these values after insertion, then the target cells must be configured as editable (unlocked). Keep in mind that if you use a Related Column Value variable, the related value will not be automatically updated if you allow the user to edit the parent value after insertion.
For more information on setting up calc method controls—meaning the InsertCMColumn and InsertCM tags—see Setting up calc method controls for a sheet.
The Add Rows command is always executed on the form, at the After Updating Values processing step of the form update process. For more information on how processing steps fit in with the form update process, see Axiom form update process. Note that if the Add Rows command causes a calc method dialog to display (either to select the calc method to insert, or to select variable values for the calc method), then no other commands will be executed after the Add Rows command.
Setting up calc method insertion
To allow users to insert new rows from the Axiom form, you can use a Button component that is configured to run the Add Rows command shortcut. The command can also be used with a Button tag in a Formatted Grid component.
To start off, add the Button component to the Axiom form canvas and then configure the properties as desired. You will probably want the button text to be something like "Insert New Row". You can then configure the Command for the component as follows:
-
In the component properties, click the ... button to the right of the Command box.
-
In the Shortcut Properties dialog, click the ... button to the right of the Shortcut Target box.
-
In the Axiom Explorer dialog, select the Command Library, then select Add Rows, then click Open.
The Add Rows command is now listed as the shortcut target, and the relevant shortcut parameters are now available.
-
Complete the shortcut parameters as follows, then click OK to close the Shortcut Properties dialog.
- Target Sheet: Type the sheet name where the calc method is to be inserted.
- Column Label: Type the header label defined in the InsertCMColumn tag.
-
Row Label: Type the insertion point label defined in the InsertCM tag. This is where the calc method will be inserted.
Example Shortcut Properties dialog
Using Is Deferrable
The Is Deferrable option on the Add Rows command is intended for cases where you have multiple Add Rows commands on a single button. If some insertions use calc method variables and others do not, you can defer the execution of the insertions without variables until all variable values have been selected. If the user cancels a variable selection and therefore cancels that insertion, the deferred insertions will also be canceled.
To do this, set up the button commands as follows:
- List the Add Rows commands that use variables before the commands that do not use variables, so that the insertions with variables are executed first.
- Enable Is Deferrable for all of the Add Rows commands that do not use variables, so that insertions without variables are deferred and dependent on the completion of the insertions with variables.
Whether an Add Rows command uses calc method variables depends on the calc methods allowed by the InsertCM tag for the specified Row Label. Deferred insertions must be assigned a single calc method that does not use variables, because deferred insertions must be able to be processed without user input.
Add Rows behavior
Within the Axiom form, the user can click the button to perform the Add Rows command. Within the source file, the command identifies the designated sheet, column, and row, and then inserts the calc method as specified in the InsertCM tag.
If multiple calc methods are allowed for insertion, then the user is first prompted to select which calc method to insert.
If the calc method has calc method variables, then the user is prompted to specify values for those variables before the calc method is inserted.
Assuming the inserted row is configured to display in the formatted grid, the new row will display in the Axiom form after the form update process is complete. The user can then complete any inputs associated with the new row.
