Using Validators

When a user selects a new value from or types into a form field or editable cell in a published view, it is automatically validated.

By default, fields and cells have type validation applied, corresponding to the data types of their respective entities—or in the case of an array, its elements. Any registered entity validators are also automatically applied. For more, see the JavaScript API documentation.

Validation is applied when a field or cell becomes invalid so can only be applied to editable cells. A cell containing invalid input displays a red background, which is removed once the value becomes valid again. If you attempt to save an invalid value, a dialog displays a validation error message, and the value itself is reverted.

In addition to the default validation, you can provide one or move validators per form field or table column using the <vdl-validate> element. A <vdl-validate> element must contain a pass attribute that is either a Boolean expression or a function to be called whenever a value is edited. It should also contain text content to serve as an error message if validation fails. If text content is not provided and the validation fails, it reverts the value silently.

Whether you use a Boolean expression or a function, they both get passed the same information:

entityName—the name of the entity being edited.
value—the cell value.
key—the index of the element being edited, if it is from an array.

The following example shows a simple Boolean expression, provided as the pass attribute in a <vdl-validate> child element of a <vdl-field> element, that accesses one of the model's parameters.

<vdl-field entity="ChannelCost" indices="1" label="Cost (SMS)"> 
  <vdl-validate pass="=value > 1">Cost must be greater than 1
  </vdl-validate> 
</vdl-field>

The next example illustrates how to apply <vdl-validate> to a table column.

<vdl-table> 
  <vdl-table-column set="CHANNELS" width="70"></vdl-table-column> 
  <vdl-table-column entity="ChannelCost" 
                    editable="true"
                    heading="Channel Cost"> 
    <vdl-validate pass="=value > 1">Cost must be greater than 1</vdl-validate> 
  </vdl-table-column> 
</vdl-table>

The same validation can be offered as a reusable function:

<script>
    function greaterThan0(entityName, value, key) {
    return value > 0;
    }
</script>

This is invoked by using the following pass attribute:

<vdl-validate pass="=greaterThan1">Profit score must be greater than zero.</vdl-validate>

Note that in all cases, the expression used should resolve to a Boolean and the function, if used, should return a Boolean.

You could use the entityName argument to create validation functions that work across multiple entities and behave differently in each case. The key argument becomes useful when you want to validate depending upon an item's position in an array.

So far, all validation has prevented new invalid values from being saved, and the cell values are reverted. Occasionally, you may sometimes need to apply soft validation, which will mark cells or fields as invalid but still allow the values to be saved. This is useful if you need to validate a group of values in a table but allow the saving of intermediate invalid states as each cell in a group is corrected. To do this, and enable this behavior per validator, set allow-save="true" on the respective <vdl-validate> element.

Because validators are applied to columns as child elements to <vdl-field> or <vdl-table-column>, this allows multiple validators to be defined. It also allows you to generate validators within a loop over a set or JavaScript array, and to conditionally apply validators.

Using Row Information

The <vdl-validate> tag's pass attribute provides access to the current row data when used with a <vdl-table> element. When a validation callback is provided to the pass attribute, it is called with four parameters: entityName, value, indices, and rowData. rowData contains an array of indices and all cell values that exist in the adjacent cells of the row in which this cell is being validated. This enables you to validate a cell value based on one or more values from adjacent cells in a table row.

<vdl-table-column set="A">Index A</vdl-table-column>
<vdl-table-column entity="B">Entity B</vdl-table-column>
<vdl-table-column entity="C" editable = "true">
    <vdl-validate pass="=function(entityName, value, indices, rowData)
                         {return value < rowData[1]}">
    </vdl-validate>
</vdl-table-column>

Here, the validator causes an error if the value in column C is greater than or equal to the value in column B.

Contents

Index

Glossary

Search Results

Using Validators

Using Row Information