Developing a JavaScript custom action

When invoked, a JavaScript object definition is included in a web UI view definition to place it on the screen. A JavaScript custom action can be on a detail view, a collection view, a home page, a menu bar or in navigation tree

Lifecycle of a JavaScript custom action

JavaScript custom action object

A JavaScript custom action object must provide an object with the following member functions.

init(initializationParameters, context)

initializationParameters

A map of the initialization parameter name to value. If no parameters are defined in the configuration, this parameter will be null

context

A CustomActionContext object which contains details of where the custom action is located as well as data from the page. For a collection view, the items will be all entities displayed on the page at the time. For a detail view the items will be the bsrUri of the entity shown. For menu bar, home page, and navigation tree the items will be empty.

The function should return true if the custom action should be visible. The function should return false if the custom action should be hidden.

For a detail view, collection view, home page panel, or navigation tree the custom action are not displayed if hidden. For the menu bar the custom action will be disabled.

execute(context)

context is a CustomActionContext object. For a collection view the items will all be entities which are selected and displayed on the page at the time. For a detail view there will be a single item, the bsrUri of the entity shown. For menu bar, home page, and navigation tree the items will be empty.

execute does not need to return anything.

Here is a sample object definition.

function MyButton() {
	this.init = function(initParameters, context) {
	}
	
	this.execute = function(context) {
	}
}

CustomActionContext object

The CustomActionContext object has the following member variables.

items

An array of strings, each string is the bsrUri of a registry entity.

source

A string corresponding to the location of where the custom action is run. One of the following.

• serviceregistry.SOURCE_HOME_PAGE
• serviceregistry.SOURCE_NAVIGATION_TREE
• serviceregistry.SOURCE_MENU_BAR
• serviceregistry.SOURCE_DETAIL_VIEW
• serviceregistry.SOURCE_COLLECTION_VIEW

JavaScript functions

A number of JavaScript functions are provided. These are all in the global serviceregistry object which is available to JavaScript custom actions.

serviceregistry.displayMessage(message, type)

This function displays a message in the messages area at the top of the page.

message

A string message to be displayed.

type

The type of message; informational, error or warning. This must be one of the following.

• serviceregistry.MESSAGE_TYPE_INFORMATIONAL
• serviceregistry.MESSAGE_TYPE_WARNING
• serviceregistry.MESSAGE_TYPE_ERROR

serviceregistry.clearMessages()

This function clears the messages area.

serviceregistry.deselectAll()

This function deselects all entities on a collection view. The call will be ignored if the view is anything other than a collection view.

serviceregistry.formatMessage(messageKey, bundleName, insert0, insert1, insert2…)

This function formats the message using the specified key, bundle and optional inserts. It returns a string message. Messages and bundles specified must have been defined in the configuration for the custom action.

Any number of inserts can be specified, or none.

If a message bundle name or message key is specified which was not made available in the web UI view configuration, the function will throw an error message string indicating which was not found.

messageKey

A string defining the key of the message to use.

bundleName

A string defining the fully-qualified name of the bundle to use.

insert0

A string defining the first insert. The first occurrence of “{0}” found in the message will be replaced by this value.

insert1

A string with the second insert.

serviceregistry.startBusy(customActionObject)

This starts a busy indicator on the cursor and disables the link or button which started the custom action.. Typically used when a task is started which will take greater than a few seconds.

customActionObject

The custom action object the call is made from. Typical usage would be startBusy(this);

serviceregistry.stopBusy(customActionObject)

This stops the busy indicator on the cursor and re-enables the link or button which started the custom action. Typically used once the custom action is finished processing.

customActionObject

The custom action object the call is made from. Typical usage would be stopBusy(this);

serviceregistry.getUserName()

This function returns the name of the current user.

serviceregistry.navigation.reloadCurrentPage()

This function reloads the current page. This is typically used when changes have been made on the server which will affect the currently displayed entity or entities.

The current page in the web browser history will be replaced by the new page.

serviceregistry.navigation.showDetail(bsrUri, tabName)

This function navigates to the detail view.

bsrUri

The Bsr Uri of the entity to show on the detail view.

tabName

The tabName parameter is the value of the tab-name attribute on the tab definition in the detail view definition which will be used to display the entity specified. In the case of the WSRR default detail view definitions, use a value from one of the following.

• serviceregistry.TAB_DETAILS
• serviceregistry.TAB_CONTENT
• serviceregistry.TAB_IMPACT_ANALYSIS
• serviceregistry.TAB_GOVERNANCE
• serviceregistry.TAB_POLICY

In the case of a custom detail view definition, specify a valid tab name by referring to the detail view definition file.

The tabName parameter is optional, the default is the details view (serviceregistry.TAB_DETAILS).

serviceregistry.navigation.previousPage()

This function navigates to the previous page in the breadcrumb trail. If no previous page exists, it will navigate to the home page.

serviceregistry.navigation.viewQuery (viewQueryName)

This function will run the specified view query and show the results. It is equivalent to the user clicking on the view query from the home page, navigation tree or menu bar.

viewQueryName

The name of a view query defined in a loaded view query definition file.

serviceregistry.navigation.homePage

This function navigates to the home page

Usage notes

Custom actions should be short running and not contain any long running tasks.

The Dojo libraries are available on all pages. Use Dojo functions wherever possible. The version of Dojo available on the web UI pages is 1.3.2..

Any custom actions placed in the navigation tree or menu bar will have their init() methods called for every page in the UI so their initialization code should be as efficient to execute as possible.

For development use external JS files, because the code can be changed without needing to reload view definitions.

Define js-messages for every custom action definition on the page, even if there will be duplicates. Do not include the whole message bundle, unless the bundle is small.

You cannot show messages on a page you navigate to.

Keep custom variables as member variables in a custom action object. Do not use global variables.

Keep custom action object names unique across the registry. On a given page, the menu bar, navigation tree and a view can be shown. The view can be a detail view, collection view, or the home page. In these circumstances the custom action object names defined in the menu bar, navigation tree, and displayed view must be unique and not duplicated. If a duplicate custom action object definition is used, the object which is instantiated is dependant upon the web browser JavaScript implementation, and is not predictable. Therefore undesired behavior might be encountered, for example a custom action defined on a detail view could use the custom action object definition in the menu bar. By keeping custom action object names unique, this undesirable behavior is avoided.

The same custom action object definition can be reused in multiple places. In this circumstance,define the object in one separate JavaScript file and include this file in any custom actions which use the object definition, using the <js-file> element.

Do not manipulate the Document Object Model (DOM) structure of web UI pages. This might cause the web UI pages functionality to stop working and is not supported.

Custom actions are displayed as buttons and links but will be initially non-visible on the page. After the init method has run for a custom action, its button or link will be made visible. Therefore if many custom actions are defined on a page, they are displayed in sequence.