Toggle menu

Wizard Buttons

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.

Properties

LabelDescriptionType Name
Button TypeEither "Normal" or "Contrast". Selecting contrast adds the class "btn--contrast", which can then be targeted by the site's style sheetBUTTONTYPE
Is iCM Panel ButtonIf 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 neededISICMPANELBUTTON
Navigation ButtonsWhether 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 typeENABLENAVIGATIONBUTTONS
Back LabelThe label that will appear on the back buttonBACKLABEL
Back ModeControl 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

See Form Back Buttons for an example
BACKMODE
Back FunctionThis 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) {
    var thePreviousPage;
    thePreviousPage = defaultPage;
    if (helper.getFieldValue('FIELD1') == 'SKIPPAGE2') {
        thePreviousPage = 'PAGE1';
    }
    return thePreviousPage;
}

Back Function
 

defaultPage
is the page that would be displayed if the function were not present
BACKFUNCTION
Next LabelThe label that will appear on the next buttonNEXTLABEL
Next ModeValidate, 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 FunctionBy 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 buttonNEXTFUNCTION
Finish LabelThe label that will appear on the Finish (submit) buttonFINISHLABEL
Finish OnlySetting 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 formsFINISHONLY
Reset LabelThe label that will appear on the Reset buttonRESETLABEL
Reset ButtonDetermines 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 ButtonsWhether 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
ENABLEEDITBUTTONS
Update LabelThe label of the update buttonUPDATELABEL
Update FunctionCalled 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 LabelThe label of the cancel buttonCANCELLABEL
Cancel FunctionCalled 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 FunctionThis 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 ) {
  return ["BACK", "NEXT", "FINISH" ];
}

Override Function
 
If you use an override your chosen buttons will always be displayed, regardless of the page mode
OVERRIDEFUNC
Additional Styling ModifierAn optional CSS modifier for the field. See Common Field Properties for an exampleADDITIONALSTYLINGMODIFIER
DocumentationAdd 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 exampleDOCUMENTATION
Last modified on 09 January 2024

Share this page

Facebook icon Twitter icon email icon

Print

print icon