542096e72c
Also update `self.url` documentation to reflect the changes.
This reverts commit 964455ae6f.
Reason for revert: moving forward as misuse of plugin._url is fixed
Bug: Issue 11998
Change-Id: I8c4d888dae3e8df0f15ad210c4f40ac9704d5b37
487 lines
12 KiB
Plaintext
487 lines
12 KiB
Plaintext
= 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
|
|
---------
|