Skip to main content
Kinetic Community

Getting Started

Kinetic JavaScript Library

This  provides some basics for using Kinetic Javascript Library.

Builder Defined Field Conditions

In the builder you can define two conditions (currently): visible and enabled. These conditions are expressions which when evaluated will affect the field they are bound to.

Variables available by default:

  • space
  • kapp
  • form
  • values
  • identity

For example:

// Visible expression on section Requestor Info Section
values('requestFor') === 'someone else'

// Set this expression in the Required constraint on fields within the
// Requestor Info Section.
values('requestFor') === 'someone else'

The example above conditionally shows the section “Requestor Info Section” when the “requestFor” radio button is set to “someone else”. It will also then conditionally make the fields within that section (as defined in the Form Builder) required as well.

If “me” or some other value in the “requestFor” field is selected then the Requestor Info Section will be hidden and its fields will not be required.

The system will apply these automatically.

Builder Defined Events

The help rollout in the Form Builder provides more detailed information as to what values bindings are available in your events.

Page Load

The page load event happens after the bundle page load event as defined in the Ready Options (see below). Use this when you want to do something before the user interacts with the page.

Variables available by default:

  • page
  • form

Page Submit

The page submit event happens before the page is submitted to the server. If you return false from this event it will prevent the page from being submitted.

Variables available by default:

  • form
  • page
  • event

Note: The event object has two members:

  • event.constraints - a map of field constraint violations.
  • event.continue() - a method which allows you to asynchronously continue the page submission.

Field Change

The field change events fire on changes to their data, not necessarily just changes to the input element by the user. If a field change event changes another field’s value, that field will also fire a change event if one is defined.

Variables available by default:

  • form
  • field
  • event

The event object also has these members:

  • newValue - the current field value
  • constraints - the evaluated constraint violations for the field

Button Click

To be implemented at a later date.

Runtime Ready Options

Your bundle will execute a block similar to this. See your bundle documentation for bundle specific configurations. If you are a bundle developer, here is some information on customizing the runtime behavior:

$(document).ready(function() {
    var bindings = ${bindings};
    var events = ${events};
    K.ready(bindings, events, {
        // You can customize how fields are rendered by providing key, function configurations here:
        fields: {
            // Example, overriding the 'time' field type:
            time: function(field, trigger) {
                // 'field' represents a field being constructed for rendering.
                // 'trigger' is a useful function for triggering change events on these fields.
            }
        },
        renderers: {
            // Override the rendering functionality for handling server submit errors.
            submitErrors: function(response) {
                // '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.
            }
        }
        ready: function(form) {
            // Provides a "bundle" level page load event.
        }
    });
});

Using Kinetic selectors.

Using the runtime API you can use patterns to retrieve information and objects pertaining to the form. For detailed documentation see the class reference. Here are some examples:

    // Selecting the current form.
    K('form')
    // Selecting a form by slug. If multiple forms of the same slug are loaded you will
    // receive an array of forms.
    K('form[ipad-request]')
    // Selecting a field by name.
    K('field[FirstName]')
    // Selecting a bridged resource by name
    K('bridgedResource[People]')

Other supporting form data can also be selected.

    // Selecting the current page
    K('page')
    // Selecting the current submission data.
    K('submission')
    // Selecting the current kapp.
    K('kapp')

Many selectors can be nested, for example:

    // Selecting a field by name which is on the current page.
    K('form page field[FirstName]')

Selectors imply the active form so the ‘form’ selector can nearly always be omitted:

    // Get the FirstName field for the current page.
    K('page field[FirstName]')

A number of form elements can also be selected by their names:

    // Selecta a button by name
    K('button[Refresh List]')
    // Select a section by name
    K('section[Personal Information]')
    // Select a text element by name.
    K('text[Introduction]')

Using Kinetic JavaScript Objects

The Field Object

The Field object has a number of useful methods defined on it for form and kapp developers.

    // Getting a field value:
    K('field[FirstName]').value()
    // Setting a field value:
    K('field[FirstName]').value('John')
    // Retrieving the field's DOM element:
    K('field[FirstName]').element()
    // Runs field constraint validations and returns the results, an emtpy array is a valid field
    K('field[FirstName]').validate()

The Form Object

The Form object is at the core of the form behavior. It provides a number of useful methods for manipulating the form:

    // Getting the form's DOM element:
    K('form').element()
    // Run all field constraint validations and return the results, an empty object is a valid form.
    K('form').validate()
    // Get a serialized version of the form values:
    K('form').serialize()

You can also trigger the page saving and advancing manually. These are automatically bound to buttons of the appropriate type, however this functionality is provided for asynchronous processing:

    // Save For Later
    // Note: this does not enforce constraints does not attempt to advance the page.
    K('form').save()
    // Submit Page
    K('form').submitPage()
    // Previous Page
    K('form').previousPage()

The Bridged Resource Object

The Bridged Resource object provides access to dynamically load data from bridges.

The bridged resource load method takes an options object as an argument. This object has the following properties:

  • attributes - an array of attributes that you want returned.
  • values - a map of values referenced by your bridged resource parameters.
  • success - a function called when the bridged resource request is complete.
    • Takes one argument, the bridged data.
  • error - a function called when there is an error encountered while processing the bridged resource request.
    • Takes one argument, the error response from the server.
    // Load a bridged resource named 'People' that has no parameters:
    K('bridgedResource[People]').load({
        attributes: ['First Name', 'Last Name', 'Login Id']
        success: function(bridgedData) {
            // Do something with the bridged data response.
            // For example:
            console.log(bridgedData.records);
        }
    });

    // Load a bridged resource named 'Person' that has a parameter. The
    // parameter is configured to reference the value of the Login ID field,
    // which is defined in the Form Builder:
    K('bridgedResource[Person]').load({
        attributes: ['First Name', 'Last Name'],
        values: {'Login ID' : 'Allen'},
        success: function(bridgedData) {
            console.log(bridgedData.record);
        }
    });