Creating Next.js Portal Pages with Portal Page Developer Helper

Portal Page Developer Helper allows you to write code for Portal Pages in any IDE and then upload it to your Metric Insights application as Portal Page asset or sync from a repository. 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 pp-dev.config.js File
  6. Modify next.config.js File
  7. Configure package.json File
  8. Create Content for Portal Page
  9. Open Portal Page Locally
  10. Log In to Metric Insights and View Portal Page
  11. Build Application and Upload Changes to Portal Page

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

NOTE: Portal Page Developer Helper supports Next.js up to version 13.

If you already have a directory with a Next.js project, proceed to the Step 3: the installation of the Portal Page Developer Helper package.

Run npx create-next-app@latest <Project Name> from the local Portal Page directory replacing <Project Name> with the name of your project 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 pp-dev.config.js 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.

6. Modify next.config.js File

  1. Open a file named next.config.js
  2. Wrap the config options with the withPPDev function

6.1. Optional Parameters

  1. miHudLess:
    • true: The default value.
    • false: Metric Insights' navigation bar and back-end including jQuery are enabled for Portal Page's local development.
  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.

7. Configure package.json File

  1. Open package.json
  2. Assign the value of the dev script to "pp-dev next"

Save the config file.

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

Proceed with creating content for your Portal Page. 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.

9. Open Portal Page Locally

  1. Open a new Terminal
  2. Run npm run dev
  3. Ctrl + click on the local link or copy and open it in the browser

10. Log In to Metric Insights and View Portal Page

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

11. Build Application and Upload Changes to Portal Page

Once you have finished creating code for the Portal Page, see Next.js documentation for information on building the application.

After the application has been built, you can either archive the project and upload it as a Portal Page Asset or sync Portal Page with a repository hosted on GitHub, GitLab, or Bitbucket.