Portal Page Templates (6.2.1+)

Portal Pages allow for a wide range of customizations. They are configurable via:

  • Layouts that determine the structure of a page
  • Templates that provide a more basic set of controls to allow end-users to select options by either:
    • Using single and multi-select options
    • Entering simple (unformatted) or rich (formatted) text

This article details how to add and tailor Portal Page Templates to your specific needs. It assumes basic knowledge of HTML and the various objects in Metric Insights.  The target audience is Administrators and Power Users with associated Portal Page Privileges.

[Release 6.2.5]: Portal Pages have been moved to the Content menu.

1. Create a New Template

Access Content > Portal Pages > Templates tab

The list page containing all available Portal Page Templates opens.

  1. Below the grid, click [+ New Template]
  2. Name: appears in the Templates list and drop-down lists in Metric Insights
  3. Internal name: is used to build a page URL, so avoid spaces in this field
  4. [Save]

2. Configure Template

You may contact support@metricinsights.com to get Portal Page Template examples or configure your own Templates by adding the code yourself, as described below.

  1. To be able to use a Template, make sure it is enabled
  2. Enable Sync with Git to upload assets from a repository located in:
  3. Optionally, select a Preview Image
  4. Display without Metric Insights navigation bar: allows switching from the default Portal Page layout. If this option is enabled, choose a personalized layout from the Layout drop-down
  5. [Save]

3. Enter Code for Portal Page Template

Access the Code tab

  1. Enter the HTML, CSS, and/or JavaScript Code in the provided field, or upload files manually from the Assets tab.
  2. [Save]

4. Customize the Image Capture Setting  

Access the Advanced tab

The Image Capture setting allows to configure the condition to take a Portal Page screenshot for an External Report.

  1. Timeout: specify a time interval after which a screenshot is taken once the Portal Page is opened
  2. Screenshot on: select a condition of taking a screenshot. Note that a screenshot will be taken when the selected condition is met or after the time interval specified in the Timeout field has elapsed
    • Only on Timeout: a screenshot is taken after time interval specified in the Timeout field
    • Element Removed from Page: this condition is appropriate if you want a screenshot to be taken after some element disappears from a Portal Page. The element can be set in the CSS Selector field; e.g., if you want a screenshot not to be taken until the Portal Page is fully loaded, enter .loading to the CSS Selector field
    • Element Added to Page: select this condition if you want a screenshot to be taken when some element appears on a Portal Page. The element can be set in the CSS Selector field
  3. [Save]

5. Modify your Template with Custom Variables

[Release 6.2.4]: 'Tags' renamed to 'Variables'.

Metric Insights allows you to define and add your own Variables to the code in order to have more control over how your Portal Pages are populated.

NOTE:

  • Variable names in the code must match the Names of Variables that are custom-added. Otherwise, they will be treated as "undefined" and the corresponding warning message will appear
  • Variable Names are case-sensitive, the maximum length of Variable Name is 255 characters
  • The maximum size of Variable Value is 64 Kb of text

5.1. Add Variables to the Template

  1. Add your Variables to the code
  2. Define your Variables' settings in the corresponding section:
  3. View the list of Global Variables

[6.2.5] The HOSTNAME Global Variable has been added, that stores the URL of MI instance.

5.2. Assign Variable Types

Clicking [+Variable] opens the Variable's settings.

Configuration options vary based on the Type assigned to a Variable:

  1. Text
  2. Select
  3. Multi Select

5.3. Specify Variable Settings Based on their Type

Settings will vary for different Variable Types. We recommend looking into different options before adding any Variables to your Templates.

5.3.1. How to Configure a Text Variable

Text Variables can be used to configure and modify the appearance of page headings or subheadings, text blocks or element URLs.

Integrated WYSIWYG Editor enables rich text editing.

  1. Provide the required settings:
    • Name
    • Type: "Text"
  2. Specify how to edit the Variable at the Variables tab of the Portal Page Editor:
    • Use WYSIWYG Editor
    • Specify whether the Variable is of List type
    • Use JSON Editor
  3. Optionally, provide a Default Value
  4. Provide Additional Options
  5. Optionally, enter JavaScript code
  6. [Apply]
List Variables

List Variables allow storing multiple values inside a single Variable.  These values are used for custom menu creation.

The entered data is converted to an array of JSON objects with the field names as keys and the user input as values.

5.3.1.1. Create New List Variable
  1. Enter a Name for the List Variable
  2. Type: "Text"
  3. Select "List"
  4. Additional Options: enter an array of Variable parameters:
    • Provide parameters as strings or as JavaScript objects
    • Parameters passed as JavaScript objects have three properties:
      • name: parameter name
      • type:  specify parameter value input type:
        • "textarea" for text input
        • "select" for a drop-down list (available values are specified in options property)
      • options: if type is set to "select", provide an array of available options
  5. [Save]

Example of Additional Options:

[
 "title",
 "url",
{
"name": "description",
"type": "textarea"
},
{
"name": "display",
"type": "select",
"options": ["left", "right", "top"]
}
]
5.3.1.2. Configure List Variable

Open the Variables tab of the Portal Page Editor

  1. Provide values for Variable parameters
  2. Click [+ Add] to add entries to your Variable

5.3.2. How to Configure a Select/Multi Select Variable

Select/Multi Select Variables can be used to embed other Portal Pages, Metric Insights Elements and Folders into a Portal Page.

Dimensions, Dataset Data and Static sources are not embedded directly, but implemented in the Code as JavaScript variables that will allow Users to further manipulate Portal Page data.

  1. Provide the required settings:
    • Name
    • Type: "Select"/"Multi Select"
    • Source: select the element you want to embed
  2. Provide the optional settings:
    • Additional Options
    • JavaScript Code
  3. [Apply]

5.4. Custom Variables Will Appear in the Portal Page Editor

Having added Variables to a Template, Users can employ these Variables to control the content that is displayed on a Portal Page. All customer-configured Variables are shown in the Portal Page Editor (access the Editor via Admin > Portal Pages).

All Variables that have been previously added to the Template will be displayed in the Portal Page Editor according to their pre-configured settings:

  • "Select/Multi Select" Variables will have a dropdown listing all Metric Insights elements that can be embedded into a Portal Page with this Variable
  • "Select" Variables will allow Users to embed only ONE element with one Variable whereas "Multi Select" Variables enable embedding Multiple elements

6. Customize Image Size using the "Resize" Option

The size of the Images embedded into Portal Pages can be modified with the resize/Y feature.

To change the size of the image, append /resize/Y at the end of the image URL. You can use either of the two options:

  1. /resize/Y/width/<width value>
  2. /resize/Y/height/<height value>

Example: URL of the resized image as displayed in browser: https://<hostname>.com/content/index/preview/element/842/segment/0/resize/Y/width/268

7. Use Case: Configuring a Portal Page with Custom Variables

Below is an example of a Portal Page built with a customizable Template.

The process is as follows:

  1. Add Variables to the Template
  2. Embed content using pre-configured Variables
  3. Verify how content is displayed on a Portal Page

7.1. Add Variables to the Template

  • As described in Section 4 of this article, we have added five custom Variables to the Template that will allow  five elements to be embedded into a Portal Page:
    • 3 Folders
    • 1 Dataset Report
    • 1 Visualization from an external platform
  • Dataset Reports allow adding various components (one or several Tables, Charts or External Visualizations). The embed code for each component can be obtained from Dataset Report Component Editors. (See details in Get the Embed Codes for Dataset Report Components)
  • Variables should be named in such a way that allows you to easily understand and remember which elements are going to be embedded.

7.2. Embed Content using Pre-Configured Variables

Custom Variables are associated with a specific Template. In order to be able to embed content via Variables, it is necessary to add the required Template to the Portal Page you are building.

  1. In the Add Portal Page pop-up, specify the Template you want to use for this Page.
    • Access the Add Portal Page pop-up via Admin > Portal Pages > click [+Portal Page] at the bottom of the Portal Page list.
    • For details, go to Overview of Portal Pages
  2. All custom Variables that have been added to the Template are shown in the Portal Page Editor.

7.3. Verify how Content is Displayed on a Portal Page

Below is an example of a Portal Page that was created for the Sales Operations team, based on the the Template shown above.