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
| Parameter | Value | Description |
|---|---|---|
| bPrependBaseURL | Boolean | Indicates 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. |
| messagesArray | Object Array | An array of toast messages. Each message is an object with the following parameters: |
| messagesArray[].icon | String | The icon URL. (Optional) |
| messagesArray[].text | String | The HTML markup to display in the toast message. |
| messagesArray[].event | String | The name of the event to fire when the user clicks on toast message. (Optional) |
| messagesArray[].params | Object | The parameters associated with the event when the user clicks on toast message. (Optional) |
Example
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:
<script id="NexJ-Portal-API" src="http://portalserver/portal/portal-api-1.0.js">
Syntax
PortalAPI.addTrustedHost(sHost)
PortalAPI.addTrustedHost parameters
| Parameter | Value | Description |
|---|---|---|
| sHost | String | The name of the host. |
PortalAPI.broadcastEvent
Broadcasts an event to other portlets.
Syntax
PortalAPI.broadcastEvent(sName, parameter)
PortalAPI.broadcastEvent parameters
| Parameter | Value | Description |
|---|---|---|
| sName | String | The name of the event. |
| parameter | Object | The 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.
Related links
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
| Parameter | Value | Description |
|---|---|---|
| sName | String | The name of the event. |
| parameter | Object | The parameter of the event. |
Example
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.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
| Parameter | Value | Description |
|---|---|---|
| callback | Function | A 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.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
| Parameter | Value | Description |
|---|---|---|
| sVarName | String | The name of the context variable to retrieve. Can be null to return all context values. |
| callback | Function | A 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.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
| Parameter | Value | Description |
|---|---|---|
| sPropName | String | The name of the property. |
| callback | Function | A 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.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
| Parameter | Value | Description |
|---|---|---|
| callback | Function | A 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
| Parameter | Value | Description |
|---|---|---|
| callback | Function | A 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
| Parameter | Value | Description |
|---|---|---|
| viewPathArray | String Array | An 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. |
| newContextMap | Map | A 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. |
| eventInfoMap | Object | The event to fire on the destination portlet after a successful navigation. Can be null. |
| eventInfoMap.name | String | The name of the event. |
| eventInfoMap.param | Object | The parameter of the event. |
| fallbackViewPathsArray | Object Array | An 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
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
| Parameter | Value | Description |
|---|---|---|
| sExpirationMessage | String | A message to display to the user. |
| bLogoutContainer | Boolean | Indicates 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
| Parameter | Value | Description |
|---|---|---|
| sPortletLayoutRefName | String | The name of the portlet layout reference, identifying the zone to load the application perspective. |
| sWorkspaceTemplateName | String | The name of the application perspective. |
| sCaption | String | The caption of the application prespective. |
| sIcon | String | The URL of application prespective icon. If empty no icon will be displayed. |
| configs | Array | A list of application configuration data (application configuration ID, caption, and icon). |
| configs[].configId | String | ID of the configuration. |
| configs[].caption | String | Caption of the application configuration. |
| configs[].icon | String | The 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
PortalAPI.openWorkspace(sWorkspaceTemplateName, sCaption, sIcon, sCtxtVarName, ctxtVal, wkspContext, argArray)
PortalAPI.openWorkspace parameters
| Parameter | Value | Description |
|---|---|---|
| sWorkspaceTemplateName | String | The name of the workspace template to use when opening a new workspace. Can be null if a context variable name and value are specified. |
| sCaption | String | If a new workspace tab is created, then the workspace tab will use this caption. |
| sIcon | String | The absolute URL of the workspace tab's icon. If null, no icon is shown. |
| sCtxtVarName | String | The name of the context variable. Can be null if a workspace template name is specified. |
| ctxtVal | String | The context value. Can be null if workspace template name is specified. |
| wkspContext | String | A context map for initializing the workspace. |
| argArray | String | A 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
| Parameter | Value | Description |
|---|---|---|
| screenNameArray | String Array | An 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
| Parameter | Value | Description |
|---|---|---|
| screenNameArray | String Array | An 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
| Parameter | Value | Description |
|---|---|---|
| sName | String | A name to identify the toolbar. |
| actionBarData | Object Array | An array of toolbar objects that contains data to represent toolbar items. |
| actionBarData[].name | String | The name of the toolbar item. |
| actionBarData[].enabled | Boolean | When set to false the item will appear but does not respond to user interaction. |
| actionBarData[].showCaption | Boolean | Indicates whether to show the caption of the toolbar item. Values are true and false. |
| actionBarData[].caption | String | The caption of the toolbar item. |
| actionBarData[].event | String | The name of the event that the portlet fires when the toolbar item is pressed. |
| actionBarData[].showIcon | Boolean | Indicates whether to show the icon of the toolbar item. Values are true and false. |
| actionBarData[].icon | String | The icon of the toolbar item. |
| actionBarData[].checkable | Boolean | indicates whether the toolbar item can be toggled. Values are true and false. |
| actionBarData[].selected | Boolean | If the toolbar item is checkable, then this indicates item's selected state. |
| actionBarData[].showDownArrow | Boolean | If the toolbar item contains children, this indicates whether a scroll arrow should be used when the child items cannot fit on the screen. |
| actionBarData[].itemList | Object Array | An array of objects that defines child toolbar items. The structure is the same as actionBarData. |
| actionBarData[].separator | Boolean | Indicates whether this toolbar item is merely a separator and to ignore all other properties. Values are true and false. |
Example
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
| Parameter | Value | Description |
|---|---|---|
| sVarName | String | The name of the context variable to retrieve. Can be null to return all context values. |
| callback | Function | A 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.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
| Parameter | Value | Description |
|---|---|---|
| bBusy | Boolean | Indicates 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.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
| Parameter | Value | Description |
|---|---|---|
| callback | Function | A 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
| Parameter | Value | Description |
|---|---|---|
| sId | String | The unique identifier of the notification beacon. |
| sCaption | String | The 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
| Parameter | Value | Description |
|---|---|---|
| sId | String | The unique identifier of the notification beacon. |
| sIcon | String | The URL of the icon to display. If bPrependBaseURL is false, then the URL must be absolute. |
| bPrependBaseURL | Boolean | Indicates 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
| Parameter | Value | Description |
|---|---|---|
| sId | String | The unique identifier of the notification beacon that will invoke the specified method. |
| sRemoteMethod | String | The name of the SOA method. |
PortalAPI.setPortalBeaconVisibility
Hides a notification beacon.
Syntax
PortalAPI.setPortalBeaconVisibility(sId, bVisible)
PortalAPI.setPortalBeaconVisibility parameters
| Parameter | Value | Description |
|---|---|---|
| sId | String | The unique identifier of the notification beacon to hide. |
| bVisible | Boolean | Indicates 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
| Parameter | Value | Description |
|---|---|---|
| bEnabled | Boolean | Indicates 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
| Parameter | Value | Description |
|---|---|---|
| period | Number | The 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
| Parameter | Value | Description |
|---|---|---|
| sName | String | The name of the portlet reference. If null, then the dimensions will be applied on the calling portlet. |
| sHeight | String | The height of the portlet to set. The height can include units: px or pt. If null, then the height will not be changed. |
| sWidth | String | The 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.setSideBarVisibility
Sets the visibility of a sidebar portlet.
Syntax
PortalAPI.setSideBarVisibility(sSide, bVisible)
PortalAPI.setSideBarVisibility parameters
| Parameter | Value | Description |
|---|---|---|
| sSide | String | The sidebar to change its visibility. Value should be LEFT or RIGHT. |
| bVisible | Boolean | Indicates 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
| Parameter | Value | Description |
|---|---|---|
| sCaption | String | The workspace tab caption. |