Administration Guide

Advanced Portal Customization

On this page

Beyond the settings described in Self Service Portal Settings, you can customize the Self Service Portal with files in the portal instance's folder on the web server: custom scripts and the HTML dashboard template. Writing these files is an on-premises task; Cloud customers contact support instead. See Administering Alloy Navigator Cloud.

Portal colors

The portal's eight color themes are built into the portal; they are not read from style-sheet files on the web server. The color theme stored for the instance selects one of them, and it is applied to the bar at the top of the portal's pages. To change the palette, choose another color theme for the instance; see Color Theme.

Whether a visitor sees the portal in light or dark mode is that visitor's own color mode: light, dark, or system, which follows the browser's color preference.

In the Web Configuration tool

Open the portal's folder

  1. In the Web Configuration window, select the Self Service Portal instance in the tree.
  2. In the information pane, find the Web category and click the "Physical path:" line.

    The portal instance's folder opens. Custom files go into its remix\client folder.

Restart the portal

A new or changed file in remix\client reaches visitors only after a restart of the portal.

  1. In the Web Configuration window, find the Self Service Portal instance in the tree.
  2. Right-click it and choose Restart, or select it and click Restart in the information pane.

On IIS 7 or later, the tool ends the processes of the instance's IIS application pool, including the portal's own server, then stops and starts the pool, and reports "<name> has been restarted". The tool restarts the pool in the same way after you reconfigure the instance's database settings.

The first page request after the restart starts the portal again and is answered with a temporary page while the portal starts. The new files reach visitors once the portal is running again, never from placing the files alone.

On the web server

The remix\client folder

Custom files go into the remix\client folder under the physical path of the portal instance. To find that folder, see Open the portal's folder.

The portal does not serve visitors from remix\client directly. Each time the portal starts, it clears and re-creates its own copies of the folder and serves from them, so:

  • A file you add to or change in remix\client reaches visitors only after the portal has been restarted. See Restart the portal.
  • The copies are under the server's common application data folder. A change made in a copy is lost the next time the portal starts, because each start clears the copies.

The portal ships seven files in the folder for file-based customization:

  • template.html - the default HTML dashboard template.
  • CustomPortletExample.html - the page the default template's Custom portlet shows.
  • custom.png - the title icon of a Custom portlet.
  • favicon.ico
  • login_bg.svg and login_bg_dark.svg - the background of the sign-in page, in light mode and in dark mode.
  • opfs-worker.js

Custom scripts

A custom script is a JavaScript file whose name starts with add_ and ends with .js, placed in the remix\client folder.

The portal serves all of these files together as one script, add.js:

  • The files appear in reverse alphabetical order of their names, each headed by a comment that names its file.
  • A file the portal cannot read is skipped.

Each portal page loads this script asynchronously. The page loads it again whenever the first part of the page's path changes, so a custom script runs again on each such navigation. The script's address carries the current path in its location parameter.

The portal marks the served script as private and lets the visitor's browser reuse it for five minutes, and keep using an older copy for up to eight hours while it checks for a newer one.

HTML dashboard template

The HTML dashboard template is the template.html file in the remix\client folder. For when the portal uses this template for its home page, see Portal Home Page.

A <portlet> element can carry eight attributes: type, title, itemCount, anonymousAccess, url, cssClass, orderBy, and filter. The url attribute is used by a Custom portlet.

The portal reads every <portlet> element of the template, and when it serves the template:

  • It leaves out every portlet whose type the portal does not recognize.
  • It leaves out every portlet of a module that is off for the instance.
  • It requires the url of a Custom portlet to end in .html.

A Custom portlet shows the HTML page its url names in a frame on the dashboard. The portal checks that the page can be reached before it shows the frame. The shipped template has one Custom portlet, which shows CustomPortletExample.html from the same folder.

The shipped template also carries two containers, customHeaderDashboard and customFooterDashboard.