Navigation Methods
The registration process features a linear navigation flow (forward/back). Custom widgets interact with this flow by preventing or allowing navigation based on custom logic.
For example, if a required field needs completion or an action requires execution within the custom widget, use the methods below to enable the custom widget to detect this and prevent the registrant from navigating to the next page or submitting the form until the necessary actions complete.
Access the Navigation SDK by calling the getNavigator()
function on the cventSdk property of your custom widget.
This is an entirely client side feature and should be used for the sake of user experience and not for security.
Navigation Set Is Valid
setIsValid(valid: boolean) sets the validity of the widget. When you call navigationSdk.setIsValid(false)
to mark a custom widget as invalid, you prevent the user from progressing in registration. The application
scrolls to the first invalid widget, which may include a custom widget or a standard widget.
If the widget qualifies as a custom widget, the application calls the widgets focusOnFailedNavigation method,
if it exists.
Parameters
| Parameters | Description |
|---|---|
| valid | True indicates the widget is valid, false if the widget is invalid. |
Return Type
| Return Type | Description |
|---|---|
void | This method returns nothing |
Example
class NavigationWidget extends HTMLElement {
constructor({ configuration }) {
super();
this.configuration = configuration ?? { required: true };
// Create a shadow root
this.attachShadow({ mode: 'open' });
this.input = document.createElement('input');
this.shadowRoot.appendChild(this.input);
// configuration can't change on guest side
// and navigation validation isn't enabled in the designer
if (this.configuration.required) {
const navigatorPromise = this.cventSdk.getNavigator();
const requiredInput = this.input;
navigatorPromise.then(navigator => {
// since our example widget always starts blank, we set it to
// invalid based on that initial state
navigator.setIsValid(false);
requiredInput.onchange = _event => {
navigator.setIsValid(Boolean(requiredInput.value));
};
});
}
}
}Navigation Validator
The registerNavigationValidator(...) method registers a handler that
conducts asynchronous validation to determine whether navigation should
proceed when the user clicks Next or Submit. This method returns a
function that removes the handler. This function doesn’t execute if
your widget has already set as invalid by calling setIsValid(false).
Parameter
| Parameters | Description |
|---|---|
| validator | The function to run when the user attempts to navigate. Returns true to allow navigation and false to prevent navigation. |
Return Type
| Return Type | Description |
|---|---|
() => void | A function that removes this validator. Call this function in the disconnected callback to avoid registering multiple validators. |
Example
class MyCustomWidget extends HTMLElement {
disconnectedCallback() {
this.cleanup?.();
this.cleanup = null;
}
async connectedCallback() {
if (!this.isConnected) {
// do not register callback if the node has been disconnected
return;
}
const navigation = await this.cventSdk.getNavigator();
const validate = async onSubmit => {
const response = await callSomeService(this.config.exampleField);
const responseObject = await response.json();
return responseObject.isValid;
};
this.cleanup = navigation.registerNavigationValidator(validate);
}
}