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.
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)
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)
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)
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)
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:
|
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)
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:
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:
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:
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:
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:
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:
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:
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:
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:
Name | Description |
---|---|
event.ctxForCustomApi.oid | Item ID of the current document |
event.ctxForCustomApi.pageName | Name of the selected property tab. |