Portal Page Developer Helper

Portal Pages have been renamed to Apps in 7.1.0.

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

PREREQUISITE:

Table of contents:

  1. Create App Template and App
    1. Create App Template
    2. Create App
  2. Initialize New Project
  3. Open App Directory in IDE
  4. Modify Config File
    1. Configure Optional Parameters
  5. Configure package.json File
  6. Create Content for App
  7. Open App Locally
  8. Log In to Metric Insights
  9. View Opened App Locally And Work With Tool Panel
  10. Build App Assets

1. Create App Template and App

1.1. Create App Template

For MI v7.1.0+: Access Content > Apps > Templates tab

For MI versions prior to v7.1.0: Access Content > Portal Pages

  1. [+ New Template]
  2. Name: Enter a name for the App Template.
  3. [Save]

1.2. Create App

  1. [+New App]
  2. Enter an App Name, this will automatically generate the Name used in URL.
    • Note the Name used in URL down, it will be needed later for integration configuration.
  3. Select the previously created App Template.
  4. [Save], this will open the created App.
  5. Copy and note down the App's ID from the URL, this value will also be needed for further configuration.

NOTE: See Overview of Apps (Portal Pages) for general information on configuring Apps.

2. Initialize New Project

  1. Start scaffold:
npm create @metricinsights/pp-dev@latest
  1. Name your project.
  2. Name the package: Enter the App's Name used in URL value.
  3. Select a framework.
  4. Select a language variant.
  5. Choose whether to add Cursor rules.
  6. Choose whether to add MI components.
  7. Choose whether to install npm packages.
  8. Switch to the project directory:
 cd <project name>
  1. Run npm install

3. Open App Directory in IDE

4. Modify Config File

Note: File extension of the config file  pp-dev.config may vary depending on the options selected on project initialization.

  1. Open the config file pp-dev.config
  2. Enter values for the parameters:
    • backendBaseURL (string): The URL of your MI instance.
    • appId (integer): The ID of the previously created App.
      • portalpageId parameter is deprecated, use appId instead.

Save the entered data.

4.1. Configure Optional Parameters

Modify the config file pp-dev.config with optional parameters described in the table below.

 

ParameterValue TypeDefault ValueDescription
miHudLessbooleanfalse
  • When true, disables the Metric Insights navigation bar and back-end integrations (including jQuery) for App (Portal Page) local development, while still allowing access to App (Portal Page) Variables. 
  • When false, the default behavior is used.
integrateMiTopBarbooleanfalseIntegrates the Metric Insights Top Bar and required scripts into the app build. 
  • NOTE: Requires miHudLess to be set to true.

This parameter can be utilized for the following use-cases:

  1. Customize the Top Bar: Modify the appearance and behavior of the MI navigation.
  2. Bundle Integration: Include MI scripts in your build instead of loading them dynamically.
  3. Offline Development: Work with MI features even when disconnected from the server.
templateLessbooleanfalse
  • When true, App Variables are not fetched from an App  and the Metric Insights navigation bar is not displayed. If enabled, appId /portalPageId does not need to be provided. 
  • When false, the default behavior is used.
enableProxyCachebooleantrue
Enables caching of proxied requests to reduce the number of back-end calls. The cache stores resources such as stylesheets and images. 
  • NOTE: Disabling this option is not recommended.
proxyCacheTTLinteger600000Proxy cache time-to-live in milliseconds. 
  • Defaults to 10 * 60 * 1000 (10 minutes).
disableSSLValidationbooleanfalse
Disable SSL certificate validation for proxy requests.
imageOptimizerboolean | objecttrue
Control image optimization.
outDirstringdist
Output directory for builds.
distZipboolean | objecttrue
Controls whether build output is zipped. Can be an object to configure output directory and file name.

Object options: 
{ 
   outDir?: string, 
   outFileName?: string 
}
syncBackupsDirstringbackups
Directory used to store asset backups synchronized from the Metric Insights server.
v7Featuresbooleanfalse
Enable Metric Insights v7 features:
  1. Changes development path from /pt/<portal-page-name> to /pl/<portal-page-name>
  2. Updates Code Sync feature to use v7.1.0+ URLs
personalAccessTokenstringprocess.env.MI_ACCESS_TOKEN
Personal Access Token used to authenticate with the Metric Insights instance.
  • You can set it in your configuration or use the MI_ACCESS_TOKENenvironment variable.
    // pp-dev.config.js
module.exports = {
  backendBaseURL: 'https://mi.company.com',
  appId: 1,
  personalAccessToken: process.env.MI_ACCESS_TOKEN,
  miHudLess: true,
  integrateMiTopBar: true,
};
  • Set MI_ACCESS_TOKEN in your .env file:
MI_ACCESS_TOKEN=your_token_here

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

6. Create Content for App

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

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

7. Open App Locally

  1. Open Terminal.
  2. Run npm run dev
  3. Ctrl + click on the local link or copy and open it in the browser.
Expand or collapse content Console Shortcuts

NOTE: The shortcuts are 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.

8. Log In to Metric Insights

  1. Choose whether to log in with the Personal API Token, or Legacy Token.
  2. Enter the selected API Token.
  3. [Token Login]

9. View Opened App Locally And Work With Tool Panel

Once the App is opened, the Portal Page Developer Helper tool panel is displayed at the bottom-right 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 App on the Metric Insights instance.
  6. Uploads assets to the backups directory and upload them to the MI instance specified in the config file.

10. Build App Assets

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