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. Optionally, select a Preview Image
  3. Enable Git Sync to upload assets from a repository located in:
  4. Optionally, switch from default Catalog Layout to a custom Layout (for details, refer to Layouts for Portal Pages)
  5. If you opt to use a personalized Layout, choose one from the drop-down
  6. Enter the HTML, CSS, and/or JavaScript Code in the provided field, or upload files manually from the Assets tab
  7. [Save]

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

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

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

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

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

3.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"]
}
]
3.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

3.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]

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

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

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

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

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

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