Atrium.onlaunch( launchObject )

Atrium.onlaunch() is a function that may be defined to run when a "launch item" action happens. The parameter is an object containing the following fields:

  • url: a string containing the URL being launched.

  • newWindow: a boolean. True when the URL should be opened in a new browser window. False when it should be opening in a new atrium tab.

  • text: A string containing text from the launched action.

  • itemId: a string containing the Atrium ID attribute from the launched action.

  • firstTab: a boolean. True when the new Atrium tab being launched should be the first tab. False when the new tab should be the last tab.

  • closable: a boolean. True when the user should be able to close the new tab*. False otherwise.

A user-defined Atrium.onlaunch() function may be used to detect when an item is being launched. Alternately, it may be used to override the default Atrium behavior of creating a new tab or opening a new browser window.

If the user-defined function returns false, then Atrium does not create a new tab or open a browser window. If Atrium.onlaunch() doesn't return false, then a new tab is created or a browser window is opened after it returns.

The function should be defined in a javascript file located in /YourInstanceName/userdata/extension/atrium/.

*The closable argument can override how Atrium creates tabs. Changing the argument to false can prevent the [x] close-link from appearing on a tab. However, there are situations where preventing users from closing tabs would leave them no way to close the tab: macro errors, or other errors where pui.shutdown isn't called in the Rich Display session. For alternatives to preventing a tab from being closed, see Atrium.promptCloseTab and Atrium.promptCloseBrowser. There are also Atrium.launchURL or Atrium.launchItem, which accept a "closeable" parameter.

(In Profound Version 5, Fix Pack 8.0, closable can override the default Atrium behavior.)


If your instance name is "profoundui", create a new file on your IFS: /profoundui/userdata/extension/atrium/settings.js

Define the function like in the following example.

Atrium.onlaunch = function(launchObject){ if (launchObject.url.indexOf("macro=myMacro") > -1){ console.log("My custom macro should run now"); } }

Note: Without a return statement the example function returns undefined, so Atrium will draw a new tab or open a browser window.

Example - Prevent closing Default Home Page

This example shows how to prevent the "Default Home Page" tab from getting a close-link.

Atrium.onlaunch = function(parms) { if (parms.url == "/profoundui/userdata/html/atrium_home.html") parms.closable = false; }

Because JavaScript passes objects by reference, changing the parms.closable value inside the custom function affects the function which calls Atrium.onlaunch: Atrium.launchURL.