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
- In the Web Configuration window, select the Self Service Portal instance in the tree.
-
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\clientfolder.
Restart the portal
A new or changed file in remix\client reaches visitors only after a restart of the portal.
- In the Web Configuration window, find the Self Service Portal instance in the tree.
- 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\clientreaches 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'sCustomportlet shows.custom.png- the title icon of aCustomportlet.favicon.icologin_bg.svgandlogin_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
urlof aCustomportlet 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.