Toggle menu

helper.utilAddNewPageInstance()

Adds a new page instance to a repeating page.

This function can only be called in the control phase of the form processing lifecycle - ie you can only use it in buttons when navigating between pages. It can only be used to add instances to pages that are already set as repeatable in the forms designer.

Your function must navigate to the newly created instance or it will be removed from the session data.

Executed

Server-side only in the control phase.

Arguments

ArgumentTypeDescription
sessionDataString, requiredThe session data (will always be sessionData)
pageNameString, requiredThe page to create a new instance of
pageInstanceInteger, optionalThe instance will be created at this position in the index (zero-based). If not set, the new instance will be created after the instance this function is called on, or at the end of the index if called from another page. If you supply a number greater than the current number of instances the user will be taken to the last navigable instance of the supplied pageName

Returns

Integer, the index of the newly created instance.

Examples

This function called in the middle of a set of repeating page instances would add a new instance after the instance it is called on, then navigate to it.

function(helper, defaultPage, sessionData, defaultPageInstance) {
    return {
        pageName: defaultPage,
        pageInstance: helper.utilAddNewPageInstance(sessionData, defaultPage, defaultPageInstance)
    };
}

This function could be used on a subsequent page of a form to navigate back to a repeating page and add a fifth instance (assuming four instances already exist).

function(helper, defaultPage, sessionData, defaultPageInstance) {
    return {
        pageName: 'PAGE1',
        pageInstance: helper.utilAddNewPageInstance(sessionData, 'PAGE1', 4)
    };
}

Last modified on 07 August 2023

Share this page

Facebook icon Twitter icon email icon

Print

print icon