Validation hooks in Builder help define custom validation logic for your model's content using JavaScript.
To create a custom validation hook:
- Go to Content Models.
- Open the model and click the Advanced tab.
- Find the Validation hook option and click Edit.
- Add your validation logic in the editor.
This video demonstrates the process:
When you click Edit Validation Hook, a code editor opens where you can add your validation hook.
async function run() {
if (contentModel.data.get('myProperty') === 'some invalid value') {
return {
level: 'error',
message: 'myProperty is invalid!'
}
}
}
return run();Validation hooks provide a way to surface custom warnings and error messages to users. To create a validation hook:
- Ensure you have an
asyncfunction defined within the code editor. Ensure the invoked function is returned at the end of the file. - Within the function, perform a check of some kind, such as validating a content model's custom field value.
- If a warning or error should be surfaced, return an object or an array of objects that contain at least a
leveland amessagekey.
Construct error messages with the following keys and values:
| Key | Required | Type | Description |
level | Yes | string | The value must be either |
message | Yes | string | The error message to be displayed. |
secondaryMessage | No | string | Additional context for the message. |
moreInfoUrl | No | string | A URL that provides help on fixing the error. |
field | No | object | Determines which field to target with the error message. |
element | No | Builder block | Identifies the Builder block to focus the error on. |
affectedElements | No | string | If the error affects multiple elements in the content, specify them as an array. |
The code you write here has access to these constants:
model: The model object being validated. This contains information about the structure and settings of the model.contentModel: The entire content object currently loaded in the Visual Editor. This includes all the data and variations associated with the content.editingVariation: The current content variation being edited. This gives access to the specific variation of the content being validated.
These constants help you access and manipulate the data within the content being validated. For example, you can retrieve values of specific properties, check conditions, and perform custom checks based on the content's attributes.
Validation can be targeted at the Page or Block level. To do so, add a field key to the error object.
The field key expects an object with two key-value pairs.
| Key | Data type | Description |
name | string | The name of the field or input to highlight. |
target | string | The value must be either |
For issues with content entry data, provide the 'page' value to the target key.
In the following code example, a check is made to ensure the content entry's custom action field has a value. If it does not, an error is surfaced.
async function run() {
if (!contentModel.data.get('action')) {
const errorMessage = 'Action is invalid.';
return {
level: 'error',
field: { name: 'action', target: 'page' },
message: errorMessage
};
}
}
return run();The follow video demonstrates this surfaced error, and shows it being fixed.
To focus an error on a specific block within a content entry, use the 'block' value.
In the example below, a particular block and its text are accessed. The length of this text is evaluated and, if the length of the text is too long, an error is surfaced.
async function run() {
const blocks = contentModel.data.get('blocks');
const wrapper = blocks[0];
const callout = wrapper.children[0].children[0];
const calloutText = callout.component.options.get('text');
if (calloutText.length >= 70) {
const calloutError = "Callout text must be less than 70 characters."
return {
level: 'error',
field: { name: 'title', target: 'block' },
element: callout,
message: calloutError
};
}
}
return run();The follow video demonstrates this surfaced error, and shows it being fixed.
