Bundle Customization

Anne Rosebery
v5

Bundle Customization

If you need to customize the way the Kinetic Runtime API works and renders forms you can override the configuration using the global bundle object. Here’s an example of what a configuration block might look like:

<script>
    bundle.config = {
        ready: function(form) {
            // 'form' is the form object.
        },
        renderers: {
            submitErrors: function(response) {
                // 'response' is the response object from the server.
            },
            resourceErrors: function(bridgedResource, response) {
                // 'bridgedResource' is the bridged resource object.
                // 'response' is the response object from the server.
            },
            fieldConstraintViolations: function(form, fieldConstraintViolations) {
                // 'form' is the form object which was attempting to submit.
                // 'fieldConstraintViolations' is a map of fields which failed validations.
            }
        },
        fields: {
            text: {
                callback: function(field) { ... },
                render: function(field) { ... }
            }
        }
    };
</script>

Ready Function

The ready function is provided as a bundle-level page load event. When a form load is complete it will call this callback with the Form object representing the form that was just loaded.

Renderer Callbacks

Available renderer callbacks:

  • fieldConstraintViolations
  • submitErrors
  • resourceErrors

Field Constraint Violations

This callback function is called with two arguments: the current Form object and an object of field violations:

  function(form, fieldConstraintViolations) {
    
  }

The field violation object looks like this:

  {
    'Required Field Name': [
      'This field is required and must be populated.'
    ]
  }

The key in the object is the name of the field with constraint violations. The value is an array of messages for each constraint the field is currently violating.

Submit Errors

The submitErrors callback is called whenever a submission is attempted but there was a server error. The function signature is function(response) where response is the response object from the server.

Resource Errors

The resourceErrors callback allows you to override the behavior of what bridged resources do when they encounter any errors. If the call to the bridged resource has an errors callback passed to it, that option will supersede this callback.

The resourceErrors callback function signature looks like this:

  function(bridgedResource, response) {
    
  }

The bridgedResource argument returns a Kinetic BridgedResource object and the response argument is the actual response from the bridge.

Field Customizations

You can override the way in which fields are rendered. The key of the fields object is the field type.

Each override is an object that can define how to handle the initial rendering of the field, and a callback that gets executed after the field rendering happens. The two property names are render and callback. The value for these properties is expected to be a function that receives the Field as an argument.

  • render: this function is called when the field is initially rendered, and is passed the Field as an argument. If null or missing, the default field rendering occurs. Use this function to override the entire field rendering.

    render: function(field) {
      
    }
  • callback: this function is called after the field is rendered, and is passed the Field as an argument. Use this function to augment the field rendering.

    callback: function(field) {
      
    }

Available Field Types

  • text
  • checkbox
  • radio
  • dropdown
  • date
  • datetime
  • time
  • attachment

Note: You cannot override section, content, or button in this manner.

All of the field types have change events bound to them automatically. Additionally date, datetime, time, and attachment have significant custom rendering behavior by default. This is how you would change how your date and time pickers worked or alter the file upload fields.

Legacy Field Customizations

In v1.x, field customization was slightly different. The bundle.config.fields object looked something like this:

<script>
    bundle.config.fields = {
        text: function(field, trigger) { ... }
            // 'field' is the field object.
            // 'trigger' is a callback to trigger change cycles.
        }
    };
</script>

This format is still currently supported in v2, but it is encouraged to update this code with the format described above in the Field Customizations section, as it will likely be removed in future versions.

With this format, the key of the fields object is still the field type, but there is only one function, not a separate render and callback function.

Each field override function takes two arguments: field and trigger. The field argument is a Field object. The trigger argument is a callback function used to elicit our field change and other similar events.

Important Note: If you override a field with a field customization and do not call trigger at any point the automatic behavior for fields of that type.

Available Field Types

  • text
  • checkbox
  • radio
  • dropdown
  • date
  • datetime
  • time
  • attachment

Note: You cannot override section, content, or button in this manner.

All of the field types have change events bound to them automatically. Additionally date, datetime, time, and attachment have significant custom rendering behavior by default. This is how you would change how your date and time pickers worked or alter the file upload fields.