Load pipeline

In the Relativity Forms API, the Load pipeline represents what happens during page loads. This includes full loads and partial reloads caused by layout or object switches. The Load pipeline offers the ability to customize and extend its behaviors by implementing any of the pipeline's event handlers within the JavaScript for your Relativity Forms Page Interaction event handler. For example, overriding the replaceGetNewObjectInstance event handler would allow the definition of default values for new object instances to display within a form.

This page contains the following information:

Load pipeline workflow

The Load pipeline represents how forms are rendered in the Relativity UI. The following diagram illustrates when specific event handlers are executed in this workflow.

Key for the diagram

• Async returns any time after hydrateLayout is fired and before pageLoadComplete is fired.
• For existing objects, replaceRead fires if registered. Otherwise, the object is read from the startup data.
• For new objects, replaceGetNewObjectInstance fires if registered. Otherwise, the object is read from the startup data.
• replaceObtainAdditionalData fires if registered. Otherwise, the Object Manager service obtains additional data for the relevant fields.
• Partial Loads occur when the Load Pipeline is executed due to switching layouts or navigating another object of the same type as what is currently being viewed, in the same form mode as the present form.

Summary of Load pipeline event handlers

The following table lists each of the event handlers used in the Load pipeline.

Ambient variables

eventHandlersRegistered

Any registered eventHandlersRegistered event handlers execute before the selected form view-model is populated with the object instance data. It signifies the completion of registering ALL event handlers associated with the object, not just those pertaining to the load pipeline.

Syntax

(function(eventNames, convenienceApi) {
    var eventHandlers = {};
 
    eventHandlers[eventNames.EVENT_HANDLERS_REGISTERED] = function() {
        console.log("Inside EVENT_HANDLERS_REGISTERED event handler");
    };
 
    return eventHandlers;
}(eventNames, convenienceApi));

Parameters

function()

replaceRead

The replaceRead event handler executes when the object instance data is ready to be retrieved for an existing object and a replaceRead event handler is registered for the object type. It retrieves the object instance data containing the form values to display.

Note: This event handler is used only with existing objects when you are loading a form with a view or edit operation.

As it executes, the event handler performs the following operations:

• Makes the requests to the source providing the object instance data.
• Transforms the object instance data into the following entities:
• The form expected by the application
• The form compatible with the service that saves changes to the object instance. This service may be the replaceSave handler if defined, or the object instance service used by the application.

• Returns a promise that resolves to the transformed object data on a successful retrieval and rejects it on an unsuccessful retrieval.

Review the following guidelines for the replaceRead event handler and the related event:

• Only register a replaceRead event handler if the stock application object instance data retrieval isn't capable of retrieving the data to display in the form.
• A registered replaceRead event handler is invoked in place of the stock application object instance data retrieval.
• Register only one handler function for this event. If you register multiple functions, only the first function is invoked, and any others are ignored.

Syntax

(function(eventNames, convenienceApi) {
    var eventHandlers = {};
 
    eventHandlers[eventNames.REPLACE_READ] = function(
        workspaceId,
        artifactId,
        formViewModelTypeId
    ) {
        var data = {};
        return convenienceApi.promiseFactory.resolve({ modelData: data });
    };
 
    return eventHandlers;
}(eventNames, convenienceApi));

Parameters

Returns

Syntax

(function(eventNames, convenienceApi) {
    var eventHandlers = {};
  
    eventHandlers[eventNames.REPLACE_READ] = function(
        workspaceId,
        artifactId,
        formViewModelTypeId
    ) {
        var isViewMode = convenienceApi.constants.FORM_VIEW_MODEL_TYPE.VIEW === formViewModelTypeId;
        var readDataPromise;
  
        function someApiCall(workspaceId, artifactId) {
            return convenienceApi.promiseFactory.resolve({
                fieldIdForSomeTextField: "A value from an API call for " + artifactId
            });
        }
  
        if (isViewMode) {
            // Will receive object data from the someApiCall source
            readDataPromise = someApiCall(workspaceId, artifactId).then(function(objectData) {
                return { modelData: objectData };
            });
        } else {
            // In this example the edit form will always be populated with the following values for the fields.
            // This is just to demonstrate that the only requirement of a custom replace read event handler is that it must return a promise with a readData object
            var data = {
                fieldId1: "1",
                fieldId2: 2,
                fieldId3: true
            };
            readDataPromise = convenienceApi.promiseFactory.resolve({ modelData: data });
        }
        return readDataPromise;
    };
  
    return eventHandlers;
}(eventNames, convenienceApi));

replaceGetNewObjectInstance

The replaceGetNewObjectInstance event handler creates a new object instance data containing predefined form values to display.

Note: This event handler is used with new objects when you are loading a form via an add operation.

As it executes, the event handler performs the following operations:

• Makes the requests to the source providing the object instance data.
• Transforms the object instance data into the following entities:
  • The form expected by the application
  • The form compatible with the service that saves changes to the object instance. This service may be the replaceSave handler if defined, or the object instance service used by the application.

• Returns a promise that resolves to the transformed new object data ready for the create form object on a successful retrieval and rejects it on an unsuccessful transformation.

Review the following guidelines for the replaceGetNewObjectInstance event handler and the related event:

• Only register a replaceGetNewObjectInstance event handler if the create form initial object data should be filled with specific values.
• A registered replaceGetNewObjectInstance event handler is invoked in place of the stock application object instance data retrieval for the create form object.
• Register only one handler function for this event. If you register multiple functions, only the first function is invoked, and any others are ignored.

Syntax

(function(eventNames, convenienceApi) {
     var eventHandlers = {};
    
     eventHandlers[eventNames.REPLACE_GET_NEW_OBJECT_INSTANCE] = function() {
          console.log("Inside REPLACE_GET_NEW_OBJECT_INSTANCE event handler");
          var newObjectData = {};
          return newObjectData;
     };
    
     return eventHandlers;
}(eventNames, convenienceApi));

Parameters

function()

transformLayout

The transformLayout event handler executes before the layout is hydrated. It provides an opportunity to modify the form layout before it is initialized.

If a field is removed from the layout, the application does not know about the field. The field will not be rendered, and the application will not provide any value for that field on form submission.

Syntax

(function(eventNames, convenienceApi) {
    var eventHandlers = {};
 
    eventHandlers[eventNames.TRANSFORM_LAYOUT] = function(layoutData) {
        console.log("Inside TRANSFORM_LAYOUT event handler");
        console.log(JSON.stringify(layoutData));
    };
 
    return eventHandlers;
}(eventNames, convenienceApi));

Parameters

function(layoutData)

The following table lists the input parameters:

hydrateLayout

The hydrateLayout event handler executes after the object instance data has been retrieved and the layout data has been transformed, but before the application renders the form.

Syntax

(function(eventNames, convenienceApi) {
    var eventHandlers = {};
 
    eventHandlers[eventNames.HYDRATE_LAYOUT] = function(layoutData, objectInstanceData) {
        console.log("Inside HYDRATE_LAYOUT event handler");
        console.log(JSON.stringify(layoutData));
        console.log(JSON.stringify(objectInstanceData));
    };
 
    return eventHandlers;
}(eventNames, convenienceApi));

Parameters

function(layoutData, objectInstanceData)

The following table lists the input parameters:

hydrateLayoutComplete

The hydrateLayoutComplete event handler executes immediately after the application has rendered the form.

Syntax

(function(eventNames, convenienceApi) {
    var eventHandlers = {};
     
    eventHandlers[eventNames.HYDRATE_LAYOUT_COMPLETE] = function() {
        console.log("Inside HYDRATE_LAYOUT_COMPLETE event handler");
    };
 
    return eventHandlers;
}(eventNames, convenienceApi));

Parameters

function()

overridePickerDataSource

The overridePickerDataSource event handler provides the opportunity to override the data source for pop-up pickers for fields.

Syntax

eventHandlers[eventName.OVERRIDE_PICKER_DATASOURCE] = function(potentialPickerFields) {
    for (var i = 0; i < potentialPickerFields.length; i++) {
        potentialPickerFields[i].pickerDataSource = {
            customGetDataFunction: function() {
                return convenienceApi.promiseFactory.resolve({
                    TotalCount: 0,
                    Results: []
                });
            }
        }
    }
}

Parameters

function(potentialPickerFields)

The PickerDataSource object

eventHandlers[eventName.OVERRIDE_PICKER_DATASOURCE] = function(potentialPickerFields) {
    for (var i = 0; i < potentialPickerFields.length; i++) {
        potentialPickerFields[i].pickerDataSource = {
            customGetDataFunction: function(defaultGetDataFunction, request) {
                this.getColumns()
                    // This assumes transformColumnsToFieldNames is defined somewhere else
                    .then(transformColumnsToFieldNames)
                    .then(function(fieldNames) {
                        // This assumes that callSomeOtherApi is defined somewhere else
                        return callSomeOtherApi(request, fieldNames);
                    });
            }
        }
    }
}

Examples

Overriding the entire Data Provider

eventHandlers[eventName.OVERRIDE_PICKER_DATASOURCE] = function(fields) {
    for (var i = 0; i < fields.length; i++) {
        const field = fields[i];
        const MY_FIELD_ID = <field identifier of the field with the picker>;
        const ARTIFACT_TYPE_ID = <artifact type id of object type in the picker>;
        const VEIW_TO_DISPLAY = <artifact id of the view>;
        switch (field.FieldID) {
            case MY_FIELD_ID:
                const dataProviderOptions = {
                    fieldArtifactId: field.FieldID,
                    fieldName: field.DisplayName,
                    objectTypeId: ARTIFACT_TYPE_ID,
                    textIdentifierColumnName: "Name",
                    viewArtifactId: VEIW_TO_DISPLAY,
                    workspaceId: this.workspaceId
                };
                const dataProvider = convenienceApi.itemListDataProviderFactory.create("object", dataProviderOptions);
  
                field.pickerDataSource = {
                    customItemListDataProvider: dataProvider
                };
                break;
            default:
                break;
        }
    }
}

Customizing the stock Data Provider

Overriding the get data function

eventHandlers[eventName.OVERRIDE_PICKER_DATASOURCE] = function(fields) {
    for (var i = 0; i < fields.length; i++) {
        const field = fields[i];
const MY_FIELD_ID = <field identifier of the field with the picker>;
        switch (field.FieldID) {
            case MY_FIELD_ID:
                field.pickerDataSource = field.pickerDataSource || {}; // Preserve, possibly existing pickerDataSource object from the layout JSON.
                field.pickerDataSource.customGetDataFunction = loadMyFieldData;
                break;
            default:
                break;
        }
    }
}
function loadMyFieldData(defaultQuery, request, columns) {
    // ...
}

Overriding the getItemListMetadata function

eventHandlers[eventName.OVERRIDE_PICKER_DATASOURCE] = function(fields) {
    for (var i = 0; i < fields.length; i++) {
        const field = fields[i];
        const MY_FIELD_ID = <field identifier of the field with the picker>;
        switch (field.FieldID) {
            case MY_FIELD_ID:
                field.pickerDataSource = field.pickerDataSource || {};
                field.pickerDataSource.customGetItemListMetadataFunction = getItemListMetadataForMyField;
                break;
            default:
                break;
        }
    }
}
  
function getItemListMetadataForMyField(workspaceId, objectTypeId, viewArtifactId) {
    return makeApiCall() // This assumes makeApiCall() is defined somewhere else, and returns data in the correct form
        .then(function(dataFromApi) {
            // Make sure the data returned is in the proper format
            return {
                FieldCollection: dataFromApi.someProperty
                ViewFieldWidthCollection: dataFromApi.someOtherProperty,
                ActiveView: dataFromApi.anotherProperty
            }
        });
}

Specifying custom ItemListMetadata

eventHandlers[eventName.OVERRIDE_PICKER_DATASOURCE] = function(fields) {
    for (var i = 0; i < fields.length;i++) {
        const field = fields[i];
        const MY_FIELD_ID = <field identifier of the field with the picker>;
        switch (field.FieldID) {
            case MY_FIELD_ID :
                field.pickerDataSource = field.pickerDataSource || {};
                field.pickerDataSource.FieldCollection = [ /* ... */ ];
                field.pickerDataSource.ViewFieldWidthCollection = { /* ... */ };
                field.pickerDataSource.View = { /* ... */ };
                break;
            default:
                break;
        }
    }
}

replaceFileActions

Note: If a custom uploadFile method is defined for any field in a layout, a custom replaceSave method must also be defined. This replaceSave method should handle the persistence of the file field's data. If the built-in Relativity Forms save operation is called with the data from a file field with an overridden uploadFile handler, it will fail.

The replaceFileActions event handler allows alterations of the upload and download behaviors for File Fields via additional Field properties.  This event executes between transformLayout (TRANSFORM_LAYOUT) and overridePickerDataSource (OVERRIDE_PICKER_DATASOURCE).

Note: This event handler should set up and assign both an uploadFile function to override file upload behavior and a downloadFile function to override file download behavior.

Syntax

(function(eventNames, convenienceApi) {
    var eventHandlers = {};
 
    eventHandlers[eventNames.REPLACE_FILE_ACTIONS] = function(fileFields) {
        var fileField = !!fileFields && !!fileFields.length && fileFields[0];
        if (!!fileField) {
            fileField.uploadFile = myReplacementUploadHandler;
            fileField.downloadFile = myReplacementDownloadHandler;
        }
    };
 
    return eventHandlers;
}(eventNames, convenienceApi));

Parameters

function(fileFields)

The following table lists the input parameters:

For each File Field, two properties may be added - uploadFile and downloadFile.

function(workspaceId, artifactId, fieldId, file, backendProgressCallback, frontendProgressCallback, cancellationToken)

function onProgressUpdate(progressInfo) {
	backendProgressCallback({
		Message: {
			CompletedSteps: progressInfo.percentComplete,
			TotalSteps: 100
		}
	});
}
yourApi.uploadFile(file, ..., onProgressUpdate, ...);

var request = new XMLHttpRequest();
var method = 'POST';
var url = 'https://some.url/and/some/route/';
var async = true;
request.open(method, url, async);
request.onprogress = function (event) {
	frontendProgressCallback(event);
};
request.send(file);

var requestOptions = {
	onBrowserUploadProgress = function(percentComplete) {
		frontEndProgressCallback({
			loaded: percentComplete,
			total: 100
		});
	} 
};
yourApi.uploadFile(file, ..., requestOptions, ...);

startUpload();
cancellationToken._promise.catch(function() {
	cancelUpload();
});

const FILE_FIELD_ID = 1234 // Replace with the ID of your file field


eventHandlers[eventNames.REPLACE_FILE_ACTIONS] = function(fileFields) {
	fileFields[0].uploadFile = function (workspaceId, artifactId, fieldId, file, backendProgressCallback, frontendProgressCallback, cancellationToken) {
		return convenienceApi.promiseFactory.resolve({Filename: "SomeFileName.some.extension"});
	};
};


// Don't forget to override replace save as the default Relativity Forms save operation will fail if you've defined a custom uploadFile handler
eventHandlers[eventNames.REPLACE_SAVE] = function(objectInstanceData, objectVersionToken) {
	var fileFieldValue = objectInstanceData[FILE_FIELD_ID];
	var transformedData = transformData(objectInstanceData);
	transformedData[FILE_FIELD_ID] = {
		name: fileFieldValue.fileName,
		id: fileFieldValue.fileId,
		guid: fileFieldValue.uploadedFileGuid
	};
	yourApi.saveObject(transformedData);
}

function(workspaceId, artifactId, fieldId, fileName)

eventHandlers[eventNames.REPLACE_FILE_ACTIONS] = function(fileFields) {
    fileFields[0].downloadFile = function(workspaceId, artifactId, fieldId, fileName) {
        return convenienceApi.promiseFactory.resolve(new File(["SomeFileContents"], fileName));
    };
};

replaceObtainAdditionalData

Replaces the call to grab extra data for a set of fields. executes from the application's hydration logic (after hydrateLayout but finishes asynchronously from the rest of the pipeline and before pageLoadComplete) for fields that require options or item details to be shown beyond the values in the instance data.

The following can be overridden by this event handler

Fields

• Single Choice
• Multiple Choice
• Single Object
• User

Field Display Types

• Drop-downs
• Lists

The pageLoadComplete event handler only executes after ALL additional data retrievals (including the ones from the replaceObtainAdditionalData event handlers) have completed (and the rest of the pipeline has finished).

Example

This example demonstrates the use of convenienceApi.additionalData.getDefaultFactoriesForAdditionalData to override the additional data for just one field.

(function(eventNames, convenienceApi) {
    var eventHandlers = {};
 
    eventHandlers[eventNames.REPLACE_OBTAIN_ADDITIONAL_DATA] = function(
        fieldsRequiringAdditionalData,
        workspaceId,
        viewModelName
    ) {
        // Get all the default additional data factories
        // If we return this value without modifying it, the default behavior will be maintained.
        var additionalDataFactories = convenienceApi.additionalData.getDefaultFactoriesForAdditionalData(workspaceId, fieldsRequiringAdditionalData);
 
        // Override just the factory for the field we're interested in
        // Let's just pretend it's the first factory in the array to make things simpler
        var someFactoryIWantToOverride = additionalDataFactories[0];
        someFactoryIWantToOverride.createAdditionalDataPromise = function() {
            return someApi.getAdditionalData(
                workspaceId,
                someFactoryIWantToOverride.field,
                viewModelName
            );
        };
         
        return additionalDataFactories;
    };
 
    return eventHandlers;
}(eventNames, convenienceApi));

Parameters

function(fieldsRequiringAdditionalData, workspaceId, viewModelName)

The following table lists the input parameters:

Output

Sample Output

[
    {
        field: fieldsRequiringAdditionalData[0],
        createAdditionalDataPromise: function () {
            // Get additional data for field 0
            convenienceApi.promiseFactory.resolve({
                options: [
                    {
                        label: "Option 1",
                        value: 1001234,
                        order: 10
                    },
                    {
                        label: "Option 2",
                        value: 1004567,
                        order: 0
                    },
                    ...
                ],
                limitForUIExceeded: false      
            });
        }
    },
    {
        field: fieldsRequiringAdditionalData[1]
        createAdditionalDataPromise: getAdditionalDataForField1
    },
    ...
]

Expected output format:

postObtainAdditionalData

A registered postObtainAdditionalData event handler executes:

• when it is defined.
• after ALL additional data retrievals (including the ones from the replaceObtainAdditionalData event handlers) have completed (pageLoadComplete will not happen until this condition is met).
• before the pageLoadComplete event handler executes.

Syntax

(function(eventNames, convenienceApi) {
    var eventHandlers = {};
 
    eventHandlers[eventNames.POST_OBTAIN_ADDITIONAL_DATA] = function() {
        console.log("Inside POST_OBTAIN_ADDITIONAL_DATA event handler");
    };
 
    return eventHandlers;
}(eventNames, convenienceApi));

Parameters

function()

createActionBar

A registered createActionBar event handler executes after the form is rendered. It creates an action bar.

If you do not use convenienceApi.actionBar.createDefaultActionBar() to create the default action bar in this event handler, you must also specify an updateActionBar event handler, or updateActionBar will assume the default action bar exists, causing undefined behavior.

Example

(function(eventNames, convenienceApi) {
    var eventHandlers = {};
 
 
    eventHandlers[eventNames.CREATE_ACTION_BAR] = function() {
        console.log("Inside CREATE_ACTION_BAR event handler");
        convenienceApi.actionBar.createDefaultActionBar(); // create default action bar
 
 
        var button = document.createElement("button");
        button.id = "testButton";
        button.textContent = "Test Button";
        return convenienceApi.actionBar.containersPromise.then(function(containers) {
            containers.rootElement.appendChild(button); // add an extra button to the action bar
        });
    };
 
 
    return eventHandlers;
}(eventNames, convenienceApi));

Parameters

function()

Returns

updateActionBar

An updateActionBar event handler updates the action bar element on a page in response to a modified layout or instance. Any registered event handlers execute during object and layout switch.

Syntax

(function(eventNames, convenienceApi) {
    var eventHandlers = {};
 
 
    eventHandlers[eventNames.UPDATE_ACTION_BAR] = function() {
        console.log("Inside UPDATE_ACTION_BAR event handler");
 
 
        var button = document.getElementById("testButton"); // update the text of the extra button added in CREATE_ACTION_BAR
        button.textContent = "Updated Button";
    };
 
 
    return eventHandlers;
}(eventNames, convenienceApi));

Parameters

function()

Returns

CreateConsole

The createConsole event handler creates the console panel in the View form. As it executes, the event handler performs the following operations for View mode layouts only:

• Adds controls to console.
• Sets up the handler function invoked when the user interacts with a control.

Note: The Console object is available on the Relativity Event Handler API. For more information, see Event Handlers API on the Relativity API Reference page.

Syntax

(function(eventNames, convenienceApi) {
    var eventHandlers = {};
 
 
    eventHandlers[eventNames.CREATE_CONSOLE] = function() {
        console.log( "Inside CREATE_CONSOLE event handler" );
 
 
        var button = document.createElement("button"); // add a button to the console
        button.id = "testConsoleButton";
        button.textContent = "Test Button";
        return convenienceApi.console.containersPromise.then(function(containers) {
            containers.rootElement.appendChild(button);
        });
    };
 
 
    return eventHandlers;
}(eventNames, convenienceApi));

Parameters

function()

Returns

updateConsole

An updateConsole event handler updates the console element on a page in response to a modified layout or instance. Any registered event handlers execute during object and layout switch. This event handler is used only for view mode layouts.

Example

(function(eventNames, convenienceApi) {
    var eventHandlers = {};
 
 
    eventHandlers[eventNames.UPDATE_CONSOLE] = function() {
        console.log( "Inside UPDATE_CONSOLE event handler" );
 
 
        var button = document.getElementById("testConsoleButton"); // update the text of the extra button added in CREATE_CONSOLE
        button.textContent = "Updated Button";
    };
 
 
    return eventHandlers;
}(eventNames, convenienceApi));

Parameters

function()

Returns

pageLoadComplete

A registered pageLoadComplete event handler executes only after all the other event handlers in the Load pipeline have executed and completed their execution. It will also wait until ALL additional data retrievals (including the ones from the replaceObtainAdditionalData event handlers) have completed before firing. It is the final event handler to execute in the Load pipeline.

Example

(function(eventNames, convenienceApi) {
    var eventHandlers = {};
 
    eventHandlers[eventNames.PAGE_LOAD_COMPLETE] = function() {
        console.log("Inside PAGE_LOAD_COMPLETE event handler");
    };
 
    return eventHandlers;
}(eventNames, convenienceApi));

Parameters

function()