blob: 893ab360f6c3ef009c394cb3ee1d4891c2b77453 [file] [log] [blame]
= 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
---------