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.
  • 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)
    {
        try
        {
            //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.

    (Click to expand)

    Folder option

  11. Click Finish.

    (Click to expand)

    Publish options

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

    (Click to expand)

    Publish options

  13. Click Publish.
  14. Navigate to the directory where you published your web application.
  15. 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. Select the Workspace Admin tab and click Relativity Applications.
    4. Click the New Relativity Application.
    5. In Application Type field, click Create new Application.
    6. In New Application Name field, enter Basic Samples Application.
    7. (Click to expand)

      New application layout

    8. Click Save to display the detail view of the application, and then click Push to Library in the console on the application details view.
    9. (Click to expand)

      Push to Library button

    10. Search for the Custom Page tab at the instance level.
    11. On the Custom page tab, click New Custom Page.
    12. In the Application field, click ellipsis button to select the application that you created.
    13. Enter Basic Samples Custom Page in the Name field.
    14. In the File field, click Choose File to upload your compressed archive created in step 15.
    15. (Click to expand)

    16. 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.
    17. (Click to expand)

      Custom Page Link field

    18. Navigate to your workspace.
    19. Search for the Relativity Applications tab at the workspace level.
    20. Locate the Basic Samples Application in the list and click on it to display the detail view.
    21. Click and confirm Unlock Application in the console on the application details view.
    22. In the Tab section of the application details view, click New to display a form for adding a tab.

      (Click to expand)

      Tab Information dialog

    23. In the Name field, enter My Custom Page.
    24. Select External as the Link Type.
    25. 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:
      %applicationPath%/CustomPages/<YourRelativityApplicationGUID>/<FileName>

      See the following link for this example:

      %applicationPath%/CustomPages/<YourRelativityApplicationGUID>/Default.aspx
    26. In the Order field, enter 1.
    27. Click Save and Back. Your new tab is displayed in the list page.
    28. (Click to expand)

      Tab section

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

    30. Click Menu icon in the Sidebar to display the All Tabs Menu with the new My Custom Page tab.
    31. 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.

      Sample custom page