JavaScript API

In the custom JavaScript module introduced in the 2022 release, you can use the JavaScript API to implement custom functionality in PowerWeb. An example use case for using this API could be if you wanted to extend the PowerWeb user interface by adding external pages. In external pages, you have more freedom to develop customized functionality and user interfaces integrated with PowerWeb.

With this API, you can synchronize elements of the PowerWeb UI with actions the user is performing in your external page. For instance, with this functionality you can prevent a user from confirming a wizard before all required data is entered in the external page. For more information about external pages, see Configure External Pages.

In this article, we describe the functions and events that are available in the JavaScript API.

Note:

The instructions of this article about the context menu apply to Chrome and Edge in native mode, for which the context menu is built from the structure of the ribbon:

The first level of the context menu contains all ribbon names.
The second level contains all section names.
The third level contains all commands in the section, including commands in drop-down lists.

For Internet Explorer and Edge in IE mode, the context menu is built in the same way as in previous releases.

Functions

The following functions can be called in a custom JavaScript module. The Custom JavaScript API is stored in the window.top.document.customAPI object, so to apply these methods you should use this example:

var meridianDoc = window.top.document;

meridianDoc.customAPI.AddRibbon('NewRibbonTab', 'Project');

setCommandStatus

Sets the status of a command in both the ribbon and context menu.

Syntax

customAPI.setCommandStatus (cmdId, status)

Parameters
Name	Description
cmdId	The ID of the command
Status	Can be set to "Active", "Disabled", or "Hidden"

addRibbon

Adds an empty ribbon to the ribbon menu and a top-level item in the context menu. Returns node of the new tab.

Syntax

customAPI.addRibbon (displayNameRibbon, afterRibbonId)

Parameters
Name	Description
displayNameRibbon	The label of the ribbon
afterRibbonId	The name of the ribbon that comes before the ribbon created by this function.

addRibbonSection

Adds a section to a ribbon tab and a second-level item to the context menu. Returns node of the new section.

Syntax

customAPI.addRibbonSection (ribbonTabId, displayNameSection, afterSectionId)

Parameters
Name	Description
ribbonTabId	The ID of the ribbon the section is being added to
displayNameSection	The label of the section
afterSectionId	Enter the name of the section that should come before this section. Leave empty if the position is not important.

addRibbonCommand

Adds a command to a section in the ribbon and a command to the second-level item in the context menu. Returns node with added command.

Syntax

customAPI.addRibbonCommand (tabName, sectionName, displayName, afterCommandName, commandType, displayCommandId, pathIcon)

Parameters
Name	Description
tabName	The name of the ribbon tab where you want to add the command.
sectionName	The name of the section in the ribbon tab the command is being added to.
displayName	The name of the command.
afterCommandName	Enter null if the command will be the first command in the section or if its position is not important. Enter the ID of the previous command if the new command needs to be after another command.
commandType	Enter one of three values: 0 – Lookup list command This is a drop-down list that does not have a default command. 1 – Simple command 2 – Drop-down list with default command
displayCommandId	The command ID.
pathIcon	The path of the icon displayed next to the command.

addSubCommand

Adds a command to the drop-down menu of a command in the ribbon and context menu. Returns node with new command.

Syntax

customAPI.addSubCommand (afterCmdId, displayName, displayCmdId, pathIcon)

Parameters
Name	Description
afterCmdId	The name of the command that comes before this command in the drop-down menu.
displayName	The label of the command.
displayCmdId	ID of the new command.
pathIcon	The path of the icon displayed next to the command.

Enable or disable UI controls in PowerWeb

In some cases when your custom JavaScript displays a dialog, all PowerWeb user interface controls need to be disabled to prevent the user from unexpectedly executing another command, selecting another document, or changing the View, Scope, or Vault. There are two functions to support this use case:

customAPI.disableAllUIcontrols ()

Disables all user interface controls in PowerWeb.

customAPI.restoreAllUIcontrols ()

Restores the status of all user interface controls to their previous status.

Events

The following events can be used in a custom JavaScript module. For these events, use the following syntax:

<element>.addEventListener ("bc:<EventName>", function(event){});

ChangeEditMode

Occurs when the user clicks the Edit, OK, Apply, or Cancel buttons in the property page. You can cancel the command by using event.preventDefault() .

Syntax

<element>.addEventListener ("bc:ChangeEditMode", function(event){});

This event stores the following parameters in an event object:

Parameters
Name	Description
event.oid	Item ID of the current document
event.ButtonName	Button Name. Value can be set to “Edit”, “OK”, “Apply” or “Cancel”.

ChangeScope

Occurs when the user selects another scope.

Syntax

<element>.addEventListener ("bc:ChangeScope", function(event){});

This event stores the following parameters in an event object:

Parameters
Name	Description
event.ctxForCustomApi.scope	Name of the selected scope

Context

Occurs when the user selects another view, refreshes page, switches between vaults, and so on. This event is also fired for the changeView event.

The object event.ctxForCustomApi stores contextual data when an object is created. This means that you can refer to these parameters to get the corresponding values, as you can in the table see below.

Syntax

<element>.addEventListener ("bc:Context", function(event){});

This event stores the following parameters in an event object:

Parameters
Name	Description
event.ctxForCustomApi.view_displayname	Name of the selected view
event.ctxForCustomApi.view_oid	View OID
event.ctxForCustomApi.vault_displayname	Vault displayname
event.ctxForCustomApi.vault_oid	Vault OID
event.ctxForCustomApi.baseline_context	Baseline info
event.ctxForCustomApi.baseline_displayname	Baseline displayname

CommandSelected

Occurs when the user selects the command in the ribbon or context menu. You can cancel the command by using event.preventDefault() .

Syntax

<element>.addEventListener ("bc:CommandSelected", function(event){});

This event stores the following parameters in an event object:

Parameters
Name	Description
event.oid	Item ID of the current document or folder. If the command is applied to the search result, this value is null.
event.checkboxList	List of item IDs selected with a check box.
event.CommandName	Name of the command.

CommandSubmitted

Occurs when the command has been sent to the web server.

Syntax

<element>.addEventListener ("bc:CommandSubmitted", function(event){});

This event stores the following parameters in an event object:

Parameters
Name	Description
event.oid	Item ID of the current document or folder. If the command is applied to the search result, this value is null.
event.checkboxList	List of item IDs selected with a check box.
event.CommandName	Name of the command.

DeselectItem

Occurs when the user deselects the check box of an item in a list.

Syntax

<element>.addEventListener ("bc:DeselectItem", function(event){});

This event stores the following parameters in an event object:

Parameters
Name	Description
event.oid	Item ID of the current document

SelectItem

Occurs when the user selects an item in a list or selects the check box of an item in a list.

Syntax

<element>.addEventListener ("bc:SelectItem", function(event){});

This event stores the following parameters in an event object:

Parameters
Name	Description
event.oid	Item ID of the current document
event.checkboxClicked	Check box status (true or false)

SelectPane

Occurs when the user selects a pane.

Syntax

<element>.addEventListener ("bc:SelectPane", function(event){});

This event stores the following parameters in an event object:

Parameters
Name	Description
event.ctxForCustomApi.oid	Item ID of the current document
event.ctxForCustomApi.viewName	Name of the selected pane. Value can be set to “Properties”, “Rendition”, “Revisions”, “References” , “ProjectCopies“ or “Workflow”.

SelectTab

Occurs when the user selects a property tab.

Syntax

<element>.addEventListener ("bc:SelectTab", function(event){});

This event stores the following parameters in an event object:

Parameters
Name	Description
event.ctxForCustomApi.oid	Item ID of the current document
event.ctxForCustomApi.pageName	Name of the selected property tab.