Portal Page Developer Helper

Portal Page Developer Helper allows you to write code for Portal Pages in any IDE and then import it to your Metric Insights application as Portal Page asset. Also you can launch your Portal Page on localhost before applying any changes to the actual Portal Page's code.

PREREQUISITE:

Table of contents:

  1. Create Portal Page
  2. Create package.json File in Portal Page Directory
  3. Install Portal Page Developer Helper Package
  4. Open Portal Page Directory in IDE
  5. Create a Config File
  6. Configure package.json File
  7. Create Content for Portal Page
  8. Open Portal Page Locally
  9. Log In to Metric Insights
  10. View Portal Page Locally And Work With Tool Panel
  11. Build Portal Page Assets

1. Create Portal Page

Access Content > Portal Pages

  1. [+New Page]
  2. Enter a Portal Page Name
  3. Enter a Name used in URL and note it down, it will be needed later for integration configuration
    • Note: Letters, numbers, dashes and underscores are the only supported characters for Portal Pages' URL names
  4. [Save], this will open the created Portal Page
  5. Copy and note down the Portal Page's ID from the URL, this value will also be needed for further configuration

2. Create package.json File in Portal Page Directory

Run npm init from the local Portal Page directory and proceed entering the needed data to create a package.json file.

3. Install Portal Page Developer Helper Package

Run npm i @metricinsights/pp-dev to install the Portal Page Developer package.

4. Open Portal Page Directory in IDE

In an IDE:

  1. Ctrl + K Ctrl + O or [Open Folder]
  2. Select the Portal Page Folder, [Select Folder]

5. Create a Config File

Note: The name of the config file must be pp-dev.config.

  1. Create a file named pp-dev.config.js
  2. Enter the following code:
module.exports = {
    backendBaseURL: '<MI Application Server>',
    portalPageId: <Portal Page ID>,
  };

Replace <MI Application Server> with the URL of your MI instance and <Portal Page ID> with the ID of the previously created Portal Page. Save the entered data.

5.1. Optional Parameters

  1. miHudLess:
    • true: Metric Insights' navigation bar and back-end including jQuery are disabled for Portal Page's local development, Portal Page Variables are accessible.
    • false: The default value.
  2. templateLess:
    • true: Portal Page Variables are not fetched from a Portal Page. Metric Insights' navigation bar is not displayed. If this parameter is set to true, the portalPageId parameter does not have to be provided.
    • false: The default value.
  3. enableProxyCache:
    • true: The default value.
    • false: The proxy cache is disabled. It is not recommended to change the value of this parameter, as the proxy cache is utilized to reduce the number of requests to the back-end. It caches the requests to different files, such as containing styles and images.
  4. proxyCacheTTL: The proxy cache's time-to-live in milliseconds. The default value is 10 * 60 * 1000.

6. Configure package.json File

  1. Open package.json
  2. Add the following code to the scripts property:
"dev": "pp-dev",
"build":"pp-dev build"

Save the config file.

7. Create Content for Portal Page

Note: Files that are not used in the Portal Page are not transferred to the archive with Portal Page assets. The exception is the directory public.

  1. Create an index.html file
  2. Enter the Portal Page's code in the index.html file
  3. Optionally, create a directory named public the contents of which are transferred to the archive with Portal Page assets regardless of being utilized in the Portal Page
    • The contents of the public folder are transferred to the root of the archive with Portal Page assets. However, you can create folders inside the public, these folders and their contents will be transferred to the archive's root.

8. Open Portal Page Locally

  1. Access Terminal > New Terminal
  2. Run npm run dev
  3. Ctrl + click on the local link or copy and open it in the browser
Console Shortcuts

Currently not available for Next.js

The following console shortcuts are available:

  • l: Re-login to the proxy server
  • r: Restart the server
  • u: Show server URL
  • o: Open in browser
  • c: Clear console
  • q: Quit
  • C: Clear proxy cache

9. Log In to Metric Insights

  1. Enter credentials of an Admin user from the MI application server that you have listed in the config file
  2. [Login]

10. View Portal Page Locally And Work With Tool Panel

Once the Portal Page is opened, the Portal Page Developer Helper tool panel is displayed at the bottom-left corner of the screen with its controls:

  1. Hide tool panel
  2. Open link to the npm package of the Portal Page Developer Helper
  3. Open link to the Metric Insights instance
  4. Shows whether or not the Template mode is enabled. This is controlled by the templateLess parameter
  5. Open link to the Portal Page on the Metric Insights instance

11. Build Portal Page Assets

  1. Execute run npm build in the terminal
  2. Folder dist-zip is created and contains a zip archive with Portal Page's assets and contents of the public directory. This archive can be uploaded to the Metric Insights' instance.