Help & Documentation
Open Support Ticket

Modifying App (Portal Page) Template with Custom Variables

Portal Pages have been renamed to Apps in v7.1.0.

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

NOTES:

  • 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.
  • Variable placeholders must be written differently depending on the value type:
    • Strings: Use single quotes, for example '[Title]'
    • Numbers: Do not use single quotes, for example [SalesNumber]
    • List variables: Do not use single quotes, for example [FeatureList]

1. Adding Variables to the Template

Open the Template Editor and access the Variables tab:

  • For MI v7.1.0+: Access Content > Apps > Templates tab > Select a Template > Variables tab
  • For MI versions prior to 7.1.0: Access Content > Portal Pages > Templates tab > Select a Template > Variables tab

[+Variable] to open the Variable Editor screen.

2. Configuring Variable

  1. Name: Enter the Variable name.
  2. Description: In this field you can type instructions for the User.
  3. Type: Select the Variable Type from the drop-down menu. Check the Variable types description below.

3. Variable Types

Settings will vary for different Variable Types. We recommend reviewing the available options before adding Variables to your Templates.

3.1. Text Variable

Use Text Variables for titles, labels, descriptions, or any single-line text.

A Text Variable accepts a string value. Text Variables can be used to configure and modify the appearance of page headings or subheadings, text blocks, or element URLs.

The integrated WYSIWYG Editor enables rich text editing.

  1. Use WYSIWYG Editor: Activate this checkbox if you want to edit the Variable in WYSIWYG Editor.
  2. Raw HTML: Activate this checkbox if you want to edit the Variable as raw HTML.
  3. Use JSON Editor: Activate this checkbox if you want to edit the Variable in JSON Editor.
  4. Default Value: The text you type here will be displayed in the Variable text field and can be edited.
  5. This is an example how different Text Variables are displayed on the Content tab of the App.

3.2. Select/Multi Select Variable

Select/Multi Select Variables can be used to embed Announcement, Categories, Custom Attributes, Datasets, Dataset Data, Elements, Folders, Groups, Apps, App Entities, Dimensions, and Static user-entered values.

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 App data.

  1. Source: Select the object you want to embed.
  2. Additional Options: If you choose "Static" or "Dataset Data" option in the Source drop-down menu, here you can specify the contents of the list that will be shown in the App Editor by entering JSON.

3.3. File Variable

File Variable can be used to upload a file that will be used for App layout or content.

3.4. List Variables

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

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

  1. Use JSON Editor: Activate this checkbox, if you want to edit the Variable in JSON Editor.
  2. Default Value: Optionally, add a default array of Variable parameters.
  3. Additional Options: Enter a JSON array of Variable parameters:
    • Provide parameters as strings or as JavaScript objects.
    • Parameters passed as JavaScript objects have the following properties:
FieldValue TypeDescription
namestringDefines the field name.
typestringSpecifies the field input type. Allowed values:
  • "text"
  • "textarea"
  • "select"
  • "multi-select"
  • "boolean"
  • "file"
sourcestringOptional. Used for select-type fields to specify the source object.
optionsarrayOptional. Used when the field type requires a predefined list of values.

Additional Options Examples

List with text fields only:

["Title", "Icon", "FolderID"]

List with text and select:

[
  "Title",
  "Icon",
  { "name": "Type", "type": "select", "options": ["type-1", "type-2", "type-3", "type-4"] }
]

List with textarea and select:

[
  "title",
  "url",
  {
    "name": "description",
    "type": "textarea"
  },
  {
    "name": "display",
    "type": "select",
    "options": ["left", "right", "top"]
  }
]

List with file field:

[
  "Title",
  { "name": "Image", "type": "file" }
]

List with dataset selector:

[
  "Title",
  { "name": "Element", "type": "select", "source": "dataset" }
]

List with multi-select elements:

[
  "Title",
  { "name": "Elements", "type": "multi-select", "source": "element" }
]

List with boolean:

[
  "Title",
  { "name": "Is Active", "type": "boolean" }
]

Full example:

[
  "Title",
  "Icon",
  { "name": "Type", "type": "select", "options": ["type-1", "type-2", "type-3", "type-4"] },
  { "name": "Image", "type": "file" },
  { "name": "Element", "type": "select", "source": "dataset" },
  { "name": "Elements", "type": "multi-select", "source": "element" },
  { "name": "Is Active", "type": "boolean" }
]

3.4.1. Populate Items for List Variables

Open the Content tab of the App Editor (this has to be the App that uses Template you are creating).

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

3.5. Color Variable

Color Variable can be used to provide a color picker that shows the HEX code of the chosen color.

3.6. Boolean Variable

Boolean Variable supports values True and False.

4. Custom Variables Will Appear in the App Editor

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

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

  • File Variable will have an Upload button which allows loading image files from the PC.
  • Color Variable shows the chosen color and its HEX code in the field below.
  • Select/Multi Select Variables will have a dropdown menu with 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.
  • Boolean Variables allow to select between the "True" and "False" values.

5. Using Variables in App Code

Where Variables Are Allowed

App Variables can only be used in the entry HTML document, not in arbitrary .js or .tsx files.

Stack Where to put variable placeholders
Vanilla JS index.html
React (for example, Vite + React) index.html
Next.js document.tsx (or your custom document)

For Next.js, window.PP_VARIABLES is wired through the build so that, after the build, Variable values end up in index.html (the shipped HTML). Design placeholders accordingly in the document that becomes that HTML.

Rules for Using Variables in Templates

How you write the placeholder depends on the type of value the Variable produces:

<h1>'[Title]'</h1>
<p>'[Subtitle]'</p>
<img src="'[Logo]'" alt="Logo" />
<div style="background-color: '[PrimaryColor]'">...</div>

The platform replaces '[VariableName]' with the actual value when the App is rendered. 

Variable names are case-sensitive and must exactly match the names defined in the App configuration.

Result type In HTML / template Example
String (text, file URL, color, boolean as string, etc.) Wrap in single quotes '[Title]', '[Logo]'
Number No surrounding quotes [SalesNumber]
List Do not use single quotes [FeatureList]

Syntax Examples in HTML

Strings (Text, File, Color, Boolean in Template)

<h1>'[Title]'</h1>
<p>'[Subtitle]'</p>
<img src="'[Logo]'" alt="Logo" />
<div style="background-color: '[PrimaryColor]'">...</div>

Number

<span data-sales="[SalesNumber]"></span>

List (No Quotes)

<div id="list-data" class="list-placeholder">[FeatureList]</div>