Item list event handlers

The Relativity Forms API includes event handlers and classes used to manipulate item lists.

Summary of item list event handlers

The following table lists the item list event handlers.

Event handler or class Description
itemListModifyActions Modifies the default action buttons for an item list.
itemListModifyColumns Modifies columns in an item list.
itemListReloaded Executes each time the item list is reloaded.

Summary of item list event handler APIs and objects

The following table lists the item list APIs and related objects.

Event handler or class Description
columnsApi Provides methods for modifying columns on item list, such as the adding formatters, setting titles, or removing columns.
itemListActionsApi Describes an item list action button.
Item List Action button object Modifies action buttons on the item list.
View object Identifies the current item list.
Visibility Rule class Indicates the visibility of action buttons for an item list.

Item List Event Handlers

itemListModifyActions

This event is executed immediately before the Item List is rendered. It provides the opportunity to modify default action buttons for the Item List. If the event handler does not call the initialize, addAction or the addDefaultActions method on the itemListActionsApi object, the default action buttons will be added to the Item List.

The itemListModifyActions event also provides an opportunity to modify how the item list gets data. If the event handler does not call the setCustomGetDataFunction method on the itemListActionsApi object, the default method or retrieving item list data through the Object Manager API will be used.

The event handler is expected to perform one or more of the following tasks:

  • setup the action buttons itself (by calling initialize, addAction or addDefaultActions methods).
  • leave the Item List action bar intact (do not call initialize, addAction or addDefaultActions), thus triggering adding the default action buttons by the application.
  • define a custom get-data function the item list will use to populate the item list. This will override the default behavior, which uses the Object Manager API to get data.

Syntax

Copy 
function(itemListActionsApi: <object>, view: <object>)

Parameters

The following tables lists the input parameters:

Parameter Description
itemListActionsApi: <object> Modifies action buttons on the item list. For more information, see itemListActionsApi.
view: <object> Identifies the current item list. This object has these fields used for item list identification: (see below)

view: <object>ArtifactID - number - The artifact ID of the view.
Name - string - The name of the view.
ObjectTypeID - number - The artifact type ID of the object displayed in the view.

Ambient variables

Name Description
this On execution of the event handler, Relativity Forms binds the value of the "this" keyword to an object which provides data and functionality related to the active form. For more information, see this Binding.
convenienceApi Globally available to all event handlers is the active application's convenienceAPI object. For more information, see convenienceAPI object.
eventNames Globally available to all event handlers is the active application's eventNames object. For more information, see eventNames object in Additional Forms API objects.

Example

See code samples for itemListActionsApi.

itemListModifyColumns

Modifies columns in an item list through the columnsApi. This event is executed once per item list when it is added to the form.

Syntax

Copy 
function(columnsApi: <object>, view: <object>)

Parameters

The following tables lists the input parameters:

Parameter Description
columnsApi: <object> Provides methods for modifying columns on item list, such as the adding formatters, setting titles, or removing columns. The ColumnsApi is exposed as a part of the event handler API. For more information, see columnsApi.
view: <object> Identifies the current item list. This object has these fields used for item list identification: (see below)

view: <object>ArtifactID - number - The artifact ID of the view.
Name - string - The name of the view.
ObjectTypeID - number The artifact type ID of the object displayed in the view.

Ambient variables

Name Description
this On execution of the event handler, Relativity Forms binds the value of the "this" keyword to an object which provides data and functionality related to the active form. For more information, see this Binding.
convenienceApi Globally available to all event handlers is the active application's convenienceAPI object. For more information, see convenienceAPI object.
eventNames Globally available to all event handlers is the active application's eventNames object. For more information, see eventNames object in Additional Forms API objects.

Example

See code samples for columnsApi.

itemListReloaded

Executes each time the item list is reloaded. The itemListReloaded event handler executes in the view model popup when the item list is reloaded and provides a way to read the results of the item list. For more information, see Popup eventHandlerFactory.

Syntax

Copy 
function(data: <object> )

Parameters

The following table lists the input parameters:

Parameter Description
data: <object> Describes the new item list startup data. This object has these fields: (see below)

data: objectCurrentStartIndex - Number - The current starting index (1 is the first result). Results - Array<object> - Array of item list row objects. TotalCount - Number - The total amount of results.

Ambient variables

Name Description
this On execution of the event handler, Relativity Forms binds the value of the "this" keyword to an object which provides data and functionality related to the active form. For more information, see this Binding.
convenienceApi Globally available to all event handlers is the active application's convenienceAPI object. For more information, see convenienceAPI object.
eventNames Globally available to all event handlers is the active application's eventNames object. For more information, see eventNames object in Additional Forms API objects.

Example

Copy 
(function(eventNames, convenienceApi) {
     var eventHandlers = [];

     eventHandlers[eventNames.ITEM_LIST_RELOADED] = function(data) {
          console.log("Inside ITEM_LIST_RELOADED event handler");
          console.log(data);
          /*
               {
                    "CurrentStartIndex": 1,
                    "Results": [
                         {
                              "column1_name": "row1_column1_value",
                              "column2_name": "row1_column2_value"
                         },
                         {
                              "column1_name": "row2_column1_value",
                              "column2_name": "row2_column2_value"
                         }, ...
                    ],
                    "TotalCount": 20
               }
          */
          var buttonToDisable = document.getElementById("my-button");
          buttonToDisable.disabled = !data.TotalCount; // disable button when there are is at least one result in the item list.
     };

     return eventHandlers;
}(eventNames, convenienceApi));

Item List Action button object

Describes an item list action button.

Field Type Description
title String The title of an action button.
type ACTION_TYPES The type of action button. See constants.
action Function A function that executes when a user clicks the action button.
disabled Boolean Set to true to disable the action button, or false to enable it.
order Number The order of the action button.

View object

Identifies the current item list.

This object has these fields used for item list identification:

Field Type Description
ArtifactID number The artifact ID of the view.
Name string The name of the view.
ObjectTypeID number The artifact type ID of the object displayed in the view.

Visibility Rule class

Indicates the visibility of action buttons for an item list.

Field Type Description
Delete Boolean Set to true to make the Delete button visible, or false to hide it.
Link Boolean Set to true to make the Link button visible, or false to hide it.
New Boolean Set to true to make the New button visible, or false to hide it.
Unlink Boolean Set to true to make the Unlink button visible, or false to hide it.