Best Practices for Portal Page Developers

Do Portal Pages inherit CSS from the rest of the application?

If setting Catalog Layout is set to "Yes", a Portal page inherits all styles from the application, including its theme (if applicable). 

To use custom CSS classes, we recommend adding a prefix cp_ (custom page) in front of new class names. iframes can be used to prevent CSS overlaps from happening.

What are the JavaScript libraries that I can use?

  • If Catalog Layout is set to "No", you may use any JavaScript library.
  • If Catalog Layout is set to "Yes", all JavaScript libraries available in Metric Insights can be used with a few exceptions:
    1. jQuery must be used in no-conflict mode
    2. Highcharts v5.0.4 and Underscore.js version 1.8.3 are available globally
    3. Ext.js is not allowed

How can I store data in JavaScript?

As of Metric Insights 6.1.0, Portal Page developers can utilize the following methods:

  1. storeData() will it store states in JSON format
  2. getData() will display data about state that was previously saved

All state-related data saved in the portal_page_data table within dashboard_db

States can be global or localized to a specific user via a per_user_ind Y/N boolean. The default is set to global (N)

How should I manage my assets?

There are several ways of managing Assets like JavaScript libraries, CSS and images:

  • sync with a Git repository located in:
  • manually upload via ZIP archive
  • directly upload via the Assets tab (Admin > Portal Pages > Assets) and directly link from either the Portal Page, Template, or Layout

Note: You cannot reference externally hosted libraries. They must be hosted within the MI system itself. We enforce this to meet common security requirements in the enterprise.

If I use a custom theme, how do I apply those colors/styling to my portal page?

  • If Catalog Layout is set to "Yes", the theme will be applied automatically.
  • If Catalog Layout is set to "No", the developer should explicitly include theme CSS in their layout.

How do I track links opened from a Portal Page?

In order to call the tracking function, your Portal Page must have access to the /js/application/portal_page_view.js file:

  • If Catalog Layout is set to "Yes", this file is already included into the Portal Page by default
  • If Catalog Layout is set to "No", include the /js/application/portal_page_view.js file into Portal Page's HTML via the <script> tag:

<script src="https://<hostname>.com/js/application/portal_page_view.js"></script>

JavaScript call of the tracking function: MI.PortalPageView.logClick(href,page_internal_name);

Function parameters:

  • href:  URL of the opened link
  • page_internal_name: an Internal Name of the Portal Page from which the link is opened

All the tracked data is stored in the portal_page_link table of the Dashboard database in the following format:

portal_page_link
portal_page_link_id portal_page_internal_name user_id link_clicked view_time

How to use the 'Enable POST request navigation from other sites' option?

POST requests from sites other than current Metric Insights instance are disabled by default due to security considerations; however, this behavior can be changed by activating the Enable POST request navigation from other sites option from the Portal Page's Advanced tab. This will allow receiving POST requests from sites other than your Metric Insights instance.

An example of using this feature is configuring OAuth 2.0 authentication:

  • MI sends an authentication request to the Microsoft identity platform
  • User receives a POST response with an ID token and an Access token

See the How do I manage OAuth 2.0 authentication for Portal Pages using JWT? section for a detailed description of the use case.

How do I manage OAuth 2.0 authentication using JWT for Portal Pages?

PREREQUISITES:

Example authentication request:

$.ajax({
 "url":"/data/page/<Portal Page internal name>/auth/info"
 ,"success":function(response){
  if(null==response.post){
   document.location = 
   'https://login.microsoftonline.com/<tenant ID>/oauth2/v2.0/authorize'
   +'?client_id=<client ID>'
   +'&response_type=id_token%20token'
   +'&response_mode=form_post&scope=openid%20email%20profile'
   +'&state=<state>&nonce=<nonce>'
   +'&redirect_uri'+encodeURIComponent('https://<MI hostname>/p/<Portal Page ID>/');

The ID token and Access token can be accessed via the returned response object's properties: response.post.id_token and response.post.access_token respectively.

Note: See the Get an access token to call UserInfo section for details on authentication requests.