Gerrit Code Review supports an API for JavaScript plugins to interact with the web UI and the server process.

Entry Point

JavaScript is loaded using a standard <script src='…​'> HTML tag. Plugins should protect the global namespace by defining their code within an anonymous function passed to Gerrit.install(). The plugin will be passed an object describing its registration with Gerrit:

Gerrit.install(function (self) {
  // ... plugin JavaScript code here ...
});

Plugin Instance

The plugin instance is passed to the plugin’s initialization function and provides a number of utility services to plugin authors.

self.getServerInfo()

Returns the server’s ServerInfo data.

self.getPluginName()

Returns the name this plugin was installed as by the server administrator. The plugin name is required to access REST API views installed by the plugin, or to access resources.

self.on()

Register a JavaScript callback to be invoked when events occur within the web interface.

Signature
self.on(event, callback);

  • event: A supported event type. See below for description.

  • callback: JavaScript function to be invoked when event happens. Arguments may be passed to this function, depending on the event.

Supported events:

  • history: Invoked when the view is changed to a new screen within the Gerrit web application. The token after "#" is passed as the argument to the callback function, for example "/c/42/" while showing change 42.

  • showchange: Invoked when a change is made visible. A ChangeInfo and RevisionInfo are passed as arguments. PolyGerrit provides a third parameter which is an object with a mergeable boolean.

  • submitchange: Invoked when the submit button is clicked on a change. A ChangeInfo and RevisionInfo are passed as arguments. Similar to a form submit validation, the function must return true to allow the operation to continue, or false to prevent it. The function may be called multiple times, for example, if submitting a change shows a confirmation dialog, this event may be called to validate that the check whether dialog can be shown, and called again when the submit is confirmed to check whether the actual submission action can proceed.

  • comment: Invoked when a DOM element that represents a comment is created. This DOM element is passed as argument. This DOM element contains nested elements that Gerrit uses to format the comment. The DOM structure may differ between comment types such as inline comments, file-level comments and summary comments, and it may change with new Gerrit versions.

  • highlightjs-loaded: Invoked when the highlight.js library has finished loading. The global hljs object (also now accessible via window.hljs) is passed as an argument to the callback function. This event can be used to register a new language highlighter with the highlight.js library before syntax highlighting begins.

self.changeActions()

Returns an instance of ChangeActions API.

Signature
self.changeActions();

self.screen()

Register a module to be attached when the user navigates to an extension screen provided by the plugin. Extension screens are usually linked from the top menu.

Signature
self.screen(pattern, opt_moduleName);

  • pattern: URL token pattern to identify the screen. Argument can be either a string ('index') or a RegExp object (/list\/(.*)/). If a RegExp is used the matching groups will be available inside of the context as token_match.

  • opt_moduleName: The module to load when the user navigates to the screen. The function will be passed a screen context.

self.settings()

Returns the Settings API.

Signature
self.settings();

self.registerCustomComponent()

Register a custom component to a specific endpoint.

Signature
self.registerCustomComponent(endpointName, opt_moduleName, opt_options);

  • endpointName: The endpoint this plugin should be reigistered to.

  • opt_moduleName: The module name the custom component will use.

  • opt_options: Options to register this custom component.

self.url()

Returns a URL within the plugin’s URL space. If invoked with no parameter the URL of the plugin is returned. If passed a string the argument is appended to the plugin URL.

A plugin’s URL is where this plugin is loaded, it doesn’t necessary to be the same as the Gerrit host. Use window.location if you need to access the Gerrit host info.

For preloaded plugins, the plugin url is based on a global configuration of where to load all plugins, default to current host.

self.url();                    // "https://gerrit-review.googlesource.com/plugins/demo/"
self.url('/static/icon.png');  // "https://gerrit-review.googlesource.com/plugins/demo/static/icon.png"

self.restApi()

Returns an instance of the Plugin REST API.

Signature
self.restApi(prefix_url)

  • prefix_url: Base url for subsequent .get(), .post() etc requests.

Plugin Rest API

restApi.delete()

Issues a DELETE REST API request to the Gerrit server. Returns a promise with the response of the request.

Signature
restApi.delete(url)

  • url: URL relative to the base url.

restApi.get()

Issues a GET REST API request to the Gerrit server. Returns a promise with the response of the request.

Signature
restApi.get(url)

  • url: URL relative to the base url.

restApi.post()

Issues a POST REST API request to the Gerrit server. Returns a promise with the response of the request.

Signature
restApi.post(url, opt_payload, opt_errFn, opt_contentType)

  • url: URL relative to the base url.

  • opt_payload: JavaScript object to serialize as the request payload.

  • opt_errFn: JavaScript function to be invoked when error occured.

  • opt_contentType: Content-Type to be sent along with the request.

restApi.post(
  '/my-servlet',
  {start_build: true, platform_type: 'Linux'});

restApi.put()

Issues a PUT REST API request to the Gerrit server. Returns a promise with the response of the request.

Signature
restApi.put(url, opt_payload, opt_errFn, opt_contentType)

  • url: URL relative to the base url.

  • opt_payload: JavaScript object to serialize as the request payload.

  • opt_errFn: JavaScript function to be invoked when error occured.

  • opt_contentType: Content-Type to be sent along with the request.

restApi.put(
  '/builds',
  {start_build: true, platform_type: 'Linux'});

Change Actions API

A new Change Actions API instance will be created when changeActions() is invoked.

changeActions.add()

Adds a new action to the change actions section. Returns the key of the newly added action.

Signature
changeActions.add(type, label)

  • type: The type of the action, either change or revision.

  • label: The label to be used in UI for this action.

changeActions.add("change", "test")

changeActions.remove()

Removes an action from the change actions section.

Signature
changeActions.remove(key)

  • key: The key of the action.

changeActions.addTapListener()

Adds a tap listener to an action that will be invoked when the action is tapped.

Signature
changeActions.addTapListener(key, callback)

  • key: The key of the action.

  • callback: JavaScript function to be invoked when action tapped.

changeActions.addTapListener("__key_for_my_action__", () => {
  // do something when my action gets clicked
})

changeActions.removeTapListener()

Removes an existing tap listener on an action.

Signature
changeActions.removeTapListener(key, callback)

  • key: The key of the action.

  • callback: JavaScript function to be removed.

changeActions.setLabel()

Sets the label for an action.

Signature
changeActions.setLabel(key, label)

  • key: The key of the action.

  • label: The label of the action.

changeActions.setTitle()

Sets the title for an action.

Signature
changeActions.setTitle(key, title)

  • key: The key of the action.

  • title: The title of the action.

changeActions.setIcon()

Sets an icon for an action.

Signature
changeActions.setIcon(key, icon)

  • key: The key of the action.

  • icon: The name of the icon.

changeActions.setEnabled()

Sets an action to enabled or disabled.

Signature
changeActions.setEnabled(key, enabled)

  • key: The key of the action.

  • enabled: The status of the action, true to enable.

changeActions.setActionHidden()

Sets an action to be hidden.

Signature
changeActions.setActionHidden(type, key, hidden)

  • type: The type of the action.

  • key: The key of the action.

  • hidden: True to hide the action, false to show the action.

changeActions.setActionOverflow()

Sets an action to show in overflow menu.

Signature
changeActions.setActionOverflow(type, key, overflow)

  • type: The type of the action.

  • key: The key of the action.

  • overflow: True to move the action to overflow menu, false to move the action out of the overflow menu.

Panel Context

A new panel context is passed to the panel callback function each time a screen with the given extension point is loaded.

panel.body

Empty HTML <div> node the plugin should add the panel content to. The node is already attached to the document.

Properties

The extension panel parameters that are described in the plugin development documentation are contained in the context as properties. Which properties are available depends on the extension point.

Gerrit

The Gerrit object is the only symbol provided into the global namespace by Gerrit Code Review. All top-level functions can be accessed through this name.

Gerrit.css()

Warning
 This method is deprecated. It doesn’t work with Shadow DOM and will be removed in the future. Please, use plugin.styles instead.

Creates a new unique CSS class and injects it into the document. The name of the class is returned and can be used by the plugin.

Classes created with this function should be created once at install time and reused throughout the plugin. Repeatedly creating the same class will explode the global stylesheet.

Signature
Gerrit.install(function(self)) {
  var style = {
    name: Gerrit.css('background: #fff; color: #000;'),
  };
});

Gerrit.install()

Registers a new plugin by invoking the supplied initialization function. The function is passed the plugin instance.

Gerrit.install(function (self) {
  // ... plugin JavaScript code here ...
});

Part of Gerrit Code Review