Migrating applications to Relativity Forms

Relativity Forms is our solution for rending all layouts in Relativity, which provides more controlled Relativity object customization through robust JavaScript APIs and granular front-end page lifecycles, on an evolving framework.

If you have customized user interfaces with Classic Forms, you will most likely need to update these customizations to use the new Relativity Forms approach.

Review the information in this topic to understand how your applications may be impacted. For an example of converting from Classic Forms to Relativity Forms, The Sample: Converting a Classic Form to a Relativity Form walkthrough demonstrates converting a Classic Form with event handlers to a Relativity Form.

Determining if your applications are affected

If your applications use any of the following, you will need to make changes to ensure your applications function as desired after enabling Relativity Forms: 

  • Console or PageInteraction event handlers
  • PreLoad event handlers to supply default values
  • HTML-enabled fields, custom text fields, or custom labels that modify content elsewhere on the page
  • HTML or JavaScript content as part of PreLoad, PreSave, or PostSave event handlers
  • Object type event handler return values where the Message property is more than just plain-text (such as script or markup)
  • Event handlers employing PostExecutionAction, RedirectToLayout, or other redirections

If your application does not use these, your application should be safe to enable with Relativity Forms without modification.

To enable or switch to Relativity Forms, use the Object Type Settings screen to set Use Relativity Forms to Yes, as shown below:

Conceptual Differences

The table below lists the main conceptual differences between Classic Forms and Relativity Forms.


Classic Forms

Relativity Forms



The 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.

Front-end (in the browser), with server-side work accomplished by services invoked by 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.

PageInteraction JavaScript Source String literal content or link generated in PopulateScriptBlocks function of a PageInteraction event handler JavaScript resource files in your Application, referenced by ScriptFileNames property of the object type’s PageInteraction event handler

Output of server-side Console event handler embedded into the page.

Sever-side work done within the same code which constructs the markup.

Server-side Console event handlers are ignored.

Consoles are created by PageInteraction JavaScript.

Server-side work done by services invoked by front-end script.


Primarily server-side.

Embedded JavaScript is run as the page renders in the browser, placing the burden to control timing on the developer, with no explicit JavaScript API support from Relativity.

Lifecycle tailoring is most significantly handled via server-side event handlers allowing augmentation of reads, saves, and deletions.

Primarily front-end, divided into four main page operations:

Each operation consists of multiple named events which the JavaScript may handle to specifically time code execution.

Server-side create, read, update and delete operations can be completely replaced.

Default behavior of Relativity Forms will fire the server-side event handlers related to these operations.

JavaScript API support Nothing explicit

Named events that you can handle, allowing timing of code execution.

Each script handler is provided with script APIs consisting of:

  • A this binding which contains methods and metadata specific to the currently active object and layout.
  • A robust convenienceApi object supplying functionality to perform operations like directly accessing and manipulating fields without DOM lookup, making http requests, populating the page's Console, and more

Server-side object type event handlers for CRUD (create, read, update, and delete)

  • PreLoad
  • PreSave
  • PostSave
  • PreMassDelete
  • PreCascadeDelete
  • PreDelete
PreLoad does execute for new objects. PreLoad does not execute for new objects; value defaulting for new objects must be done in JavaScript.


  • Long Text Fields: 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. 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.

Frequently-Asked Questions

  • What will happen if I do nothing?
    • If your applications are affected because they use functionality listed above and you do not make any changes, your customizations will fail when your applications are switched over to Relativity Forms. All applications in our ecosystem will be switched over to Relativity Forms, and Classic Forms will no longer be available by the end of Quarter 1, 2022
  • I currently handle specific lifecycle customizations in place using Classic Forms. I need to make sure they still work when I convert to Relativity Forms. What do I need to do?
  • I currently use the console event handler in my application that runs on Classic Forms. What do I need to do?

Additional Resources

DevHelp Community GitHub Release Notes NuGet

Share knowledge with the Relativity developer community.

Access tools and resources to build an application.

Review the most recent product release notes.

Create .NET Apps faster with NuGet.