Additional Forms API objects

The Relativity Forms API includes objects and functions for pop-up windows. It also includes a class for event names.

Summary of additional Forms API objects and functions

The following table lists additional Forms API objects and functions.

Filter

eventNames object

Represents the event names used in the Relativity Forms API. For convenience, the event names on the following object are sorted in property order.

const EVENT_NAMES = {
    CREATE_ACTION_BAR: "createActionBar",
    CREATE_CONSOLE: "createConsole",
    EVENT_HANDLERS_REGISTERED: "eventHandlersRegistered",
    HYDRATE_LAYOUT: "hydrateLayout",
    HYDRATE_LAYOUT_COMPLETE: "hydrateLayoutComplete",
    ITEM_LIST_MODIFY_ACTIONS: "itemListModifyActions",
    ITEM_LIST_MODIFY_COLUMNS: "itemListModifyColumns",
    ITEM_LIST_RELOADED: "itemListReloaded",
    OVERRIDE_PICKER_DATASOURCE: "overridePickerDataSource",
    PAGE_INTERACTION: "pageInteraction",
    PAGE_LOAD_COMPLETE: "pageLoadComplete",
    PAGE_UNLOAD: "pageUnload",
    POST_DELETE: "postDelete",
    POST_OBTAIN_ADDITIONAL_DATA: "postObtainAdditionalData",
    POST_SAVE: "postSave",
    PRE_DELETE: "preDelete",
    PRE_SAVE: "preSave",
    REPLACE_DELETE: "replaceDelete",
    REPLACE_FILE_ACTIONS: "replaceFileActions",
    REPLACE_GET_NEW_OBJECT_INSTANCE: "replaceGetNewObjectInstance",
    REPLACE_OBTAIN_ADDITIONAL_DATA: "replaceObtainAdditionalData",
    REPLACE_READ: "replaceRead",
    REPLACE_READ_DELETE_DEPENDENCY_LIST: "replaceReadDeleteDependencyList"
    REPLACE_SAVE: "replaceSave",Item List Types enumeration
    TRANSFORM_LAYOUT: "transformLayout",
    UPDATE_ACTION_BAR: "updateActionBar",
    UPDATE_CONSOLE: "updateConsole",
    VALIDATE_SAVE: "validateSave",
    VALIDATION: "validation"
};

popupControlApi object

Provides functionality for closing and accessing properties of a pop-up window.

Syntax

const popupControlApi = {
     closePopup,          // Function
     isPopupSafeAndLive,  // Function
     popup                // Window
}

Properties

Popup eventHandlerFactory function

Creates event handlers that run within a pop-up window created by invocations of methods on the convenienceApi.relativityFormsPopup.

The Add(), Edit(), and View() methods all take an optional eventHandlerFactory: Function property. This mechanism facilitates communication between the opener and pop-up Relativity Forms applications. It exposes the ability to add event handlers to a pop-up instance of Relativity Forms when the window is opened.

The factory function has the following signature:

function eventHandlerFactory(popupControlApi, popupEventNames, popupConvenienceApi)

Parameters

Return type

An event handler object. See Relativity Forms API for more information.

Example

(function(eventNames, convenienceApi) {
    var eventHandlers = {};
 
    eventHandlers[eventNames.PAGE_LOAD_COMPLETE] = function() {
        console.log("main PAGE_LOAD_COMPLETE called");
        var popupMode = "openView";
 
          // the popup eventHandlerFactory function, passed as a parameter for relativityFormsPopup
        var eventHandlerFactory = function(popupControlApi, popupEventNames, popupConvenienceApi) {
            var popupEventHandlers = {};
            popupEventHandlers[popupEventNames.PAGE_LOAD_COMPLETE] = function() {
                console.log("popup PAGE_LOAD_COMPLETE called");
            };
            return popupEventHandlers;
        };
 
        var openArgs = {
            workspaceId: this.workspaceId,
            artifactTypeId: <Number>,
            artifactId: <Number>,
            parentArtifactId: <Number>,
            eventHandlerFactory: eventHandlerFactory
        };
 
        convenienceApi.relativityFormsPopup[popupMode](openArgs);
    };
 
    return eventHandlers;
}(eventNames, convenienceApi));

ColumnDefinition class

The base class that describes a column of data. This object is extended by the ItemListColumn class. If Event Handler code is defining a custom ItemListDataProvider.getColumns function, it will need to return column objects in the format described here.

Syntax

See the syntax sample for ItemListColumn.

Properties

ItemListColumn Properties

An ItemListColumn extends the ColumnDefinition class and contains the following additional properties:

Methods

None

CellContent class

Configuration that describes how the item list displays the content of cells in the column. This may need to be defined in Event Handler code if a custom ItemListDataProvider.getColumns method is being defined since it defines how those columns will show information.

Properties

{ "col_A": "row_N col_A value", "col_B": "row_N col_B value" }

Example

CellContent formatDefinitions examples

// No formatting
// input item list data: [{ "col_A": "One" }, { "col_A": "Two" }]
// rendered item list data: "One", "Two"
var cellContent = {
    dataLocation: "col_A",
    formatDefinitions: Null
}
 
// BooleanValues
// input item list data: [{ "col_A": true }, { "col_A": false }]
// rendered item list data: "Yes", "No"
var cellContent = {
    dataLocation: "col_A",
    formatDefinitions: [{
        name: "BooleanValue",
        options: {
            trueLabel: "Yes",
            falseLabel: "No"
    }]
}
 
// Custom
// input item list data: [{ "firstName": "Salt", "lastName": "Pepper" }]
// rendered item list data: <span>Salt Pepper</span> element
var cellContent = {
    dataLocation: "firstName",
    formatDefinitions: [{
        name: "BooleanValue",
        options: {
            format: function(content, dataItem) {
                console.log(content);    // "Salt"
                console.log(dataItem);    // { "firstName": "Salt", "lastName": "Pepper" }
 
                var spanElement = document.createElement("span");
                spanElement.textContent = content + " " + dataItem["lastName"];
                return spanElement;
            }
    }]
}
 
// DateTime
// input item list data: [{ "col_A": "2009-04-27T18:44:50.217" }]
// rendered item list data: "4/27/2009"
var cellContent = {
    dataLocation: "col_A",
    formatDefinitions: [{
        name: "DateTime",
        options: {
            includeTime: false,
            locale: "en-US"
    }]
}
 
// HtmlText
// input item list data: [{ "col_A": "<i>Italic Text</i>" }]
// rendered item list data: "Italic Text" in italics
var cellContent = {
    dataLocation: "col_A",
    formatDefinitions: [{
        name: "HtmlText",
        options: {}
    ]
}
 
// Image
// input item list data: [{ "col_A": { "imgSrc": "./my/cat/picture.jpg", "imgAlt": "cute cat picture" }]
// rendered item list data: <img src="./my/cat/picture.jpg" alt="cute cat picture"> element
var cellContent = {
    dataLocation: "col_A",
    formatDefinitions: [{
        name: "Image",
        options: {
            srcLocation: "imgSrc",
            alt: "imgAlt"
        }
    ]
}
 
// SingleValue
// input item list data: [{ "col_A": { "Inner Key": "Inner Value" }]
// rendered item list data: "Inner Value"
var cellContent = {
    dataLocation: "col_A",
    formatDefinitions: [{
        name: "SingleValue",
        options: {
            dataLocation: "Inner Key"
        }
    ]
}
 
// MultipleValue
// input item list data: [{ "col_A": [{ "id": "1", "value": "One" }, { "id": "2", "value": "Two" }] }]
// rendered item list data: "One;Two"
var cellContent = {
    dataLocation: "col_A",
    formatDefinitions: [{
        name: "MultipleValue",
        options: {
            dataLocation: "Inner Key",
            idLocation: "",
            delimiter: ";"
        }
    ]
}
 
// TruncatedText
// input item list data: [{ "col_A": "Very long text" }]
// rendered item list data: "Very..."
var cellContent = {
    dataLocation: "col_A",
    formatDefinitions: [{
        name: "TruncatedText",
        options: {
            maxLength: 7
        }
    ]
}

CellContentAlignment enumeration

Defines cell content alignment.

Enums

HeaderContent class

Represents a column header definition. When creating your own ItemListDataProvider.getColumns method and need to fill in this field, it is recommended to set the indicators parameter to Null, as IColumnIndicator instances cannot be created manually.

Syntax

var toolbarHeaderContentElement = document.getElementById("header");
 
 
var headerContent = {
    clickable: true,
    indicators: Null,
    title: "Title",
    toolbarContent: toolbarHeaderContentElement
};

Properties

Methods

None

IColumnIndicator interface

Defines an interface of a column indicator. Column indicators are typically used to add indicator icons to column headers, such as sort and filter icons. This cannot be manually created by users, but it is detailed here for when you're creating your own ItemListDataProvider.getColumns method. Instead, it is used internally to generate sort and filter icons for column headers for applicable item lists.

Methods

render()

Returns an indicator element as a value suitable for the consumption of Hyperscript function of SkateJS.

Parameters

None

Return type

String | HTMLElement | Array | Null

FieldMetadata class

Contains information about a single field.

Syntax

var fieldMetadata = {
     artifactID: 0,
     artifactViewFieldID: 0,
     associativeObjectTypeID: 0,
     columnName: "Name",
     fieldTypeID: 0, // fixed length text
     filterType: "Choice",
     headerName: "Header",
     itemListType: "Text",
     isSystem: false
};

Properties

Methods

None

Field Type ID enumeration

Defines the number identification for field types.

Enums

Filter Types enumeration

Defines the types of filters that can be used in an item list.

Enums

QueryRequest class

Contains request details for an item list query.

Syntax

var QueryRequest = {
     startIndex: 0,
     pageSize: 0,
     filters: [filter1, filter2],
     sorts: [sort1, sort2],     
     idsToInclude: [0, 1, 2],     
     idsToExclude: [3, 4, 5]
};

Properties

Methods

None

Filter class

Represents a single filter applied to a request.

Syntax

var filter = new rwc.dataManagement.conditions.Filter("advancedText", [condition], true);

Properties

Methods

None

Condition class

Represents a single condition of a filter.

Syntax

var condition = {
     operator: "is less than",
     value: 10,
     displayValue: "is less than 10"
};

Properties

Methods

None

Sort class

Represents sort definition.

Syntax

var sort = {
     column: "Name",
     direction: "asc"
};

Properties

Methods

None

QueryResponse class

Represents a response from the Query method. The response is a transformation of the Query API Endpoint response from the Object Manager, where the entries in the Objects field are mapped to the Results field such that every entry has the ArtifactID along with any requested fields (e.g. Name) as its properties.

Syntax

var queryResponse = {
     Results: [
          {
               "Name": "test1 name",
               "ArtifactID": 1039665
          },
          {
               "Name": "test2 name",
               "ArtifactID": 1039666
          }
     ],
     TotalCount: 2,
     CurrentStartIndex: 1,
};

Fields

Properties

None

Methods

None

itemListDataProvider object

The itemListDataProvider is a part of the multi/single-list picker component that is used to retrieve data and provide the information required to render its inner lists.

The intention is for users to construct the object themselves and then use the custom provider to build SingleListPickerModal or MultiListPickerModal.

Syntax

itemListDataProvider = {
     getFieldMetadata,                    // function
     getColumns,                              // function
     getTextIdentifierColumnName,     // function
     query,                                   // function
     getValuesByIds                         // function
}

Methods

See the following subsections for information about these methods:

• getFieldMetadata(String: fieldName)
• getColumns(Function: itemListReloadHandler)
• getTextIdentifierColumnName()
• query(Object: request, Array<Object>|Null: columns)
• getValuesByIds(Array<Number>: ids)

getFieldMetadata(String: fieldName)

This method returns a FieldMetadata object for a given field name. The multi-list picker component uses this method to retrieve information about fields. 

Parameters

Return Type

Promise<FieldMetadata>

Syntax

var itemListDataProvider = {
     // ...
     getFieldMetadata: function(fieldName) {
          var metaData = {
               artifactID: 0,
               artifactViewFieldID: 0,
               associativeObjectTypeID: 0,
               columnName: "Name",
               fieldTypeID: 0, // fixed length text
               filterType: "None",
               headerName: Null,
               isSystem: false
               itemListType: "Text",
          };
          return convenienceApi.promiseFactory.resolve(metaData);
     },
     // ...
};

getColumns(Function: itemListReloadHandler)

This method returns an array of ItemListColumn objects. These objects are used by the inner item lists of the multi-list picker component to render columns. The itemListReloadHandler reloads item list data when invoked.

Parameters

Return Type

Promise<Array<ItemListColumn>>

Syntax

var itemListReloadHandler = function() {
     console.log("Reloading item list");
};
 
 
var itemListDataProvider = {
     // ...
     getColumns: function(itemListReloadHandler) {
          var toolbarContentElement = document.createElement("span");
        toolbarContentElement.innerText = "Content of Toolbar Content element";
        var noop = function () {};
          var itemListColumn1 = {
               id: "0",
            actAsAdvanced: false,
            defaultWidth: 150,
            content: {
                comparer: Null,
                dataLocation: "ArtifactID", // key to look for in each data entry
                formatDefinition: Null
            },
            contentAlignment: Null,
            headerContent: {
                clickable: false,
                indicators: Null,
                title: Null,
                toolbarContent: toolbarContentElement
            },
            highlighted: false,
            minWidth: 75,
            resizable: true,
            separatorVisible: true,
            title: "Artifact ID",
            width: 150,
            wrapped: true,
 
            filter: Null,
            filterable: false,
            filterAdvanced: false,
            filterTitle: Null,
            sortable: false,
            sortDirection: Null,
          };
 
          return convenienceApi.promiseFactory.resolve([
               itemListColumn1,
               // ...
          ]);
     },
     // ...
};

Example

var itemListReloadHandler = function(value) {
     console.log("itemListReloadHandler called with value: " + JSON.stringify(value));
};
 
itemListDataProvider.getColumns(itemListReloadHandler).then(function(itemListColumn) {
     console.log("itemListColumn: " + JSON.stringify(itemListColumn));
});

getTextIdentifierColumnName()

This method returns the name of the column that is the identifier of the row, usually the first column that is seen. For example Name or ArtifactID.

Parameters

None

Return Type

String

Syntax

var itemListDataProvider = {
     // ...
     getTextIdentifierColumnName: function() {
          return "Name";
     },
     // ...
};

Example

var textIdentifierColumnName = itemListDataProvider.getTextIdentifierColumnName();

query(Object: request, Array | Null: columns)

This method returns a promise that resolves to an object that has a shape which is the same as QueryResponse. A request variable is an object that represents the body of the query. The columns variable is an array of objects that defines columns to include in the result set.

Parameters

Return Type

Promise<QueryResponse>

Syntax

var itemListDataProvider = {
     // ...
     query: function(request, columns) {
          var results = [
               {
                    "Name": "test1 name",
                    "ArtifactID": 1
               },
               {
                    "Name": "test2 name",
                    "ArtifactID": 2
               }
          ];
 
 
          return convenienceApi.promiseFactory.resolve({
               "Results": results,
               "TotalCount": results.length,
               "CurrentStartIndex": 1
          });
     },
     // ...
};

Example

itemListDataProvider.query(request, columns).then(function(result) {
     console.log("results: " + JSON.stringify(result));
});

getValuesByIds(Array<Number>: ids)

This method returns a promise that resolves to an array of data items having given identifiers.

Parameters

Return Type

Promise<QueryResponse.Results>

Syntax

var itemListDataProvider = {
     // ...
     getValuesByIds: function(ids) {
          return [
               {
                    "Name": "test1 name",
                    "ArtifactID": 1
               },
               {
                    "Name": "test2 name",
                    "ArtifactID": 2
               }
          ];
     },
     // ...
};

Example

itemListDataProvider.getValuesByIds(ids).then(function(values) {
     console.log("values: " + JSON.stringify(values));
});

itemListSettingPersistenceService object

Used by single and multiple list picker components to store and retrieve their item list settings.

Syntax

itemListSettingPersistenceService = {
     getGridStyle,                    // function
     getFiltersVisible,               // function
     getItemListState,               // function
     getItemListStateOrDefault,     // function
     getItemListColumnWidths,     // function
     setGridStyle,                    // function
     setFiltersVisible,               // function
     setItemListState,               // function
     setItemListColumnWidth,          // function
}

Methods

See the following subsections for information about these methods:

• getGridStyle()
• getFiltersVisible(String: itemListKey, Number: workspaceId)
• getItemListState(String: itemListKey)
• getItemListStateOrDefault(String: itemListKey, String: columnWidthsKey)
• getItemListColumnWidths(String: columnWidthsKey)
• setGridStyle(Boolean: gridStyleValue)
• setFiltersVisible(String: itemListKey, Boolean: filtersVisibleValue)
• setItemListState(String: itemListKey, Object: itemListStateValue)
• setItemListColumnWidth(String: itemListKey, String: columnKey, Number: width)

getGridStyle()

Gets the grid style setting for a particular item list.

Parameters

None

Return type

Promise<Boolean> - returns the grid style setting.

Syntax

var itemListSettingPersistenceService = {
     // ...
     getGridStyle: function() {
          return convenienceApi.promiseFactory.resolve(false);
     },
     // ...
};

Example

itemListSettingPersistenceService.getGridStyle().then(function(value){
    console.log("The grid style is currently set to" + value);
});

getFiltersVisible(string itemListKey, number workspaceId)

Gets the filters visible setting for a particular item list.

Parameters

Return type

Promise<Boolean>

Syntax

var itemListSettingPersistenceService = {
     // ...
     getFiltersVisible: function(itemListKey, workspaceId) {
          return convenienceApi.promiseFactory.resolve(false);
     },
     // ...
};

Example

itemListSettingPersistenceService.getFiltersVisible(itemListKey, this.workspaceId).then(function(value){
    console.log("The filter visibility setting is currently set to " + value);
});

getItemListState(string itemListKey)

Gets the item list state.

Parameters

Return type

An Item List State object.

Syntax

var itemListSettingPersistenceService = {
     // ...
     getItemListState: function(itemListKey) {
          return convenienceApi.promiseFactory.resolve(false);
     },
     // ...
};

Example

var itemListState = itemListSettingPersistenceService.getItemListState(itemListKey);
/*
itemListState = {
     sorts:               Array<Sort>,
     filters:          Array<Filter>,
     data:               Array<Object>,
     startIndex:          Number,
     pageSize:          Number,
     columnWidths:     Number
}
*/

getItemListStateOrDefault(string itemListKey, string columnWidthsKey)

Gets item list state or a new instance of the state object.

Parameters

Return type

An Item List State object.

Syntax

var itemListSettingPersistenceService = {
     // ...
     getItemListStateOrDefault: function(itemListKey, columnWidthsKey) {
          return convenienceApi.promiseFactory.resolve(false);
     },
     // ...
};

Example

var itemListState = itemListSettingPersistenceService.getItemListStateOrDefault(itemListKey, columnWidthsKey);
/*
itemListState = {
     sorts:               Array<Sort>,
     filters:          Array<Filter>,
     data:               Array<Object>,
     startIndex:          Number,
     pageSize:          Number,
     columnWidths:     Number
 
}
*/

getItemListColumnWidths(string columnWidthsKey)

Persists item list column width.

Parameters

Return type

Map<String, Number> | Null - returns the column width.

Syntax

var itemListSettingPersistenceService = {
     // ...
     getItemListColumnWidths: function(columnWidthsKey) {
          return convenienceApi.promiseFactory.resolve(false);
     },
     // ...
};

Example

var columnWidths = itemListSettingPersistenceService.getItemListColumnWidths(columnWidthsKey);
if (!!columnWidths) {
     columnWidths.forEach(function(value, key) {
          console.log("key: " + key + ", value: " + value);
     });
}

setGridStyle(boolean gridStyleValue)

Persists grid style value for all item lists.

Parameters

Return type

None

Syntax

var itemListSettingPersistenceService = {
     // ...
     setGridStyle: function(gridStyleValue) {
          // write grid style value boolean to persistence
     },
     // ...
};

Example

itemListSettingPersistenceService.setGridStyle(true);

setFiltersVisible(itemListKey: String, filtersVisibleValue: Boolean)

Persists filter visibility for a specific item list.

Parameters

Return type

None

Syntax

var itemListSettingPersistenceService = {
     // ...
     setFiltersVisible: function(itemListKey, filtersVisibleValue) {
          // write filters visible value boolean to persistence based on itemListKey
     },
     // ...
};

Example

itemListSettingPersistenceService.setFiltersVisible(itemListKey, true);

setItemListState(string itemListKey, object itemListStateValue)

Persists item list state.

Parameters

Return type

None

Syntax

var itemListSettingPersistenceService = {
     // ...
     setItemListState: function(itemListKey, itemListStateValue) {
          // write item list state object to persistence based on itemListKey
     },
     // ...
};

Example

var itemListState = {
     filters:     Array<Filter>,
     pageSize:     Number,
     sorts:          Array<Sort>,
     startIndex:     Number
};
 
itemListSettingPersistenceService.setItemListState(itemListKey, itemListState);

setItemListColumnWidth(string itemListKey, string columnKey, number width)

Persists item list column width.

Parameters

Return type

None

Syntax

var itemListSettingPersistenceService = {
     // ...
     setItemListColumnWidth: function(itemListKey, columnKey, width) {
          // write item column width value to persistence based on itemListKey and columnKey
     },
     // ...
};

Example

itemListSettingPersistenceService.setItemListColumnWidth(itemListKey, columnKey, 10);

ItemListMetadata object

An object that tells Liquid how to render an item list. At minimum, a FieldCollection is required. The other properties are optional.

{
    "143245": 100,
    "143247": 40,
    "100004": 75
}

Item List State class

An object that contains the current state of the item list including sort, filter, and pager information.

Syntax

var itemListState = {
     startIndex: 1,
     pageSize: 1,
     filters: [{
          field: "Name",
          condition: {
               operator: "is less than",
               value: 10,
               displayValue: "is less than 10"
          },
          isAdvanced: false
     }],
     sorts: [{
          column: "Column Name",
          direction: "asc"
     }],
     data: [
          {
               "Name": "test1 name",
               "ArtifactID": 1
          },
          {
               "Name": "test2 name",
               "ArtifactID": 2
          }
     ],
     columnWidths: new Map(
          ["one", 100],
          ["two", 200]
     )
};

Properties

Methods

None

Item List Types enumeration

Defines types of item list columns.

Enums

Date Formats

DateTime items support multiple formats in forms. One letter values correspond to different date formats.

Relativity object

Represents the structure of a Relativity Choice or Object.

Properties

ReadData object

Represent the field-value data used to populate the form.

Properties

{
    1234567: "Some value", // field ID referencing a fixed length field
    8901234: [1, 2, 3], // field ID referencing a multiple choice field
    5678901: 10 // field ID referencing a whole number field
}

{
    2345678: { // some single object field
        "ArtifactID": 0,
        "Guids": [],
        "ItemSecured": true
    },
    9012345: [ // some multi object field
        {
            // the name of this object will appear
            "ArtifactID": 6789012,
            "Guids": [],
            "Name": "An unsecured item",
            "ItemSecured": false
        },
        {
            "ArtifactID": 0,
            "Guids": [],
            "ItemSecured": true
        },
        {
            "ArtifactID": 0,
            "Guids": [],
            "ItemSecured": true
        }
    ]
}

ExitDialog class

Represents the window alert dialog that is displayed when navigating away from and edit/add form that contains unsaved changes.

Methods

See the following subsections for information about these methods:

• activate(string message)
• trigger(string message)

activate(message: String)

Sets an ExitDialog with a message that will be displayed when the user navigates from edit/add form page with unsaved data on it. This uses the activate Aurelia hook.

Parameters

Return type

Void

Example

(function(eventNames, convenienceApi) {
    var eventHandlers = {};
 
    eventHandlers[eventNames.PAGE_LOAD_COMPLETE] = function() { 
       this.exitDialog.activate("Unsaved Data!!! Continue?");
    };
 
    return eventHandlers;
}(eventNames, convenienceApi));

trigger(message: String)

Displays the browser's confirmation dialog on the page and returns whether or not the user clicked the confirmation button in the dialog. The execution of JavaScript is stopped until the user confirms or cancels the dialog.

Parameters

Return type

Boolean

Example

(function(eventNames, convenienceApi) {
    var eventHandlers = {};
 
    eventHandlers[eventNames.PAGE_LOAD_COMPLETE] = function() {
       var continue = this.exitDialog.trigger("Error Occurred. Do you wish to continue??");
       if(continue)
       {
          // Do something to try to resolve error.
          console.log("Error Resolved");
       }
    };
 
    return eventHandlers;
}(eventNames, convenienceApi));

RuntimeConfig class

Represents specific Relativity configurations that are used for communication between the forms application and Relativity. These properties are read-only.

Properties