Customizing with Javascript

Javascript can be used to extend forms. This article outlines the out of box Kinetic JS selectors and methods.

Kinetic JS Objects

The Kinetic Runtime API provides has a number of methods and properties for the various Kinetic objects.

❗️
Do not modify any Kinetic methods or properties. Changing them may have adverse affects on behavior and is not supported!

Kinetic Object

The Kinetic object, or K provides high-level API access.

K(selector) - selects an object based on a selection criteria. See Using Kinetic Selectors for more information.
K.select(selector) - an alternative way to execute object selections.
K.api(method, path, options) - executes an asynchronous API call and safely updates the form display upon completion. It takes 3 arguments:
- method - string name of the method, e.g. 'GET'
- path - the URL or path to access.
- options - a jQuery-compatible AJAX options config.
K.reset() - completely resets the Kinetic object. Useful for kapp-level pages embedding forms dynamically.
K.as(form) - given a Kinetic Form object execute API functionality as that form. Used primarily in embedded and child forms.
K.use(form) - this advanced method is used to change the current active form to the Form object provided.
K.load(options) - asynchronously load an embedded form. See Using Subforms for more information.

Note: The K.ready() function is not the same as the ready function provided in the bundle customization object.
This method is a reserved method that should only be called by Core Edition generated code.

Field Object

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

📘
Important Notes of the Field Object
Some of the functions which correspond to conditions specified within the builder may cause conflicts. For example
if you define a “Visible” condition in the builder of “Hidden” and then call the show method, eventually the form
will self-correct and hide the field again. Functions which fall into this criteria are: hide, show, disable,
and enable. In many cases leaving these conditions to their default state should allow
you use the functions in JavaScript event code.

K('field[Field Name]').name() - returns the name of the field.
K('field[Field Name]').type() - returns the field type.
K('field[Field Name]').form() - returns the Form object that the current field belongs to.
K('field[Field Name]').allowsMultiple() - returns true or false for attachments, undefined for non-attachment fields.
K('field[Field Name]').element() - returns the DOM element representing the field’s input element(s).
K('field[Field Name]').wrapper() - returns the DOM element representing the div which contains the field’s DOM elements (label, input, etc.)
K('field[Field Name]').value(newValue) - sets the field value to newValue.
K('field[Field Name]').value() - returns the current value of the field.
K('field[Field Name]').hide() - hides the current field.
K('field[Field Name]').show() - displays the current field.
K('field[Field Name]').disable() - sets the field to be disabled.
K('field[Field Name]').enable() - sets the field to be enabled.
K('field[Field Name]').options() - returns the options DOM elements list for “dropdown”, “checkbox”, and “radio” fields.
K('field[Field Name]').options(newOptions) - given an array of objects with a ‘label’ and ‘value’ key create new options DOM elements for the field.
K('field[Field Name]').validate() - runs field constraint validations and returns the results or an empty array if it is a valid field.

Form Object

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

K('form').slug() - returns the slug of the current form.
K('form').name() - returns the name of the current form.
K('form').description() - returns the description of the current form.
K('form').attributes() - returns all of the attributes configured for the form.
K('form').attributes('name') - returns a specific attribute configured for the form.
K('form').reviewMode() - returns true if the form is being rendered in review mode.
K('form').embeddedMode() - returns true if the form is currently embedded.
K('form').element() - returns the form DOM element representing the current form.
K('form').find(selector) - given a jQuery-style selector, find DOM elements within this form. Takes subforms into consideration, this find will not return a subform’s element(s).
K('form').serialize() - returns a serialized object representing the fields and values for the current page.
K('form').validate() - executes client-side constraint validation for all fields on the current page. It returns an object with keys representing fields with violations and an array of violation messages.
K('form').basePath() - returns the path the base of the REST API.
K('form').kappPath() - returns the REST API path for the kapps resource.
K('form').formPath() - returns the REST API path for the forms resource.
K('form').submissionPath() - returns the REST API path for the current submission.
K('form').save() - performs the “Save for Later” action. Note: this does not enforce constraints does not attempt to advance the page.
K('form').submitPage() - performs the “Submit Page” action.
K('form').previousPage() - performs the “Previous Page” action.

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.
metadata - a map of metadata parameters that will be passed to the bridge adapter.
- The supported metadata parameter names are dependent on the bridge adapter being used by the active bridge mapping.
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.

Here is an example bridged resource load:

    // Load a bridged resource named 'People' that has no parameters:
    K('bridgedResource[People]').load({
        attributes: ['First Name', 'Last Name', 'Login Id'],
        metadata: {
          "limit": "5",
          "pageToken": "i0j70ogl9638s4ccs0bvdkrqftxa6kvzt52",
          "order": "Login Id:asc"
        },
        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);
        }
    });

In addition to the load method you can call these other methods:

K('bridgedResource[People]').name() - returns the name of the bridged resource.
K('bridgedResource[People]').type() - returns the bridged resource type, either “Single” or “Multiple”
K('bridgedResource[People]').dependencies() - returns an array of field names which are used in parameters.
K('bridgedResource[People]').attributes() - returns an array of values which will be returned from the bridge.
K('bridgedResource[People]').metadata() - returns a map of metadata properties sent to the bridge.

Page Object

The page object provides information about the current form page. It has the following functions:

K('page').id() - returns the current page ID.
K('page').name() - returns the current page name.

Section Object

The section object provides information about a section on the current page. It has the following functions:

K('section[Section Name]').name() - returns the name of the section.
K('section[Section Name]').element() - returns the DOM element representing the section.
K('section[Section Name]').hide() - hides the section, respecting the omit values behavior.
K('section[Section Name]').show() - shows the section, respecting the omit values behavior.

As documented with other object types the hide and show behavior is conditional and may be superseded by the form’s
behavior.

Button Object

The button object provides information about a button on the current page. It has the following functions:

K('button[Submit Button]').name()- returns the button name.
K('button[Submit Button]').element() - returns the DOM element representing the button.
K('button[Submit Button]').hide() - hides the button.
K('button[Submit Button]').show() - shows the button.
K('button[Submit Button]').disable() - enables the button.
K('button[Submit Button]').enable() - disables the button.

As documented with other object types the hide, show, enable, and disable behavior is
conditional and may be superseded by the form’s behavior.

Content Object

The content object provides information about a content field on the current page. It has the following functions:

K('content[Content Name]').name() - returns the content field's name.
K('content[Content Name]').element() - returns the DOM element representing the content field.
K('content[Content Name]').show() - shows the content field.
K('content[Content Name]').hide() - hides the content field.

As documented with other object types the hide and show behavior is conditional and may be superseded by the form’s
behavior.

Kapp Object

K('kapp').name() - returns the kapp name.
K('kapp').slug() - returns the kapp slug.
K('kapp').attributes() - returns all of the attributes configured for the kapp.
K('kapp').attributes('name') - returns a specific attribute configured for the kapp.

Space Object

K('space').name() - returns the space name.
K('space').slug() - returns the space slug.
K('space').attributes() - returns all of the attributes configured for the space.
K('space').attributes('name') - returns a specific attribute configured for the space.

Submission Object

K('submission').id() - returns the submission ID or null if a new submission.
K('submission').value(fieldName) - returns the value from a field that was on a previous page.

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.

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')
    // Selecting the current identity.
    K('identity')

Nesting Selectors

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]')

Selecting Elements by Name

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]')

The Bundle Object

Bundle is a helper object designed to be used in javascript applications. The bundle object provides a number of static methods that are automatically included with each request.

KD.Bundle.apiLocation()

Returns the path of the latest API version including the application context path.

Example:

KD.Bundle.apiLocation()                                /kinetic/SPACE_SLUG/app/api/v1

KD.Bundle.apiLocation(version)

Returns the path of the specified API version including the application context path.

Example:

KD.Bundle.apiLocation('v1')                            /kinetic/SPACE_SLUG/app/api/v1

KD.Bundle.contextPath()

Returns the context path for the application.

Example:

KD.Bundle.contextPath()                                /kinetic

KD.Bundle.kappLocation()

Returns the path of the current Kapp including the application context path.

Example:

KD.Bundle.kappLocation()                               /kinetic/SPACE_SLUG/KAPP_SLUG

KD.Bundle.kappLocation(slug)

Returns the path of the specified Kapp including the application context path.

Example:

KD.Bundle.kappLocation('catalog')                      /kinetic/SPACE_SLUG/catalog

KD.Bundle.kappSlug()

Returns the slug of the current Kapp.

Example:

KD.Bundle.kappSlug()                                   catalog

KD.Bundle.location()

Returns the path of the current bundle including the application context path.

Example:

KD.Bundle.location()                                   /kinetic/app/bundles/SPACE/BUNDLE

KD.Bundle.spaceLocation()

Returns the path of the current Space including the application context path.

Example:

KD.Bundle.spaceLocation()                              /kinetic/SPACE_SLUG

KD.Bundle.kappSlug()

Returns the slug of the current Space.

Example:

KD.Bundle.spaceSlug()                                  acme

KD.Bundle.identity()

Returns the username of the user making the request.

Example:

KD.Bundle.identity()                                   [email protected]

Using Subforms

The K.load function allows a form/submission to be loaded into the current page, it will be loaded and submitted via AJAX interactions.

Below is an example usage of the K.load function.

K.load({
  path: '/kinetic/acme/catalog/ipad-request',
  container: '#subform-div',
  loaded: function(form) { ... },
  created: function(data, action) { ... }
  updated: function(data, action) { ... },
  completed: function(data, action) { ... }
});

Options/Callbacks

path path to the form (including space, kapp, and form slugs) that will be loaded
container CSS selector that specifies where the loaded form should be placed
loaded called after the form is loaded and appended to the page, it is passed the following parameters
- form the Form object representing the loaded form, see Using Kinetic Objects for details
created called after the page save/submission results in the successful creation of a new submission, it is passed the following parameters
- data contains the following properties
  - submission the submission API result, see the REST API documentation for details
- action contains the following action functions
  - default loads the next displayable page for the embedded submission, note that this is done automatically unless the stop action (below) is called
  - close removes the embedded form from the page
  - stop prevents the default action from being done
updated called after each save/submit following creation, it is passed the following parameters
- data contains the following properties
  - submission the submission API result, see the REST API documentation for details
- action contains the following action functions
  - default loads the next displayable page for the embedded submission, note that this is done automatically unless the stop action (below) is called
  - close removes the embedded form from the page
  - stop prevents the default action from being done
completed called after page submit results in completion of the submission, it is passed the following parameters
- data contains the following properties
  - submission the submission API result, see the REST API documentation for details
- action contains the following action functions
  - default loads the confirmation page for the embedded submission, note that this is done automatically unless the stop action (below) is called
  - close removes the embedded form from the page
  - stop prevents the default action from being done
unauthorized called when the http request to load the form returns a status code of 401
(indicating the user making the request is not authenticated and the form requires authentication).
This callback is not passed any parameters.
forbidden called when the http request to load the form returns a status code of 403
(indicating the authenticated user does not have access to submit the form).
This callback is not passed any parameters.
notFound called when the http request to load the form returns a status code of 404
(indicating that the kapp slug and form slug provided do not match a form).
This callback is not passed any parameters.
error called when the http request to load the form returns any status code that indicates
an error. Note that if one of the status codes mentioned above is returned, this callback will be
called in addition to the more specific callback. This callback is not passed any parameters.

Scenarios

For a simple, one page, service item the created and completed callbacks will likely be called at the same time.
For a multi-page service item, the created callback will be called upon submission of the first page. Any subsequent save or submit will result in the update callback being called. And finally, when the last page has been submitted the completed callback will be called.

Updated over 2 years ago

Kinetic JS Objects

❗️

Kinetic Object

Field Object

📘Important Notes of the Field Object

Form Object

Bridged Resource Object

Page Object

Section Object

Button Object

Content Object

Kapp Object

Space Object

Submission Object

Using Kinetic Selectors

Examples

Nesting Selectors

Selecting Elements by Name

The Bundle Object

KD.Bundle.apiLocation()

KD.Bundle.apiLocation(version)

KD.Bundle.contextPath()

KD.Bundle.kappLocation()

KD.Bundle.kappLocation(slug)

KD.Bundle.kappSlug()

KD.Bundle.location()

KD.Bundle.spaceLocation()

KD.Bundle.kappSlug()

KD.Bundle.identity()

Using Subforms

Options/Callbacks

Scenarios

📘
Important Notes of the Field Object