Event Handler Functions - The Digital Platform Documentation Site

Skip to main content

Field handler functions are triggered when a field first loads, and each time its value changes.

The function's parameters are:

helper - The form helper library
fieldName - The name of the field
value - The new value of the field
valid - The field validated successfully (either true or false)
eventName - The name of the event triggering the call, either CHANGE, PAGEINIT or NEWPAGEINIT

In these examples the handler on the first field combines its value with some text and updates the second field.

Example 1
1. Here the first field is required, and has validation set up so it only accepts a postcode. The handler checks that the value is valid (ie it exists and is in the correct format) before updating the second field. The handler is also written so that the change is only made when the field is updated, not when the page loads.
2. The handler looks like this:
  
  function (helper, fieldName, value, valid, eventName) { if (eventName == 'CHANGE' && valid) { helper.setFieldValue('TWO', String('You entered: ') + String(value)); } }
  
  Enter a postcode to see the update, or some random text to see the handler not perform the update.
3. Postcode*
4. Field two
Example 2
1. This example shows how not to do it!
  
  Field one is still required and has validation set up to only accept a postcode. However, the handler isn't checking that the change is valid, it simply updates the final field. It doesn't check the event that triggered it, so is also executed when the page loads, which is why field four already has the text "You entered:" in it.
2. The handler looks like this:
  
  Enter some random text to see the poor behaviour.
3. Postcode*
4. Field four