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:

  1. The first level of the context menu contains all ribbon names.

  2. The second level contains all section names.

  3. 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.

ClosedFunctions

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');

ClosedsetCommandStatus

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"

ClosedaddRibbon

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.

ClosedaddRibbonSection

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.

ClosedaddRibbonCommand

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.

ClosedaddSubCommand

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.

ClosedEnable 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.

ClosedEvents

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

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

ClosedChangeEditMode

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”.

ClosedChangeScope

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

ClosedContext

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

ClosedCommandSelected

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.

ClosedCommandSubmitted

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.

ClosedDeselectItem

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

ClosedSelectItem

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)

ClosedSelectPane

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”.

ClosedSelectTab

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.

2023