Documentation/js-api.txt

= Gerrit Code Review - JavaScript API

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:

[source,javascript]
----
Gerrit.install(function (self) {
  // ... plugin JavaScript code here ...
});
----


[[self]]
== 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]]
=== self.getServerInfo()
Returns the server's link:rest-api-config.html#server-info[ServerInfo]
data.

[[self_getPluginName]]
=== 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]]
=== self.on()
Register a JavaScript callback to be invoked when events occur within
the web interface.

.Signature
[source,javascript]
----
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
  link:rest-api-changes.html#change-info[ChangeInfo] and
  link:rest-api-changes.html#revision-info[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 link:rest-api-changes.html#change-info[ChangeInfo]
  and link:rest-api-changes.html#revision-info[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]]
=== self.changeActions()
Returns an instance of ChangeActions API.

.Signature
[source,javascript]
----
self.changeActions();
----

[[self_screen]]
=== 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 link:dev-plugins.html#top-menu-extensions[top menu].

.Signature
[source,javascript]
----
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 link:#ScreenContext[screen context].

[[self_settings]]
=== self.settings()
Returns the Settings API.

.Signature
[source,javascript]
----
self.settings();
----

[[self_registerCustomComponent]]
=== self.registerCustomComponent()
Register a custom component to a specific endpoint.

.Signature
[source,javascript]
----
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]]
=== 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.

[source,javascript]
----
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]]
=== self.restApi()
Returns an instance of the Plugin REST API.

.Signature
[source,javascript]
----
self.restApi(prefix_url)
----

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

[[PluginRestAPI]]
== Plugin Rest API

[[plugin_rest_delete]]
=== restApi.delete()
Issues a DELETE REST API request to the Gerrit server.
Returns a promise with the response of the request.

.Signature
[source,javascript]
----
restApi.delete(url)
----

* url: URL relative to the base url.

[[plugin_rest_get]]
=== restApi.get()
Issues a GET REST API request to the Gerrit server.
Returns a promise with the response of the request.

.Signature
[source,javascript]
----
restApi.get(url)
----

* url: URL relative to the base url.

[[plugin_rest_post]]
=== restApi.post()
Issues a POST REST API request to the Gerrit server.
Returns a promise with the response of the request.

.Signature
[source,javascript]
----
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.

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

[[plugin_rest_put]]
=== restApi.put()
Issues a PUT REST API request to the Gerrit server.
Returns a promise with the response of the request.

.Signature
[source,javascript]
----
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.

[source,javascript]
----
restApi.put(
  '/builds',
  {start_build: true, platform_type: 'Linux'});
----

[[ChangeActions]]
== Change Actions API
A new Change Actions API instance will be created when `changeActions()`
is invoked.

[[change_actions_add]]
=== changeActions.add()
Adds a new action to the change actions section.
Returns the key of the newly added action.

.Signature
[source,javascript]
----
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.

[source,javascript]
----
changeActions.add("change", "test")
----

[[change_actions_remove]]
=== changeActions.remove()
Removes an action from the change actions section.

.Signature
[source,javascript]
----
changeActions.remove(key)
----

* key: The key of the action.

[[change_actions_addTapListener]]
=== changeActions.addTapListener()
Adds a tap listener to an action that will be invoked when the action
is tapped.

.Signature
[source,javascript]
----
changeActions.addTapListener(key, callback)
----

* key: The key of the action.

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

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

[[change_actions_removeTapListener]]
=== changeActions.removeTapListener()
Removes an existing tap listener on an action.

.Signature
[source,javascript]
----
changeActions.removeTapListener(key, callback)
----

* key: The key of the action.

* callback: JavaScript function to be removed.

[[change_actions_setLabel]]
=== changeActions.setLabel()
Sets the label for an action.

.Signature
[source,javascript]
----
changeActions.setLabel(key, label)
----

* key: The key of the action.

* label: The label of the action.

[[change_actions_setTitle]]
=== changeActions.setTitle()
Sets the title for an action.

.Signature
[source,javascript]
----
changeActions.setTitle(key, title)
----

* key: The key of the action.

* title: The title of the action.

[[change_actions_setIcon]]
=== changeActions.setIcon()
Sets an icon for an action.

.Signature
[source,javascript]
----
changeActions.setIcon(key, icon)
----

* key: The key of the action.

* icon: The name of the icon.

[[change_actions_setEnabled]]
=== changeActions.setEnabled()
Sets an action to enabled or disabled.

.Signature
[source,javascript]
----
changeActions.setEnabled(key, enabled)
----

* key: The key of the action.

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

[[change_actions_setActionHidden]]
=== changeActions.setActionHidden()
Sets an action to be hidden.

.Signature
[source,javascript]
----
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.

[[change_actions_setActionOverflow]]
=== changeActions.setActionOverflow()
Sets an action to show in overflow menu.

.Signature
[source,javascript]
----
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.

[[PanelContext]]
== 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]]
=== panel.body
Empty HTML `<div>` node the plugin should add the panel content to.
The node is already attached to the document.

[[PanelProperties]]
=== Properties

The extension panel parameters that are described in the
link:dev-plugins.html#panels[plugin development documentation] are
contained in the context as properties. Which properties are available
depends on the extension point.

[[Gerrit]]
== 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]]
=== Gerrit.css()
[WARNING]
This method is deprecated. It doesn't work with Shadow DOM and
will be removed in the future. Please, use link:pg-plugin-dev.html#plugin-styles[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
[source,javascript]
----
Gerrit.install(function(self)) {
  var style = {
    name: Gerrit.css('background: #fff; color: #000;'),
  };
});
----

[[Gerrit_install]]
=== Gerrit.install()
Registers a new plugin by invoking the supplied initialization
function. The function is passed the link:#self[plugin instance].

[source,javascript]
----
Gerrit.install(function (self) {
  // ... plugin JavaScript code here ...
});
----

GERRIT
------
Part of link:index.html[Gerrit Code Review]

SEARCHBOX
---------