Relativity Forms API

What is Relativity Forms?

We know that Forms pages (view, edit, and new Layout pages) are heavily customized by developers. For that reason, we make it a priority to keep customization use cases top-of-mind. Relativity Forms is a new Layout-rendering option, providing the developer with robust JavaScript APIs and a granular front-end page life cycle for easier, more controlled Relativity object customization.

High-level differences between Classic Forms and Relativity Forms

Conceptually, a forms page can be thought to have four main workflows:

Classic Forms pages

Classic Forms page load life cycle occurs mostly on the web server before it is delivered to the browser:

After this load, the page is delivered to the browser, and any embedded script is executed as the page renders in the client-side.

Classic Forms exposes only a limited amount of control over the load, the ability to populate/alter field values before the page is rendered, via Pre Load event handlers. Change Submit and Delete can be customized in some respects with the scripts embedded in the page by existing Page Interaction event handlers, but no API is provided for accessing or manipulating Fields, and no support is given to make it easy to time when scripts are fired.

Additional event handlers can be used to do work (on the server) before deletions, and before and after saves.

Relativity Forms

Relativity Forms moves the page load into the life cycle to the front-end. A nearly empty page is delivered to the browser, which makes an API call to get Layout information and a list of file names of JavaScript files, which define the handlers for the front-end's page life cycle. Upon receipt of the API's response, the page requests each of the script files and turns them into code which handles the page's life cycle events.

The page then completes its rendering, executing the handlers for the load life cycle which were defined in the scripts which the page downloaded moments beforehand.


In the context of Relativity Forms, these workflows are referred to as pipelines:

In Relativity Forms, each of these pipelines has a set of life cycle events for which you may register handlers by name within one or more JavaScript files. This granularity removes any need on your part to write code which decides when code executes, and does not require you to manually wire logic up to UI components to accomplish that timing.

To aid you, each handler which you implement is provided with:

These events, and the items provided to the event handlers allow for more stable and future-proof event handlers than Classic Forms. When the logic or markup used to render Relativity Forms changes, the APIs continue to work.

Implementing Relativity Forms event handlers

Page Interaction event handlers for object types using Relativity Forms require JavaScript resource files rather than code defined in the PopulateScriptBlocks() method as is used in Classic Forms. These JavaScript files contain the handlers for the client-side events which occur in each pipeline. You implement these client-side event handlers by creating JavaScript files with your custom code, and then specify the names of these files in the ScriptFileNames and AdditionalHostedFileNames properties added to the .NET PageInteractionEventHandler class. The JavaScript and any other supporting files are uploaded to Relativity separately from the DLL for the Page Interaction event handler. Additionally, in order to be rendered by Relativity Forms, the Use Relativity Forms Field on the object type must be set to Yes.

Special considerations for Relativity Forms event handlers:

Guidelines for page interaction event handlers to be used in Relativity Forms

Use these guidelines when developing page interaction event handlers to be used in Relativity Forms:

  1. Create event handler JavaScript files - implement one or more JavaScript files that contain the logic to be executed by a Relativity Forms page. In most cases, you may have only one file, but you can specify multiple files. For more information, see Code.

    Note: Create JavaScript files separately from the DLL that contains your Page Interaction event handler. You need to upload these files and the DLL as separate files, so the JavaScript files shouldn’t be part of your Visual Studio project.

  2. Optionally create additional files - you may optionally implement or define one or more additional files required for your Page Interaction event handler. For example, you might want to provide image, CSS, or supporting JavaScript files.

    Note: Create these files separately from the DLL that contains your Page Interaction event handler. As you will need to upload these files and the DLL as separately, the files shouldn’t be part of your Visual Studio project.

  3. Create a new class in Visual Studio.

    Note: You can also use a template to create this event handler type. For more information, see Visual Studio templates

  4. Add NuGet packages - ensure your Visual Studio project has installed the relevant NuGet packages, including at a minimum the Relativity.EventHandler and Relativity.Api packages. See Best practices for building applications.
  5. Add a GUID for the event handler - set the System.Runtime.InteropServices.Guid to the GUID identifying your event handler. Use the GUID generator in Visual Studio.
  6. Set the CustomAttributes.Description attribute - provide a description that you want to appear in the Relativity UI for the event handler.
  7. Inherit from the PageInteractionEventHandler class - extend the base class for this type of event handler.
  8. Override the PopulateScriptBlocks() method - Relativity Forms ignores the PopulateScriptBlocks() method, so if you are making a new event handler only to be used in Relativity Forms, return an empty Response. However, if you are converting an existing Page Interaction event handler for use in Relativity Forms, this can be left as-is so that your existing customizations can be used in Classic Forms while you convert to Relativity Forms.
  9. Override the ScriptFileNames property - return the names of the files containing the JavaScript logic that you want the Relativity Forms page to execute. These files are automatically interpreted and yield an object that contains one or more event handlers to register for the object type within the Relativity Forms API.
  10. Optionally, override the AdditionalHostedFileNames property - return the names of any additional files that your Page Interaction event handler needs. For example, it might require images or style sheets. These files are available for download and usage, but the Relativity Forms API doesn't attempt to obtain them or interpret them as event handler files.
  11. Upload your event handler assembly, script files, and additional files to Relativity - in the Relativity UI, use the Resource Files tab to upload your compiled .dll file for the event handler, and any files specified by the ScriptFileNames and AdditionalHostedFileNames properties. You need to upload these items as separate files, so they shouldn't be embedded in your .NET class. See Add event handlers to applications.
    As part of the upload process, you need to associate your custom files with an application that Relativity uses to host them. See Resource files on the Relativity Documentation site.
  12. Associate your event handler with an object type - in your workspace, associate the newly uploaded Page Interaction event handler with the with one or more object types. See Adding an event handler.
  13. Enable the use of Relativity Forms on the associated object types - ensure that Relativity Forms is enabled by setting the Use Relativity Forms Field on your object type to Yes.
  14. When you navigate to a forms page for a Relativity Forms - enabled object type associated with the event handler, it should automatically run the JavaScript contained in the files that you specified in the ScriptFileNames property.

Customizing Relativity Forms pages with the Relativity Forms API

The following code illustrates a sample Page Interaction event handler compatible with Relativity Forms.

using kCura.EventHandler;
 namespace EventHandlerExampleApplication
      [kCura.EventHandler.CustomAttributes.Description("Example Page Interaction event handler for Relativity Forms")]
      public class EventHandlerExample : kCura.EventHandler.PageInteractionEventHandler
          public override Response PopulateScriptBlocks()
              return new Response();
          public override string [] ScriptFileNames
                  return new string [] {  "eventHandlerExampleResourceFile.js" };
          public override string [] AdditionalHostedFileNames
                  return new string [] {  "example.png" ,  "styles.css" };

The following code illustrates a simple event handler script file "eventHandlerExampleResourceFile.js":

(function(eventNames, convenienceApi) {
     var eventHandlers = {};
     eventHandlers[eventNames.PAGE_LOAD_COMPLETE] = function () {
          console.log("Page load complete!");
     return eventHandlers
}(eventNames, convenienceApi));

Identifying the URL for a file

You can use the AdditionalHostedFileNames property to identify supplementary files for use by your event handler. The web server hosts any files that you specify in this property. To determine the appropriate URL for a file, make the following call from within your JavaScript:

var fileUrl =<applicationGuid>,'latest',<fileName>);

This call consists of the following parameters:

Updating custom event handler script files

After you implement your event handler's script files, you can modify a file without needing to update the associated Relativity Application. To do this, you will replace the existing file through the Resource Files tab. Within five seconds of uploading the files, they are available on all web servers in your environment. Use the following steps:

  1. Alter the event handler JavaScript file locally, and save it.

  2. Open the Relativity instance that contains your application.

  3. Navigate to the Resource Files tab and find the JS file you want to update. In this example, look for the eventHandlerExampleResourceFile.js associated with the application.
  4. Edit the entry and click Clear, in order to clear the exiting entry for the file.

  5. Click Choose File and select your updated JS file. The name of the script must remain the same, click Save.

Your changes should now be observable in the associated object type's Relativity Forms pages. If you do not see your changes taking effect, try clearing your browser cache and reloading the page. Some browsers (including Chrome) will allow you to disable the cache while your developer tools are open. This is recommended during development.

Once you have finished development of the script files, you can update the version number of your Relativity Application by pushing it to the library, in order to fix any lingering cache issues for users.

Community Updates

Aero Developer FAQ Evolving the Platform Most recent release notes
Learn more Learn more Learn more

Additional Resources

Access Third-Party Tools with GitHub     Create .NET Apps Faster with NuGet
Visit github     visit nuget