UI Extension Javascript API

To interact with the standard form fields from the Javascript of a UI extension, 4me offers the UI Extension Javascript API.

All API calls start with ITRP. For example, the API call ITRP.field('note').val(); can be used to get the current value of the Note field of the Request form.

Get initial values

It is possible to get the initial values of a record when it is opened in edit mode. For example, to make the Attachment field required when a request is edited that has the status Assigned, use the following:

JavaScript
if (ITRP.record.initialValues.get('status') === 'assigned') {
  ITRP.field('attachment').required();
}

The general form of this API call is ITRP.record.initialValues.get('field'). The fields that are available depend on the type of the record that the UI extension is linked to, and are the same as those listed in the Collection Fields section of the respective API:

Note: some of the fields are references, such as the team to which a Request is assigned. You can access the reference attributes (usually id and name / subject) by passing both the name of the reference and the name of the attribute to the API, for example: ITRP.record.initialValues.get('team', 'name').

Distinguish new and existing records

To find out whether the user is adding a new record, use the following:

JavaScript
// Possible values: true and false
var new_record = ITRP.record.new;
if (new_record) { /* ... */ }

Distinguish Self Service and Specialist view

To find out whether the user is using Self Service or the Specialist view, use the following:

JavaScript
// Possible values: 'self_service' and 'full_ui'
var context = ITRP.record.context;
if (context === 'self_service') { /* ... */ }

A practical example of this can be found in Advanced UI Extension Examples.

Interact with form fields in Self Service

The Javascript API offers various functions to interact with the built-in form fields of 4me records. For each type of record and each field, the available functions are listed below. Refer to Functions for descriptions and brief examples of these functions.

Requests

Tasks

Project Tasks

Interact with form fields in the Specialist view

The Javascript API offers various functions to interact with the form fields of records that are available in the Specialist view. For each type of record and each field, the available functions are listed below. Refer to Functions for descriptions and brief examples of these functions.

Requests

Tasks

Project Tasks

Configuration Items

Risks

Functions

required

Use this function to make a field optional or required.

JavaScript
ITRP.field('note').required(); // Make the Note field required
ITRP.field('note').required(true); // Make the Note field required
ITRP.field('note').required(false); // Make the Note field optional

readonly

Use this function to make a field readonly or read/write.

JavaScript
ITRP.field('severity').readonly(); // Make the Severity field readonly
ITRP.field('severity').readonly(true); // Make the Severity field readonly
ITRP.field('severity').readonly(false); // Make the Severity field read/write

val

Use this function to get or set the value of a field.

JavaScript
// Get the value of the Subject field:
var value = ITRP.field('subject').val();

// Set the value of the Subject field to 'New subject':
ITRP.field('subject').val('New subject');

// Clear the value of the Subject field:
ITRP.field('subject').val('');

// Fill a rich text field with HTML:
ITRP.field('note').val({ html: 'This is <b>bold</b> text.' });

show

Use this function to make a hidden field visible.

JavaScript
ITRP.field('note').show(); // Show the note field

hide

Use this function to hide a field.

JavaScript
ITRP.field('note').hide(); // Hide the note field

toggle

Use this function to toggle the visibility of a field.

JavaScript
ITRP.field('note').toggle(true); // Show the note field
ITRP.field('note').toggle(false); // Hide the note field

size

Use this function to get the number of attached files.

JavaScript
var size = ITRP.field('attachment').size();
if (size < 2) { /* ... */ }

placeholder

Use this function to set the placeholder of the note field.

JavaScript
ITRP.field('note').placeholder('Describe your request here…');

on

Use this function to attach an event handler to a field. It is based on the jQuery on() function and takes two required parameters:

JavaScript
// Make the Remarks field required 
// when the Status is changed to 'In Production'
ITRP.field('status').on('change', function() {
  var status = ITRP.field('status').val();
  ITRP.field('remarks').required(status === 'in_production');
});

off

Use this function to remove an event handler from a field. It is based on the jQuery off() function and takes two required parameters:

JavaScript
var set_remarks_value = function() {
  if (ITRP.field('status').val() === 'being_repaired') {
    ITRP.field('remarks').val('Describe what needs to be repaired:');
    // Make sure that the value of the remarks field is only filled in 
    // the first time the status is set to 'Being Repaired':
    ITRP.field('status').off('change', set_remarks_value);
  }
};

ITRP.field('status').on('change', set_remarks_value);

trigger

Use this function to manually trigger an event. It is based on the jQuery trigger() function and takes one parameter:

JavaScript
// Do something when the user changes the status field to another value:
ITRP.field('status').on('change', function() { /* do something ... */ });

// Make sure that the action defined above is also performed 
// when the form is initially displayed:
ITRP.field('status').trigger('change');


// The two statements above can also be combined, as follows.
// This is a common pattern when attaching an event handler.
ITRP.field('status').on('change', function() { 
  /* do something ... */ 
}).trigger('change');