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.
Conceptually, a forms page can be thought to have four main workflows:
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 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 Relativity Forms, long text field line endings are saved in a different format than Classic Forms. In Classic Forms, long text line endings get saved in the Windows format. In Relativity Forms, on the other hand, long text line endings
are saved in whichever format is defined by the browser and operating system of the user.
Note: We do not recommend using the long text field as a means of saving a delimited value field. What is saved and rendered could change depending on how and where the field is saved.
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.
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:
Object type event handler(s) | Brief description |
---|---|
The existence of a Console event handler associated to an object type will not prevent the type from using Relativity Forms, but Relativity Forms ignores them. To achieve Console behavior in Relativity Forms, implement a handler for the load pipeline's createConsole event. | |
(This does not apply to Classic Forms pages or Relativity Forms pages) | |
The Object Manager API executes these handlers during its deletions, and by default, Relativity Forms uses Object Manager APIfor its deletions. So by default, Relativity Forms will respect the existence of these Event Handlers, with the following caveat:
| |
The Object Manager API executes these handlers during its reads, and by default, Relativity Forms uses Object Manager APIfor its object instance reads. So by default, Relativity Forms will respect the existence of these Event Handlers, with the following caveats:
| |
The Object Manager API executes these handlers during its saves, (before and after the object is saved, respectively) and by default, Relativity Forms uses Object Manager API for its saves. So by default, Relativity Forms will respect the existence of these Event Handlers. They fire on the server, after the submit pipeline finishes its validation (on submit). If a handler is implemented for the submit pipeline's replaceSave, and something other than the Object Manager API is used for the save, these object type event handlers will not be executed. |
Use these guidelines when developing page interaction event handlers to be used in Relativity Forms:
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.
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.
Note: You can also use a template to create this event handler type. For more information, see Visual Studio templates
The following code illustrates a sample Page Interaction event handler compatible with Relativity Forms.
using kCura.EventHandler; namespace EventHandlerExampleApplication { [System.Runtime.InteropServices.Guid("0cae30b4-a591-4029-acf7-ac85302ac83f")] [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 { get { return new string [] { "eventHandlerExampleResourceFile.js" }; } } public override string [] AdditionalHostedFileNames { get { 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));
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 = window.top.GetRelativityApplicationWebResourceFile(<applicationGuid>,'latest',<fileName>);
This call consists of the following parameters:
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:
Alter the event handler JavaScript file locally, and save it.
Open the Relativity instance that contains your application.
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 |