Customizing with JavaScript

Kinetic JS Objects

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

Important! 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 K provides high-level API access.

Kinetic Object	Purpose
`K(selector)`	Selects an object based on the 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: \n - `method` - string name of the method, e.g. `'GET'` \n - `path` - the URL or path to access. \n - `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 Embedding Subforms into Forms 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 reserved and 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.

Notes

Some of the functions that 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, the form will eventually self-correct and hide the field again.

The following functions can cause conflicts:

hide

show

disable

enable.
In many cases, leaving these conditions in their default state should allow
you use the functions in JavaScript event code, but this is not guaranteed.

Field Object	Purpose
`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]').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 methods for manipulating the form its properties.

Form Object	Purpose
`K('form').slug()`	Returns the slug 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. This `find` will not return a subform’s elements.
`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 method does not enforce constraints and 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 the ability to dynamically load data from bridges.

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

Bridged Resource Object	Purpose
`attributes`	An array of attributes that you want to be returned.
`metadata`	A map of metadata parameters that will be passed to the bridge adapter. Note: 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 that's called when the bridged resource request is complete. Takes one argument, the bridged data.
`error`	A function that's called when there is an error encountered while processing the bridged resource request. Takes one argument, the error response from the server.

Here's an example of a bridged resource load script:

    // 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);
        }
    });

You can also call these other methods:

Method	Purpose
`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 that are used in parameters.
`K('bridgedResource[People]').attributes()`	Returns an array of values that 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:

Function	Purpose
`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:

Function	Purpose
`K('section[Section Name]').name()`	Returns the section name.
`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.

Like 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:

Function	Purpose
`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.

Like 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:

Function	Purpose
`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.

Like other object types, the hide and show behavior is conditional and may be superseded by the form’s
behavior.

Kapp Object

Function	Purpose
`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

Function	Purpose
`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.

    // 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]

Embedding Subforms into Forms

The K.load function allows a form/submission to be loaded into the current page. Loading and submission are performed 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 the 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 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.