How to embed custom JavaScript in the Web App and the Self Service Portal

On this page

You can extend the Web App or the Self Service Portal with external content, such as videos, a chat, maps or web analytics, by adding your own JavaScript to its pages. An administrator of the web server saves the code as a script file, places the file in the folder of the Web App or portal instance, and restarts the instance from the Web Configuration tool. When you finish, your script runs on the pages of that instance.

Before you begin

  • Placing files on the web server is an on-premises task. Alloy Navigator Cloud customers contact support for this step. See Administering Alloy Navigator Cloud.
  • You work on the web server that hosts the instance, in the Web Configuration tool. The Web App package adds a Web Configuration shortcut to the Alloy Software > Alloy Navigator folder of the Start menu. See Publish the Web Applications.

Write the script

Save your JavaScript code as a file whose name starts with add_ and ends with .js, for example add_AlloyYouTube.js. You can add as many such files as you need. For a sample, see Example: show videos on the portal home page.

A custom script runs on every page of the instance. Code that writes into a part of one page should first check that the part is there.

Add the script to the Self Service Portal

Custom files of the portal go into the remix\client folder under the physical path of the portal instance.

In the Web Configuration tool:

  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.
  3. Copy your script file into the remix\client folder under that path.

The file 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 first page request after the restart starts the portal again and is answered with a temporary page while the portal starts. Your script reaches visitors once the portal is running again, never from placing the file alone.

Add the script to the Web App

Custom scripts of the Web App go into the js folder under the physical path of the Web App instance.

In the Web Configuration tool:

  1. In the tree, select the Web App instance. It is listed under its IIS site and named after its virtual directory.
  2. On the instance's information page, in the Web category, click the Physical path value. The folder of the instance opens in File Explorer.
  3. Copy your script file into the js folder under that path.

Then restart the Web App:

  1. In the tree, right-click the Web App instance and choose Restart, or click Restart on the instance's information page.

The tool restarts the instance's application pool and reports that the instance has been restarted. The Web App runs all add_*.js files of its js folder, in alphabetical order of their names.

Check how the portal runs your scripts

  • The portal serves all add_*.js files of remix\client 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 lets the visitor's browser reuse the script for five minutes, and keep using an older copy for up to eight hours while it checks for a newer one.

Example: show videos on the portal home page

When the portal builds its home page from the HTML dashboard template, template.html in remix\client, the shipped template carries two containers for your content: customHeaderDashboard at the top of the home page and customFooterDashboard at the bottom. For when the portal uses this template, see How the home page is built.

The following script, saved as add_AlloyYouTube.js, shows two videos of the Alloy Software YouTube channel in the header container. Each video appears as a thumbnail and starts playing when clicked. Because the script runs on every portal page, and again whenever the first part of the page's path changes, it does nothing when the container is missing or already holds its videos.

// ========== Preferences ==========
var container = document.getElementById("customHeaderDashboard");
var videos = ["DYCvL8UuTWA", "VMT6Nlcjo40"];
var height = "180px";

if (container && !container.querySelector(".custom-videos")) {
  renderVideos(container, videos, height);
}

// ========== Core function ==========
function renderVideos(container, videos, height) {
  var videoContainer = document.createElement("div");
  videoContainer.className = "custom-videos";
  videoContainer.style.display = "flex";
  videoContainer.style.justifyContent = "space-around";
  videoContainer.style.height = height;
  videoContainer.style.paddingTop = "20px";
  container.prepend(videoContainer);

  videos.forEach(function (id) {
    // The video's thumbnail stands in for the player
    var thumbnail = document.createElement("img");
    thumbnail.src = "https://i.ytimg.com/vi/" + id + "/mqdefault.jpg";
    thumbnail.style.height = "100%";
    thumbnail.style.cursor = "pointer";

    // A click replaces the thumbnail with the YouTube player, playing
    thumbnail.onclick = function () {
      var iframe = document.createElement("iframe");
      iframe.src = "https://www.youtube.com/embed/" + id + "?autoplay=1";
      iframe.style.height = "100%";
      iframe.style.border = "0";
      videoContainer.replaceChild(iframe, thumbnail);
    };

    videoContainer.appendChild(thumbnail);
  });
}

Change or remove a script

Edit or delete the script file in the folder where you placed it, then restart the instance from the Web Configuration tool again.

The portal serves its pages from copies of remix\client that it clears and re-creates each time it starts. Make your changes in remix\client itself: a change made in a copy is lost the next time the portal starts.

Keep your scripts across an upgrade

An upgrade of a web package replaces all files of its instances; customized instance files survive only in the backup made on the package's Files Backup page. Keep a copy of your script files. See Upgrade a Production Installation.

When the Web Configuration tool upgrades a Self Service Portal from the earlier portal, it copies every add_*.js file of the portal's Scripts folder into remix\client, and then deletes the Scripts folder.

Result

Your script files are in the folder of each Web App or portal instance you chose, and after the restart the instance runs them on its pages. To track portal usage with a Google tag in the same way, see Google Analytics.