Build your first custom page

This tutorial illustrates how to create a simple custom page available from an external tab in Relativity. It describes how to complete the following tasks:

  • Use the Relativity template for custom pages.
  • Write the source code for a custom page.
  • Package the custom page files.
  • Add the custom page to an application.
  • Create an external tab for displaying it in Relativity.

Your completed custom page displays your name and the current time in the Relativity UI.

This page contains the following information:

Before you begin

Complete the following tasks to before you begin implementing a custom page:

  • Obtain access to an instance of Relativity used for development purposes.
  • Set up your development environment and enable Developer mode in Relativity. This tutorial uses Visual Studio 2017 to illustrate development tasks. See Developer mode.
  • Install the Relativity templates in Visual Studio. This tutorial uses the custom page template. See Add templates through Visual Studio.

Build a custom page

Note: The following example is based on WebForms. You can also use MVC5, WebApi2, or other frameworks supported under IIS and .NET 4.6.2.

Use these steps to build a simple custom page:

  1. In Visual Studio, create a new project named MyFirstCP using the Relativity Custom Page Form template.

    (Click to expand)

    New Project dialog

  2. To open the NuGet Package Manager, click Tools > NuGet Package Manager > Manage NuGet Packages for Solution. Select and install the NuGet package for Relativity.CustomPages.
  3. Select the Relativity.CustomPages library that matches your environment version.

    (Click to expand)

    NuGet package version for custom page

  4. Open Default.aspx and press SHIFT + F7 to open the design window.
  5. Press CTRL + ALT + X to open the toolbox.
  6. Double click on Label to add a label to the layout.
  7. Right-click on Label > Properties. Set the following properties:
    • border style - select Double.
    • border color - select Blue
    • ID - update it to DisplayLabel.

    (Click to expand)

    Label properties

  8. Navigate to Default.aspx.cs and set the text for the DisplayLabel.

    This example uses the Visual Studio template for custom pages. It contains examples of information that you can return using the built-in Custom Pages Helper template. This tutorial doesn't use of all of them, so you can remove the unneeded ones.

    protected void Page_Load(object sender, EventArgs e)
            //Gets the user ID.
            int userArtifactId = Relativity.CustomPages.ConnectionHelper.Helper().GetAuthenticationManager().UserInfo.ArtifactID;
            //Gets the email address of the current user.
            string userEmailAddress = Relativity.CustomPages.ConnectionHelper.Helper().GetAuthenticationManager().UserInfo.EmailAddress;
            //Gets the first name of the current user.
            string firstName = Relativity.CustomPages.ConnectionHelper.Helper().GetAuthenticationManager().UserInfo.FirstName;
            //Gets the last name of the current user.
            string lastName = Relativity.CustomPages.ConnectionHelper.Helper().GetAuthenticationManager().UserInfo.LastName;
            //Gets the full name of the current user.
            string fullName = Relativity.CustomPages.ConnectionHelper.Helper().GetAuthenticationManager().UserInfo.FullName;
            //Gets the current user workspace artifact ID.
            int currentUserWorkspaceArtifactId = Relativity.CustomPages.ConnectionHelper.Helper().GetAuthenticationManager().UserInfo.WorkspaceUserArtifactID;
           string displayString = String.Format("User: {0}\r\nUser ID: {1}\r\nUser Email: {2}\r\n\r\n Hello {3}, the time is {4}.", fullName, userArtifactId, userEmailAddress, firstName, DateTime.Now.ToShortTimeString());
            DisplayLabel.Text = displayString;
        catch (Exception ex)
            //Your custom page caught an exception
            DisplayLabel.Text = ex.ToString();
  9. Right-click on your MyFirstCP web project and click Publish.

    (Click to expand)

    Pick a publish target

  10. Click New, select Folder, and click Next to locate the file where you want to publish your custom page.

    Note: Don't overwrite any of your project files when specifying the target location. If publishing to the project directory, select a subdirectory.

  11. (Click to expand)

    Folder option

  12. Click Finish.

    (Click to expand)

    Publish options

  13. Expand Delete existing files. Verify that the Delete all existing files prior to publish option is selected. Click Save.

    (Click to expand)

    File Publish Options section

  14. Click Publish.
  15. Navigate to the directory where you published your web application.
  16. Add the contents of the parent directory to a .zip file. (Don't add the parent directory to this file.)

    Note: Save the files as a .zip file because other archive file types won't work properly.

    (Click to expand)

    Custom page archive

    Note: If you used a blank web project to build this custom page, verify whether the bin directory has a folder called roslyn. If it contains this folder, follow the instructions provided in Can't upload custom pages published through Visual Studio 2015 and higher.

Deploy a custom page

To deploy a custom page:

  1. Open the Relativity instance used for development.
  2. Create a new workspace called Basic Samples. You can also use an existing workspace to deploy your custom page.
  3. Open the Relativity Applications tab in the workspace.
  4. Click New Relativity Application.
  5. In Application Type field, click Create new Application.
  6. In New Application Name field, enter Basic Samples Application.

    (Click to expand)

    New application layout

  7. Click Save to display the detail view of the application, and then click Push to Library in the console on the application details view.

    (Click to expand)

    Push to Library button on Relativity Application console

  8. Locate the Custom Page tab.
  9. On the Custom page tab, click New Custom Page.
  10. In the Application field, click ellipsis button to select the application that you created.
  11. Enter Basic Samples Custom Page in the Name field.
  12. In the File field, click Choose File to upload your compressed archive created in step 15.

    (Click to expand)

    Custom page layout

  13. Click Save to display the detail view of your custom page. Copy the URL in the Custom Page Link field.

    This field lists a base URL for the custom page. You can use this URL to link your page to a tab In Relativity.

    (Click to expand)

    Custom page details view

  14. Navigate to the Relativity Applications tab in your workspace.
  15. Locate the Basic Samples Application in the list and click on it to display the detail view.
  16. Click and confirm Unlock Application in the console on the application details view.
  17. In the Tab section of the application details view, click New to display a form for adding a tab.

    (Click to expand)

    Tabs layout

  18. In the Name field, enter My Custom Page.
  19. Select External as the Link Type.
  20. In the Link field, paste the base URL for your custom page generated in step 13. Append Default.aspx to it. Your link uses the following format, which includes the GUID for your application:

    See the following link for this example:

  21. In the Order field, enter 1.
  22. Click Save and Back. Your new tab is displayed in the list page.
  23. (Click to expand)

    Tab section

  24. To add your application to the Application Library, click Push to Library in the console on the application details view.

    Note: After you push the application to the library, the Custom Page Deployment Manager agents detect the new item and deploy the pages to the web server.

  25. Click the My Custom Page tab to view your custom page. You may need to wait several minutes for the agents to deploy the pages so that your custom page is visible.

    (Click to expand)

    Sample custom page