Skip to main content
Skip table of contents

JavaScript API reference for portal containers

The following JavaScript APIs are available for use in NexJ CRM portal containers.

They enable portlets developed outside of NexJ Studio to interact with NexJ CRM infrastructure.

PortalAPI.addPortalToastMessages

Adds toast messages to the notification queue. Each message will be displayed sequentially.

Syntax

PortalAPI.addPortalToastMessages(bPrependBaseURL, messagesArray)

PortalAPI.addPortalToastMessages parameters

ParameterValueDescription
bPrependBaseURLBooleanIndicates whether to prepend each message icon URL with the calling portlet's group base URL. Values are true and false. If the value is not true, the message icon URL is expected to be an absolute URL.
messagesArrayObject ArrayAn array of toast messages. Each message is an object with the following parameters:
messagesArray[].iconStringThe icon URL. (Optional)
messagesArray[].textStringThe HTML markup to display in the toast message.
messagesArray[].eventStringThe name of the event to fire when the user clicks on toast message. (Optional)
messagesArray[].paramsObjectThe parameters associated with the event when the user clicks on toast message. (Optional)

Example

JS
PortalAPI.addPortalToastMessages(false, [{icon:”http://myserver/imgs/icon1.png”, text:”You have new mail”, event:”newMailEvent”,     params{id:”abc123”, subject:”Cancelling meeting”}}])

Displays a single toast message that contains the specified icon and text. When a user clicks the toast notification, an event named newMailEvent is broadcasted to listening portlets. A JavaScript object, which includes an id property and a subjectproperty, is provided to the event as a parameter.

PortalAPI.addTrustedHost

Adds a host name to the list of hosts whose messages are always trusted. Only needed in cross-domain configurations. If this portlet will be embedded in multiple containers then this should be called once for each container.

As well, the host name from the src attribute of the of the script element with id="NexJ-Portal-API" is trusted:

JS
<script id="NexJ-Portal-API" 
   src="http://portalserver/portal/portal-api-1.0.js">

Syntax

PortalAPI.addTrustedHost(sHost)

PortalAPI.addTrustedHost parameters

ParameterValueDescription
sHostStringThe name of the host.

PortalAPI.broadcastEvent

Broadcasts an event to other portlets.

Syntax

PortalAPI.broadcastEvent(sName, parameter)

PortalAPI.broadcastEvent parameters

ParameterValueDescription
sNameStringThe name of the event.
parameterObjectThe parameter of the event.

Example

PortalAPI.broadcastEvent(“systemMaintenance”, {user:”admin”, date:”July 1, 2013”})

The portal container broadcasts an event named systemMaintenance to listening portlets. A JavaScript object that includes a user property and a date property is provided to the event as a parameter.

PortalAPI.fireEvent

PortalAPI.closeWorkspace

Closes the workspace in which the portlet resides.

Syntax

PortalAPI.closeWorkspace()

PortalAPI.fireEvent

Sends an event to the application broker portlet and the portal container.

Info

Unlike PortalAPI.broadcastEvent, firing an event does not allow other porlets to receive the event. The event will only be propagated to the application broker portlet and the portal container.

Syntax

PortalAPI.fireEvent(sName, parameter)

PortalAPI.fireEvent parameters

ParameterValueDescription
sNameStringThe name of the event.
parameterObjectThe parameter of the event.

Example

JS
PortalAPI.fireEvent(“addQuickTask”, {user:”admin”, duedate:”July 21, 2013”, desc:”Call Marvin about portfolio”})

The portal container fires an event named addQuickTask that will be handled by the broker portlet. A JavaScript object, which includes a user property, a duedate property, and a descproperty, is provided to the event as a parameter.

Related links

PortalAPI.broadcastEvent

PortalAPI.getAllGlobalProperties

Obtains a list of all global properties and their values that are used by the container. The global properties are returned asynchronously through a callback method.

Info

Set a global property value using PortalAPI.setGlobalProperty.

Syntax

PortalAPI.getAllGlobalProperties(callback)

PortalAPI.getAllGlobalProperties parameters

ParameterValueDescription
callbackFunctionA callback function that accepts one map argument. When the server responds, the callback will be invoked with the global properties map passed as the argument. The key-value pair of the map is the name of the global property and its associated value.

Related links

PortalAPI.setGlobalProperty

PortalAPI.getContext

Determines if the calling portlet's session has been persisted. The flag is returned asynchronously through a callback method.

Info

Set context values using PortalAPI.setContext.

Syntax

PortalAPI.getContext(sVarName, callback)

PortalAPI.getContext parameters

ParameterValueDescription
sVarNameStringThe name of the context variable to retrieve. Can be null to return all context values.
callbackFunctionA callback function that accepts one argument. When the server responds, the callback will be invoked with the context value passed as the argument if the context variable name is specified. If the context variable name is null, then the argument is a map of context key-values.

Related links

PortalAPI.setContext

PortalAPI.getGlobalProperty

Obtains the value of a single global property used by the container. The global property value is returned asynchronously through a callback method.

Info

Set a global property value using PortalAPI.setGlobalProperty.

Syntax

PortalAPI.getGlobalProperty(sPropName, callback)

PortalAPI.getGlobalProperty parameters

ParameterValueDescription
sPropNameStringThe name of the property.
callbackFunctionA callback function that accepts one argument. When the server responds, the callback will be invoked with the global property value passed as the argument.

Related links

PortalAPI.setGlobalProperty

PortalAPI.getPortletAlias

Obtains a unique identifier for the calling portlet. The portlet alias is returned asynchronously through a callback method.

Syntax

PortalAPI.getPortletAlias(callback)

PortalAPI.getPortletAlias parameters

ParameterValueDescription
callbackFunctionA callback function that accepts one string argument. When the server responds, the callback will be invoked with the portlet alias passed as the argument.

PortalAPI.isAvailable

After initialization, determines if the portal API is ready and available for use.

Syntax

PortalAPI.isAvailable()

PortalAPI.isSessionPersisted

Determines if the calling portlet's session has been persisted. The flag is returned asynchronously through a callback method. Calling this API does not affect the last accessed time.

Info

When persistent session timeout is set, the portal server can determine if the portlet has timed out by comparing its last accessed time using PortalAPI.setPersistentSessionTimeoutPeriod. PortalAPI.setBusy is updated whenever the ready state is updated.

Syntax

PortalAPI.isSessionPersisted(callback)

PortalAPI.isSessionPersisted parameters

ParameterValueDescription
callbackFunctionA callback function that accepts one boolean argument. When the server responds, the callback will be invoked with the session persisted flag passed as the argument. True if the session is persisted; otherwise, false.

Related links

PortalAPI.setPersistentSessionTimeoutPeriod
PortalAPI.setBusy

PortalAPI.navigate

Navigates to an existing workspace that contains the portlet specified by the view path.

Syntax

PortalAPI.navigate(viewPathArray, newContextMap, eventInfoMap, fallbackViewPathsArray)

PortalAPI.navigate parameters

ParameterValueDescription
viewPathArrayString ArrayAn array of strings that specifies the location to navigate to. The first element of the array is the name of the workspace. The second element of the array is the name of a portlet reference.
newContextMapMapA map of context variable name-value pairs. After successfully navigating to the portlet specified by the view path, the values from this map are used to update the context variables in the workspace in which the portlet resides. This is done as if you had called PortalAPI.setContext(key, value) for each key-value pair in the map. Can be null.
eventInfoMapObjectThe event to fire on the destination portlet after a successful navigation. Can be null.
eventInfoMap.nameStringThe name of the event.
eventInfoMap.paramObjectThe parameter of the event.
fallbackViewPathsArrayObject ArrayAn array in which each element is itself an array like the one used in the viewPathArray parameter. That is, each element of the main array is a two-element array of strings in which the first element is the name of a workspace and the second element is the name of a portlet reference. This parameter specifies a list of alternative view paths to attempt navigating to if the one specified by the viewPathArray parameter cannot be found. (Optional)

Example

JS
PortalAPI.navigate('["DockedEntity"]',
 '{"EntityId":"1043348EDDF9B04F16B4C296B7D91721AD"}', 'null', 
'[["Person", "refEntityNavigatorPortlet"]]')

Navigates to the DockedEntity workspace and sets its EntityId context variable value to 1043348EDDF9B04F16B4C296B7D91721AD. If the DockedEntity workspace is not available, it will navigate to refEntityNavigatorPortlet in the Person workspace instead. No event is fired on the target portlet after navigation is completed.

PortalAPI.notifyPortletExpired

Notifies the portal container that the calling portlet's session is invalidated.

Syntax

PortalAPI.notifyPortletExpired(sExpirationMessage, bLogoutContainer)

PortalAPI.notifyPortletExpired parameters

ParameterValueDescription
sExpirationMessageStringA message to display to the user.
bLogoutContainerBooleanIndicates whether to restart the portal container. Values are true and false.

PortalAPI.openAppPerspective

Loads a new application perspective in a layout zone.

Syntax

PortalAPI.openAppPerspective(sPortletLayoutRefName, sWorkspaceTemplateName, sCaption, sIcon, configs)

PortalAPI.openAppPerspective parameters

ParameterValueDescription
sPortletLayoutRefNameStringThe name of the portlet layout reference, identifying the zone to load the application perspective.
sWorkspaceTemplateNameStringThe name of the application perspective.
sCaptionStringThe caption of the application prespective.
sIconStringThe URL of application prespective icon. If empty no icon will be displayed.
configsArrayA list of application configuration data (application configuration ID, caption, and icon).
configs[].configIdStringID of the configuration.
configs[].captionStringCaption of the application configuration.
configs[].iconStringThe icon URL. (Optional)

PortalAPI.openWorkspace

Opens a workspace or switches to a workspace if one matching the parameters is already open.

Opening a workspace has different behavior depending on which parameters are set. In all cases when searching for an opened workspace that matches the given parameters, if multiple workspaces matches the specified conditions, the workspace with the lowest ordinal number will open. Similarly, when opening a new workspace, the workspace template with the lowest ordinal that matches the specified conditions is used.

  • sWorkspaceTemplateName, sCtxtVarName, ctxtVal
    If all of these values are provided, then the current set of open workspaces is searched for an exact match of the three parameters. If a match is found, then it becomes the active workspace. If no match is found, then the portal framework will look for a workspace template configured with a workspace template name, context variable and open that workspace using the specified context value.
  • sCtxtVarName, ctxtVal
    If these two values are provided, then the current set of open workspaces is searched for any dynamic workspace that matches the context variable and value. If a match is found, then it becomes the active workspace. If no match is found, then the portal framework will look for a workspace template configured with a matching context variable and open that workspace using the specified context value.
  • sWorkspaceTemplateName
    If only the template name is provided, then the current set of open workspaces is searched for a workspace based on the specified template. If a match is found, then it becomes the active workspace. If no match is found, the system opens a new workspace making use of the template.

Syntax

JS
PortalAPI.openWorkspace(sWorkspaceTemplateName, sCaption, sIcon, sCtxtVarName, ctxtVal, wkspContext, argArray)

PortalAPI.openWorkspace parameters

ParameterValueDescription
sWorkspaceTemplateNameStringThe name of the workspace template to use when opening a new workspace. Can be null if a context variable name and value are specified.
sCaptionStringIf a new workspace tab is created, then the workspace tab will use this caption.
sIconStringThe absolute URL of the workspace tab's icon. If null, no icon is shown.
sCtxtVarNameStringThe name of the context variable. Can be null if a workspace template name is specified.
ctxtValStringThe context value. Can be null if workspace template name is specified.
wkspContextStringA context map for initializing the workspace.
argArrayStringA list of additional argument pairs.

PortalAPI.registerEventHandler

Registers and loads one or more application service portlets. Application service portlets do not have any UI, and are active in the background throughout the lifetime of the portal container. These portlets are not associated with the active workspace.

Info

Fire an event from a portlet using PortalAPI.fireEvent. Broadcast an event to other portlets using PortalAPI.broadcastEvent.

Syntax

PortalAPI.registerServicePortlets(screenNameArray)

PortalAPI.registerEventHandler parameters

ParameterValueDescription
screenNameArrayString ArrayAn array of portlet names to load as service portlets.

Related links

PortalAPI.registerServicePortlets
PortalAPI.fireEvent
PortalAPI.broadcastEvent

PortalAPI.registerServicePortlets

Registers and loads one or more application service portlets. Application service portlets do not have any UI, and are active in the background throughout the lifetime of the portal container. These portlets are not associated with the active workspace.

Info

To register an event handler use PortalAPI.registerEventHandler.

Syntax

PortalAPI.registerServicePortlets(screenNameArray)

PortalAPI.registerServicePortlets parameters

ParameterValueDescription
screenNameArrayString ArrayAn array of portlet names to load as service portlets.

Related links

PortalAPI.registerEventHandler

PortalAPI.registerToolBar

Registers a toolbar with the portal container. When the portlet is loaded into a workspace, the menu that you have defined appears in the toolbar. The menu is removed from the toolbar when the user switches workspaces.

Syntax

PortalAPI.registerToolBar(sName, actionBarData)

PortalAPI.registerToolBar parameters

ParameterValueDescription
sNameStringA name to identify the toolbar.
actionBarDataObject ArrayAn array of toolbar objects that contains data to represent toolbar items.
actionBarData[].nameStringThe name of the toolbar item.
actionBarData[].enabledBooleanWhen set to false the item will appear but does not respond to user interaction.
actionBarData[].showCaptionBooleanIndicates whether to show the caption of the toolbar item. Values are true and false.
actionBarData[].captionStringThe caption of the toolbar item.
actionBarData[].eventStringThe name of the event that the portlet fires when the toolbar item is pressed.
actionBarData[].showIconBooleanIndicates whether to show the icon of the toolbar item. Values are true and false.
actionBarData[].iconStringThe icon of the toolbar item.
actionBarData[].checkableBooleanindicates whether the toolbar item can be toggled. Values are true and false.
actionBarData[].selectedBooleanIf the toolbar item is checkable, then this indicates item's selected state.
actionBarData[].showDownArrowBooleanIf the toolbar item contains children, this indicates whether a scroll arrow should be used when the child items cannot fit on the screen.
actionBarData[].itemListObject ArrayAn array of objects that defines child toolbar items. The structure is the same as actionBarData.
actionBarData[].separatorBooleanIndicates whether this toolbar item is merely a separator and to ignore all other properties. Values are true and false.

Example

JS
PortalAPI.registerToolBar("_mnuToolBar", [{"tooltip":"Add Contact", "caption":"", "showIcon":"true", "showCaption":"true", "event":"addEntity", "name":"mitAddEntity0", "icon":"../icons/24/businessman_add.png", "selected":"true", "value":["selectMenuItem", "_mnuToolbar", "0"]}, {"itemList":[{"value":["selectMenuItem", "_mnuToolbar", "4 0"], "caption":"Account Administration", "showIcon":"true", "showCaption":"true", "event":"addToDoItem", "name":"mitTaskTemplate0", "icon":"../icons/16/pencil.png", "selected":"true"}, {"value":["selectMenuItem", "_mnuToolbar", "4 1"], "caption":"Discuss Policy Change", "showIcon":"true", "showCaption":"true", "event":"addToDoItem", "name":"mitTaskTemplate1", "icon":"../icons/16/telephone.png"}], "tooltip":"Add Task", "showIcon":"true", "icon":"../icons/24/task.png", "event":"addToDoItem", "name":"mitAddTask", "showDownArrow":"true"}])

Registers a toolbar called _mnuToolBar, which consists of two actionBarData objects.

The first object is a button called Add Contact. Clicking this button fires the addEntity event.

The second object is a button called Add Task, which includes two itemList objects. Clicking this button fires the addToDoItem event. Clicking the arrow beside the button displays a menu of child items. The first object is called Account Administration. The second object is called Discuss Policy Change.

PortalAPI.setContext

Obtains the value of a context variable from the workspace in which the calling portlet resides. The context value is returned asynchronously through a callback method.

Info

Retrieve context values using PortalAPI.getContext.

Syntax

PortalAPI.getContext(sVarName, callback)

PortalAPI.setContext parameters

ParameterValueDescription
sVarNameStringThe name of the context variable to retrieve. Can be null to return all context values.
callbackFunctionA callback function that accepts one argument. When the server responds, the callback is invoked with the context value passed as the argument if the context variable name is specified. If the context variable name is null, then the argument is a map of context key-values.

Related links

PortalAPI.getContext

PortalAPI.setBusy

Notifies the portal container that the calling portlet is busy.

While a portlet is busy, all incoming events will be shelved. When the portlet is visible and in a ready state by calling PortalAPI.setBusy(false), all shelved events will be propagated to the portlet's event handler.

The initial state of a portlet is always busy. If the portlet group's loadNotificationType is1, the portlet must call PortalAPI.setBusy(false) to notify the portal container that it is initialized. If the portal container is never notified, then the portlet is forever in a busy state.

Syntax

PortalAPI.setBusy(bBusy)

PortalAPI.setBusy parameters

ParameterValueDescription
bBusyBooleanIndicates whether to notify the portal container that the calling portlet is busy. Values are true and false. If the value is false, the portal container is notified that the calling portlet is in a ready state.

Related links

PortalAPI.isSessionPersisted

PortalAPI.setGlobalProperty

Obtains a list of all global properties and their values that are used by the container. The global properties are returned asynchronously through a callback method.

Info

Retrieve all global property values using PortalAPI.getAllGlobalProperties. Retrieving one global property value using PortalAPI.getGlobalProperty.

Syntax

PortalAPI.getAllGlobalProperties(callback)

PortalAPI.setGlobalProperty parameters

ParameterValueDescription
callbackFunctionA callback function that accepts one map argument. When the server responds, the callback is invoked with the global properties map passed as the argument. The key-value pair of the map is the name of the global property and its associated value.

Related links

PortalAPI.getAllGlobalProperties
PortalAPI.getGlobalProperty

PortalAPI.setPortalBeaconCaption

Sets the displayed caption of a notification beacon, which appears on the portal container toolbar.

Syntax

PortalAPI.setPortalBeaconCaption(sId, sCaption)

PortalAPI.setPortalBeaconCaption parameters

ParameterValueDescription
sIdStringThe unique identifier of the notification beacon.
sCaptionStringThe new caption to set.

PortalAPI.setPortalBeaconIcon

Sets the displayed icon of a notification beacon, which appears on the portal container toolbar.

Syntax

PortalAPI.setPortalBeaconIcon(sId, sIcon, bPrependBaseURL)

PortalAPI.setPortalBeaconIcon parameters

ParameterValueDescription
sIdStringThe unique identifier of the notification beacon.
sIconStringThe URL of the icon to display. If bPrependBaseURL is false, then the URL must be absolute.
bPrependBaseURLBooleanIndicates whether to prepend the icon URL with the calling portlet's group base URL. Values are true and false. If the value is false, the icon URL is expected to be an absolute URL.

PortalAPI.setPortalBeaconRemoteMethod

Sets the SOA method to invoke when the specified notification beacon should update its value.

Syntax

PortalAPI.setPortalBeaconRemoteMethod(sId, sRemoteMethod)

PortalAPI.setPortalBeaconRemoteMethod parameters

ParameterValueDescription
sIdStringThe unique identifier of the notification beacon that will invoke the specified method.
sRemoteMethodStringThe name of the SOA method.

PortalAPI.setPortalBeaconVisibility

Hides a notification beacon.

Syntax

PortalAPI.setPortalBeaconVisibility(sId, bVisible)

PortalAPI.setPortalBeaconVisibility parameters

ParameterValueDescription
sIdStringThe unique identifier of the notification beacon to hide.
bVisibleBooleanIndicates whether the notification beacon should be visible. Values are true and false. Specify false to hide the notification beacon.

PortalAPI.setPortalToastEnabled

Enables the toast control in the portal container. The control is used to display toast notifications.

Syntax

PortalAPI.setPortalToastEnabled(bEnabled)

PortalAPI.setPortalToastEnabled parameters

ParameterValueDescription
bEnabledBooleanIndicates whether to enable the control that displays toast notifications. Values are true and false.

PortalAPI.setPersistentSessionTimeoutPeriod

Sets the timeout period of the portlet.

Syntax

PortalAPI.setPersistentSessionTimeoutPeriod(period)

PortalAPI.setPersistentSessionTimeoutPeriod parameters

ParameterValueDescription
periodNumberThe timeout period in milliseconds.

PortalAPI.setPortalSize

Sets the dimensions of the portlet in the portal container.

Syntax

PortalAPI.setPortalSize(sName, sHeight, sWidth)

PortalAPI.setPortalSize parameters

ParameterValueDescription
sNameStringThe name of the portlet reference. If null, then the dimensions will be applied on the calling portlet.
sHeightStringThe height of the portlet to set. The height can include units: px or pt. If null, then the height will not be changed.
sWidthStringThe width of the portlet to set. The width can include units: px or pt. If null, then the width will not be changed.

Related links

PortalAPI.isSessionPersisted

PortalAPI.setSideBarVisibility

Sets the visibility of a sidebar portlet.

Syntax

PortalAPI.setSideBarVisibility(sSide, bVisible)

PortalAPI.setSideBarVisibility parameters

ParameterValueDescription
sSideStringThe sidebar to change its visibility. Value should be LEFT or RIGHT.
bVisibleBooleanIndicates whether this sidebar should be visible. Values are true and false.

PortalAPI.setWorkspaceCaption

Sets the caption of the workspace tab in which the portlet resides.

Syntax

PortalAPI.setWorkspaceCaption(sCaption)

PortalAPI.setWorkspaceCaption parameters

ParameterValueDescription
sCaptionStringThe workspace tab caption.


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.