The wizard button field displays a set of buttons that will change depending on where it is placed in your form.
In a multipage form it will, by default, provide a "Next" button on the first page, "Back" and "Next" buttons on middle pages, and "Back" and "Submit" buttons on the final page. If a page has already been submitted, and the page is being revisited in "edit mode" you'll see "Update" and "Cancel" buttons. Any set of buttons can also include a "Reset" button.
Navigation through your form pages can be controlled by supplying back and next functions, which let you to write logic that will skip over pages and display different pages depending upon the values entered in the form.
The override function gives you full control over the buttons that will be output.
If your form has complex branching the .utilRemovePageData function may also be useful.
Repeating Pages
If your form includes repeating pages the default behaviour of the buttons is to navigate between page instances.
For example, consider a three page form with a wizard button on each page, and three instances (ie three repeats) of page two. Once a user has navigated to page three, pressing "Back" would navigate through instance three, then two, then one of the repeating page, then back to page one. Similarly, pressing "Next" on page one would navigate through instances one, then two, then three of the repeating page, then on to page three. This assumes those page instances already exist.
The wizard buttons can also create page instances if an exact number of instances is specified in your form design. Rather than a user adding instances themselves, if your repeating page settings' minimum and maximum instances are the same and validated, pressing "Next" will add a new page instance and navigate to it until the required number of instances is reached, at which point it will navigate to the next page. If there are zero required instances of a repeating page, it will be skipped.
Examples
Two tutorials guide you through form navigation: Multipage Forms and Navigation and Multipage Forms and Branching.
Form Back Buttons has examples of the behaviour of the back button.
The Page Modes article has some example functions, including a description of the three page modes and how to invoke them in your navigation functions.
Properties
| Label | Description | Type Name |
|---|---|---|
| Button Type | Either "Normal" or "Contrast". Selecting contrast adds the class | BUTTONTYPE |
| Is iCM Panel Button | If set to true and the form is being used via a Form App shortcut within iCM, the button will be rendered as an action within the Actions Panel. The button itself will be hidden on the form. This allows better integration into iCM when needed | ISICMPANELBUTTON |
| Navigation Buttons | Whether or not to display the Back, Next and Finish buttons. You might want to hide these buttons if you are using the Navigation Button to navigate through your form, but still want the edit buttons (see below) provided by this field type | ENABLENAVIGATIONBUTTONS |
| Back Label | The label that will appear on the back button | BACKLABEL |
| Back Mode | Control whether fields are validated and actions triggered when a user presses the back button. No validation - The default setting allows a user to navigate back to the previous page as if this page hadn't been visited. Values that have been entered on the page won't be saved in the form session and no action fields will be triggered No validation (link) - This behaves in the same way as no validation, but outputs the button as a link. Back links are generally placed at the top of a page and are not triggered by pressing the Enter key Validate actions/no actions - In this mode the back button will only navigate away from the current page if there are no validation failures. Any values entered for the fields on the page will be saved in this form session. When performing validation it is also possible to control if action fields are triggered or not. In most circumstances performing actions when navigating back doesn't make sense None - Remove the button from the set | BACKMODE |
| Back Function | This function determines which page should be displayed when the back button is clicked. By default, the page located directly before the current page in the forms designer will be displayed. Your function should return the name of the page to display instead. This function could be added to page 3 of a form, where page 2 may have been skipped:function(helper, defaultPage, sessionData) { defaultPage | BACKFUNCTION |
| Next Label | The label that will appear on the next button | NEXTLABEL |
| Next Mode | Validate, actions/no actions - Moving to the next page always validates the field inputs and stores their values in the form session. You can control whether or not actions on the page are triggered None - Remove the button from the set | NEXTMODE |
| Next Function | By default, the page located directly after the current page in the forms designer will be displayed. To display a different page, return its name in your function, in exactly the same way as described for the back button | NEXTFUNCTION |
| Finish Label | The label that will appear on the Finish (submit) button | FINISHLABEL |
| Finish Only | Setting this as true hides the next button and adds a finish (submit) button, even if the current page isn't the last page of the form. This can be used to prevent the user from moving to the next page as it appears in the forms designer in branching forms | FINISHONLY |
| Reset Label | The label that will appear on the Reset button | RESETLABEL |
| Reset Button | Determines the availability and position of the reset button. By default, "None" is selected so a Reset button won't be included. Select "Left Most" or "Right Most" to include a Reset button and to position it left or right | RESETMODE |
| Edit Buttons | Whether or not to display the Update and Cancel buttons when a page is visited in edit mode. See Page Modes. This would normally be set as false on a page that also uses Wizard Buttons - Repeating Pages, as that button set will provide the update and cancel buttons. See the Summaries - Check Answers Page tutorial for an example | ENABLEEDITBUTTONS |
| Update Label | The label of the update button | UPDATELABEL |
| Update Function | Called to determine what page should be displayed when the Update button is clicked. By default, the previous page will be displayed (this is a "next - no actions" submission). To override this behaviour, provide an Update Function and return details of the page to display. The page details can be either the page name or an object (map) containing the page name and page instance. The defaultPage and defaultPageInstance parameters supplied to the Update Function are the page and page instance that would be displayed if the function was not present | UPDATEFUNCTION |
| Cancel Label | The label of the cancel button | CANCELLABEL |
| Cancel Function | Called to determine what page should be displayed when the Cancel button is clicked. By default, the previous page will be displayed (this is a "back - no actions" submission). To override this behaviour, provide a Cancel Function and return details of the page to display. The page details can be the page name or an object (map) containing the page name and page instance. The defaultPage and defaultPageInstance parameters provided to the Cancel Function are the page and page instance that would be displayed if the function was not present | CANCELFUNCTION |
| Override Function | This optional function provides direct control over the buttons displayed by the wizard field type. The function is evaluated server-side when the form HTML is being built. The following actions are available: "BACK" : Displays the previous form page, no validation is performed, no data is saved, no actions are triggered "PREV" : Displays the previous form page, the current page must pass validation and its data is saved in this session. No actions are performed. "PREVACTIONS" : Displays the previous form page, the current page must pass validation and its data is saved in this session. Actions are performed. "NEXT" : Displays the next form page. Validation is performed and actions are executed. "NEXTNOACTIONS" : Displays the next form page. Validation is performed. No actions are executed. "FINISH" : Submits the form without displaying any more pages. "RESETLEFT" : Displays a reset button as the left most button. "RESETRIGHT" : Displays a reset button as the right most button. The function should return an array of action button names: function( helper ) { If you use an override your chosen buttons will always be displayed, regardless of the page mode | OVERRIDEFUNC |
| Additional Styling Modifier | An optional CSS modifier for the field. See Common Field Properties for an example | ADDITIONALSTYLINGMODIFIER |
| Documentation | Add documentation to your field to help explain any complex functionality to future users. You might include information on what the field does and how it relates to other fields on the form. Notes added here are only ever visible in the Forms Designer, they can be searched for, viewed and downloaded from the action panel. See Common Field Properties for an example | DOCUMENTATION |
Share this page
