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
• Build a custom page
• Deploy a custom page

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.
• Ensure that you have the Relativity SDK installed. See Install the Relativity SDK.
• 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 WebForms template.

   (Click to expand)

   

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)

   

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)

   

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 > New Profile.

   (Click to expand)

   

10. Select Folder in the sidebar, and click Browse 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 Create profile.

    (Click to expand)

    

12. Select the Configure... link.

    (Click to expand)

    

13. Click Next, and expand File Publish Options. Verify that the Ensure Delete all existing files prior to publish option is selected. Click Save.

    (Click to expand)

    

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)

    

    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 and then click the New Relativity Application button.
4. In Application Type field, click Create new Application.
5. In New Application Name field, enter Basic Samples Application.
6. Click Save to display the detail view of the application.

   (Click to expand)

   

7. In the Custom Page associative list, click New to display a form for adding an new instance of the custom page.

   

8. In the Name field, enter Basic Samples Custom Page.
9. In the File field, click Browse to upload your compressed archive created in step 12.
10. In the Relativity Applications field, click to select the application that you created.

    (Click to expand)

    

11. 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)

    

12. Click Back to return to the application details view.
13. In the Tab section of the application details view, click New to display a form for adding a tab.

    (Click to expand)

    

14. In the Name field, enter My Custom Page.
15. Select External as the Link Type.
16. In the Link field, paste the base URL for your custom page generated in step 11. 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

17. Click Save > Back.
18. 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.

    

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