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 loadedcontainer
CSS selector that specifies where the loaded form should be placedloaded
called after the form is loaded and appended to the page, it is passed the following parametersform
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 parametersdata
contains the following propertiessubmission
the submission API result, see the REST API documentation for details
action
contains the following action functionsdefault
loads the next displayable page for the embedded submission, note that this is done automatically unless the stop action (below) is calledclose
removes the embedded form from the pagestop
prevents the default action from being done
updated
called after each save/submit following creation, it is passed the following parametersdata
contains the following propertiessubmission
the submission API result, see the REST API documentation for details
action
contains the following action functionsdefault
loads the next displayable page for the embedded submission, note that this is done automatically unless the stop action (below) is calledclose
removes the embedded form from the pagestop
prevents the default action from being done
completed
called after page submit results in the completion of the submission, it is passed the following parametersdata
contains the following propertiessubmission
the submission API result, see the REST API documentation for details
action
contains the following action functionsdefault
loads the confirmation page for the embedded submission, note that this is done automatically unless the stop action (below) is calledclose
removes the embedded form from the pagestop
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.
Updated 3 months ago