Lesson 6 - Create a custom page

Custom pages are used to tailor the look and feel of applications that you develop on the Relativity platform. You can develop your own cascading style sheets (CSS), JavaScript, HTML, and images for your custom pages.

In this lesson, you will learn how to complete these tasks:

  • Deploy a custom page in Relativity.
  • Add a custom page to an application in Relativity.
  • Implement a custom page containing client-side JavaScript. In this lesson, the JavaScript includes simple search functionality and the ability to create article categories.
  • Debug a custom page in the browser.
  • Use Kepler services via the REST API to search for article categories and create them in your instance of Relativity.
  • Create Relativity Dynamic Objects (RDOs) by making REST calls through JavaScript to the Object Manager service.
  • Create an RDO called Article Category using the Object Manager service.

Estimated completion time - 3 hours

Step 1 - Create a simple custom page

You start creating a simple custom page by adding HTML to an index.html file. As you work through this lesson, you continue building the page by adding JavaScript, CSS, and more HTML. Use the code editor of your choice for working with these technologies in your custom page. This lesson uses Visual Studio Code.

Use the following steps to create a simple custom page:

  1. Create a directory called HelloWikipedia.CustomPage.
    It is the root directory of your project.
  2. Track this directory using the source control tool of your choice, such as Git.
  3. Inside the root directory, create a subdirectory called src.
    As you build your custom page, add the source files for it to this directory.
  4. In the src directory, create a file called index.html, and add the following code to the file.
    Copy
    <!DOCTYPE html>
    <html>
     
    <head>
        <title>HelloWikipedia Categories</title>
    </head>
     
    <body>
        <div id="hw-container">Hello World!</div>
    </body>
     
    </html>
  5. Open the index.html file in a browser.
    Your page should look like the following screen shot. You can now deploy this simple custom page in Relativity.

    index.html file

Step 2 - Deploy a custom page in Relativity

This section illustrates how to deploy a custom page in Relativity and associate it with a tab. For more information, see Tabs on the Relativity Documentation site.

Use the following steps to deploy a custom page in Relativity:

  1. In the src directory, select the index.html file.
  2. Right-click on the file and select Send to > Compressed (zipped) folder.
  3. Set the name of the .zip file to HelloWikipedia.CustomPage.zip.

    Note: In this example, you only have a single file, which is index.html. For more complex pages, you may have additional files containing JavaScript or other code. Make sure that you select and include all these files and any directories in the .zip file.

    (Click to expand)

    Compressed (zipped) folder option

  4. Log in to your Relativity instance.
  5. Navigate to the Custom Pages tab.
    You can also search for custom pages using the Quick Nav. For more information, see Quick Nav on the Relativity Documentation site.
  6. Click New Custom Page.
    The Custom Page Information dialog appears.
  7. Click ellipsis button to select Hello Wikipedia, which you created in Lesson 2 - Build an application without any code.
    You are going to add your custom page to this application.
  8. Enter HelloWikipedia Categories in the Name field.
  9. In the File field, click Choose File to select the .zip file that you created in step 2.

    (Click to expand)

    Custom Page dialog

  10. Click Save.
  11. Verify that the Custom Page Link field now displays a path.

    Note: Record the value displayed in this field because you need to enter it when creating a tab for your custom page.

    (Click to expand)

    Custom page link

    Your Hello Wikipedia application is now updated with the new custom page. In the following steps, you push your updated application to the Application Library, so that it is available throughout your Relativity instance.

  12. Push the updated Hello Wikipedia application to the Application Library by completing the following steps:
    1. Locate the Hello Wikipedia application in the My First Workspace created in Lesson 2 - Build an application without any code.

      This workflow updates your application in the application library. Your application must be installed in a workspace. The Push to Library option performs the updates to the application in the library.

    2. Search on Relativity Applications in the workspace using the Quick Nav.
    3. Open the Hello Wikipedia application to display its details view.
    4. Click the Push to Library.

      (Click to expand)

      Push to Library button

  13. In the My First Workspace, navigate to the Tabs page.
  14. Click New Tab. The Tab Information dialog appears.
  15. Enter the following information:
    • Name - HelloWikipedia Categories
    • Tab Type - External
    • Link - enter the link displayed when you uploaded your custom page in step 9. Append /index.html to the end of the link so it points to your custom page. The GUID in the link will differ from than that in the following screen shots and code samples. See the following sample link:
      Copy
       %applicationPath%/CustomPages/e57fa0fe-59fd-49eb-92ed-895f3e592cd1/index.html
    • Order - 1000

      You can set this field to any value. It controls the order that the tab is displayed in the drop-down menu of the parent tab.

      (Click to expand)

      Tab Information dialog

  16. Navigate to the details view for the Hello Wikipedia application to complete these steps:
    1. Click Unlock Application in the Application console.
    2. Link the new tab you just created by finding Tabs section and clicking Link.
    3. Click Push to Library under Manage Application in the Application console.
  17. Navigate to the HelloWikipedia Categories tab.
    Your tab should appear like the one in the following screen shot.

    After you push the application to the Application Library, it may take several minutes for your page to reload. You may also need to clear your browse cache by performing a hard reload (CTRL + F5).

    (Click to expand)

    HelloWikipedia Categories tab

Step 3 - Add client-side JavaScript to a custom page

Use the following steps to add client-side JavaScript to a custom page:

  1. Create a subdirectory called scripts in the src directory.
  2. In the scripts directory, add the main.js file.
  3. Add the following code to the main.js file.
    This code adds text to the <div> tags on the page.
    Copy
    function startApplication() {
        console.info("HelloWikipedia Categories application started");
        const label = document.getElementById("hw-container");
        label.innerText = "Hello from JavaScript!";
    }
     
    startApplication();
  4. Add the <script> tag to the index.html file immediately before the closing </body> tag.
    This script executes the JavaScript with your page logic.
    Copy
    <script src="./scripts/main.js"></script>
  5. Complete the following steps to deploy your custom page:
    1. Add your custom page files to a .zip file as described in Step 2 - Deploy a custom page in Relativity.

      Note: Make sure that you add the src directory with the index.html file and scripts sub-directory.

    2. In Relativity, navigate to the details view of your custom page.
    3. Click Edit > Clear > Choose File to select the new version of the custom page that you created.
    4. Navigate to the Hello Wikipedia application in the My First Workspace.
    5. Open the details view of your application and click Push to Library.
      This step updates your application with the changes to your custom page.
  6. Navigate to the HelloWikipedia Categories tab for your custom page, and verify that the updated text populated by JavaScript appears on your page.

    After you push the application to the Application Library, it may take several minutes for your page to reload. You may also need to clear your browse cache by performing a hard reload (CTRL + F5).

    Deployed custom page

Step 4 - Debug your custom page

After confirming that your custom page is working properly in Relativity, you can begin debugging your JavaScript in the browser. This lesson uses Google Chrome, but you could use other tools for this purpose.

Use the following steps to debug JavaScript in the browser:

  1. Open your custom page through Relativity in Chrome.
  2. Press F12 to open the Chrome Developer Tools.
  3. In the Developer Tools, open the Source tab.
  4. Click main.js in the left pane.
    The source is displayed in the middle pane.
  5. Click on a line number to set a breakpoint.
    Chrome displays a red circle where you set the breakpoint.
  6. Press F5 to refresh the page.
    After refreshing, the JavaScript pauses its execution at the line with breakpoint.
  7. Control the debugging by using the debug execution control buttons at the top of the right pane.

    (Click to expand)

    Console tab for debugging

    Note: The Console tab in the bottom pane displays the message: HelloWikipedia Categories application started. The JavaScript for your page logged this message.

Step 5 - Implement functionality for your custom page

In this step, you add functionality to your custom page, which provides users with the ability to search for the categories in Wikipedia using an existing Kepler service. Users should also be able to add categories as RDOs through the Object Manager service. For more information, see Kepler framework and Object Manager Fundamentals.

Your completed custom page should look like the following screen shot after you update the code and deploy it in Relativity. This screen shot illustrates a search on the word science.

(Click to expand)

Search results in custom page

Use the following steps to add new functionality to your custom page:

  1. In your code editor, update the HTML in the index.html the following code.
  2. In the src directory, create a styles directory.
  3. In the styles directory, create a style.css file and add the following code to the file.
  4. Add logic to file for calling Kepler services by creating a services directory in the scripts directory.
  5. In the services directory, create an apiFetchClient.js file, and add the following code to this file.
  6. Add a service for category searches by creating the wikiCategorySearchService.js file in the services directory, and adding to this file.
  7. Add the services for adding categories by creating the categoryService.js and the globalObjectService.js files in the services directory, and adding the following code to these files.
  8. Implement the presentation layer for displaying results by creating the elementFactory.js file in the scripts directory and adding the following code to it.
  9. Facilitate the creation of a single search result element by creating a categoryResultElementFactory.js file in the scripts directory and adding the following code to this file.
  10. Create a list of multiple search result elements by create the searchResultsPresenter.js file in the scripts directory and adding the following code to this file.
  11. Execute a search and delegate the presentation results by creating the searchHandler.js file in the scripts directory and adding the following code to this file.
  12. Finalize the page functionality by update the main.js file in the scripts directory with the following code.
  13. Deploy a new version of your custom page by adding the index.html file, and the scripts and styles directories to a .zip file. See Step 2 - Deploy a custom page in Relativity.
  14. Verify that a search on the word science returns results like those in the following screen shot:

    (Click to expand)

    Search results in custom page

Step 6 - Add tests for your custom page logic

After deploying your updated custom page, you can begin writing tests for it. In this step, you use a JavaScript testing framework called Jasmine. Review the Getting Started page on the Jasmine website for more information.

Use the following steps to add tests to the project:

  1. Download and install Node.js from nodejs.org.
    This lesson uses version 14.8.0. This JavaScript runtime environment includes the node package manager called npm, which is used to install Jasmine.
  2. Navigate to the root directory of your project.
    This directory is one level above the src folder created in Step 3 - Add client-side JavaScript to a custom page.
  3. Run the following commands in PowerShell from your project root directory.
    These commands initialize npm and install Jasmine in the project:
    Copy
    // Run following command to initialize npm. This command creates package.json file in your project.
    npm init -y
     
    // Then run following command to install jasmine package. This command adds jasmine dependency to package.json.
    npm install jasmine --save-dev
     
    // Then run following command to initialize jasmine. This command adds jasmine configuration file.
    npx jasmine init
  4. Update the files created by running these commands by completing the following tasks:
    • Update the properties in the package.json file.
      Your version of Jasmine may differ from the one listed in this file.
      Copy
      {
          "name": "hellowikipedia-custompage",
          "version": "1.0.0",
          "description": "",
          "private": true,
          "scripts": {
              "test": "jasmine"
          },
          "keywords": [],
          "author": "",
          "license": "ISC",
          "devDependencies": {
              "jasmine": "^3.6.1"
          }
      }
    • Update your jasmine.json file located in the \spec\support\ directory as follows:
      Copy
      {
          "spec_dir": "src/tests",
          "spec_files": [
              "**/*[sS]pec.js"
          ],
          "helpers": [
              "helpers/**/*.js"
          ],
          "stopSpecOnExpectationFailure": false,
          "random": true
      }
  5. Create a tests subdirectory in the src directory to add a test to the project.
  6. Create the categoryService.spec.js file in the tests directory and add the following test code for the CategoryService class to this file.
  7. Create a subdirectory called fakes in the tests directory. In the following steps, you add mock classes to the fakes subdirectory.
  8. Create documentFake.js and htmlElementFake.js files in the fakes directory. These files help create the mock classes used in the categoryService.spec.js tests.
  9. Create a subdirectory called utils in the tests directory.
  10. Create the mockFactory.js file in the utils directory. This file helps generate the mock classes for the categoryService.spec.js tests.
  11. Run the following command to install the required Babel modules for using Jasmine with the import and export features of JavaScript ES6.
    Copy
    npm install  @babel/core @babel/register @babel/preset-env --save-dev

    For more information, see What is Babel? on the Babel website.

  12. Update your jasmine.json file located in the \spec\support\ directory with the following properties:
    Copy
    ...
    "helpers": [
        "../../node_modules/regenerator-runtime/runtime.js",
        "../../node_modules/@babel/register/lib/node.js",
        ...
      ],
    ...
  13. Create the babel.config.json file in the root directory of your project.
  14. Add the following property to the babel.config.json file:
    Copy
    {
        "presets": [
            "@babel/preset-env"
        ]
    }
  15. Use the following command to run the test:
    Copy
    npm run test

Step 7 - Make your custom page production ready

This step illustrates how to make your custom page ready for deployment in a production environment. Use these guidelines when publishing a custom page:

  • Bundle the code for the custom page into a single package file for use in the browser. In this step, you use module bundler called webpack. For more information, see Getting Started on the webpack website.
  • Verify that your custom page works on all supported browsers, such as Internet Explorer 11, and others.

Use the following steps to prepare the page for a production environment:

  1. Enter the following command to install the required webpack modules:
    Copy
    npm install webpack webpack-cli --save-dev
  2. Create the dist subdirectory in the root directory of your project.
  3. Move the index.html file from the src directory to the dist directory.
  4. Update the index.html file in the dist directory by replacing the <script> reference and removing the <link> to the style.css file.
  5. Verify that your index.html is updated as follows:
    Copy
    <!DOCTYPE html>
    <html>
     
    <head>
        <title>HelloWikipedia Categories</title>
    </head>
     
    <body>
     
        <div id="hw-container">
            <div id="hw-search-container">
                <span id="hw-search-label">Search Wikipedia for article categories</span>
     
                <div id="hw-search">
                    <input id="hw-search-input" placeholder="Search for category" />
                    <button id="hw-category-search-button" class="hw-button" type="button">Search</button>
                </div>
            </div>
     
            <div id="hw-results-container"></div>
        </div>
     
        <script src="bundle.js"></script>
     
    </body>
     
    </html>
  6. Enter the following command to install modules for CSS bundling:
    Copy
    npm install style-loader css-loader --save-dev
  7. Add the following import statement to the end of the import section in the main.js file located in the ../src/scripts directory:
    Copy
    ...
    import '../styles/style.css';
  8. Create a webpack.config.js file in the root directory of your project.
  9. Add the following properties to configure the webpack.config.js file.
    Copy
    const path = require('path');
     
    module.exports = {
        entry: [
            path.resolve(__dirname, "src/scripts/main.js"),
        ],
        output: {
            filename: 'bundle.js',
            path: path.resolve(__dirname, 'dist'),
        },
        module: {
            rules: [
                {
                    test: /\.css$/,
                    use: [
                        'style-loader',
                        'css-loader',
                    ],
                }
            ],
        },
    };
  10. Complete the configuration of webpack by locating the package.json file, and adding build to the scripts property:
    Copy
    "scripts": {
        "test": "jasmine",
        "build": "webpack"
    }
  11. Enter the following command to build the project:
    Copy
    npm run build
  12. Verify that the bundle.js file is created in the dist directory.
    In previous step, you updated the index.html file in the dist directory. The bundle file contains JavaScript that dynamically inserts your CSS into the HTML page.
  13. Ensure that the custom page runs in all supported browsers by adding the following modules:
    1. Enter the following command to install the required modules:
      Copy
      npm install babel-loader core-js whatwg-fetch --save-dev
    2. Update the babel.config.json as follows:
      Copy
      {
          "presets": [
              [
                  "@babel/preset-env",
                  {
                      "useBuiltIns": "entry",
                      "corejs": 3
                  }
              ]
          ]
      }
    3. Update the webpack.config.js file as illustrated in the following code.
  14. Verify that the project structure for your custom page matches the following screen shot.

    (Click to expand)

    Project structure for custom page

  15. Rebuild and deploy your custom page.

    Note: When deploying your bundled custom page, you only need to add the contents in the dist directory to the HelloWikipedia.CustomPage.zip file. No other files or directories are required.

  16. Verify that your custom page runs properly in all supported browsers.