a1067a3b04
label() method appends label after passed element (useful for checkboxes). Add a new mathod to prepend label before element (useful for input fields). Update the JS API documentation. Change-Id: I839fc7d38eca55d351074d01ffb2758bb538903e
598 lines
16 KiB
Plaintext
598 lines
16 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:
|
|
|
|
----
|
|
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_delete]]
|
|
self.delete()
|
|
~~~~~~~~~~~~~
|
|
Issues a DELETE REST API request to the Gerrit server.
|
|
|
|
.Signature
|
|
----
|
|
Gerrit.delete(url, callback)
|
|
----
|
|
|
|
* url: URL relative to the plugin's URL space. The JavaScript
|
|
library prefixes the supplied URL with `/plugins/{getPluginName}/`.
|
|
|
|
* callback: JavaScript function to be invoked with the parsed
|
|
JSON result of the API call. DELETE methods often return
|
|
`204 No Content`, which is passed as null.
|
|
|
|
[[self_get]]
|
|
self.get()
|
|
~~~~~~~~~~
|
|
Issues a GET REST API request to the Gerrit server.
|
|
|
|
.Signature
|
|
----
|
|
self.get(url, callback)
|
|
----
|
|
|
|
* url: URL relative to the plugin's URL space. The JavaScript
|
|
library prefixes the supplied URL with `/plugins/{getPluginName}/`.
|
|
|
|
* callback: JavaScript function to be invoked with the parsed JSON
|
|
result of the API call. If the API returns a string the result is
|
|
a string, otherwise the result is a JavaScript object or array,
|
|
as described in the relevant REST API documentation.
|
|
|
|
[[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_post]]
|
|
self.post()
|
|
~~~~~~~~~~~
|
|
Issues a POST REST API request to the Gerrit server.
|
|
|
|
.Signature
|
|
----
|
|
self.post(url, input, callback)
|
|
----
|
|
|
|
* url: URL relative to the plugin's URL space. The JavaScript
|
|
library prefixes the supplied URL with `/plugins/{getPluginName}/`.
|
|
|
|
* input: JavaScript object to serialize as the request payload.
|
|
|
|
* callback: JavaScript function to be invoked with the parsed JSON
|
|
result of the API call. If the API returns a string the result is
|
|
a string, otherwise the result is a JavaScript object or array,
|
|
as described in the relevant REST API documentation.
|
|
|
|
----
|
|
self.post(
|
|
'/my-servlet',
|
|
{start_build: true, platform_type: 'Linux'},
|
|
function (r) {});
|
|
----
|
|
|
|
[[self_put]]
|
|
self.put()
|
|
~~~~~~~~~~
|
|
Issues a PUT REST API request to the Gerrit server.
|
|
|
|
.Signature
|
|
----
|
|
self.put(url, input, callback)
|
|
----
|
|
|
|
* url: URL relative to the plugin's URL space. The JavaScript
|
|
library prefixes the supplied URL with `/plugins/{getPluginName}/`.
|
|
|
|
* input: JavaScript object to serialize as the request payload.
|
|
|
|
* callback: JavaScript function to be invoked with the parsed JSON
|
|
result of the API call. If the API returns a string the result is
|
|
a string, otherwise the result is a JavaScript object or array,
|
|
as described in the relevant REST API documentation.
|
|
|
|
----
|
|
self.put(
|
|
'/builds',
|
|
{start_build: true, platform_type: 'Linux'},
|
|
function (r) {});
|
|
----
|
|
|
|
[[self_onAction]]
|
|
self.onAction()
|
|
~~~~~~~~~~~~~~~
|
|
Register a JavaScript callback to be invoked when the user clicks
|
|
on a button associated with a server side `UiAction`.
|
|
|
|
.Signature
|
|
----
|
|
Gerrit.onAction(type, view_name, callback);
|
|
----
|
|
|
|
* type: `'change'` or `'revision'`, indicating what sort of resource
|
|
the `UiAction` was bound to in the server.
|
|
|
|
* view_name: string appearing in URLs to name the view. This is the
|
|
second argument of the `get()`, `post()`, `put()`, and `delete()`
|
|
binding methods in a `RestApiModule`.
|
|
|
|
* callback: JavaScript function to invoke when the user clicks. The
|
|
function will be passed a link:#ActionContext[action context].
|
|
|
|
[[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.
|
|
|
|
----
|
|
self.url(); // "https://gerrit-review.googlesource.com/plugins/demo/"
|
|
self.url('/static/icon.png'); // "https://gerrit-review.googlesource.com/plugins/demo/static/icon.png"
|
|
----
|
|
|
|
|
|
[[ActionContext]]
|
|
Action Context
|
|
--------------
|
|
A new action context is passed to the `onAction` callback function
|
|
each time the associated action button is clicked by the user. A
|
|
context is initialized with sufficient state to issue the associated
|
|
REST API RPC.
|
|
|
|
[[context_action]]
|
|
context.action
|
|
~~~~~~~~~~~~~~
|
|
A link:rest-api-changes.html#action-info[ActionInfo] object instance
|
|
supplied by the server describing the UI button the user used to
|
|
invoke the action.
|
|
|
|
[[context_call]]
|
|
context.call()
|
|
~~~~~~~~~~~~~~
|
|
Issues the REST API call associated with the action. The HTTP method
|
|
used comes from `context.action.method`, hiding the JavaScript from
|
|
needing to care.
|
|
|
|
.Signature
|
|
----
|
|
context.call(input, callback)
|
|
----
|
|
|
|
* input: JavaScript object to serialize as the request payload. This
|
|
parameter is ignored for GET and DELETE methods.
|
|
|
|
* callback: JavaScript function to be invoked with the parsed JSON
|
|
result of the API call. If the API returns a string the result is
|
|
a string, otherwise the result is a JavaScript object or array,
|
|
as described in the relevant REST API documentation.
|
|
|
|
----
|
|
context.call(
|
|
{message: "..."},
|
|
function (result) {
|
|
// ... use result here ...
|
|
});
|
|
----
|
|
|
|
[[context_change]]
|
|
context.change
|
|
~~~~~~~~~~~~~~
|
|
When the action is invoked on a change a
|
|
link:rest-api-changes.html#change-info[ChangeInfo] object instance
|
|
describing the change. Available fields of the ChangeInfo may vary
|
|
based on the options used by the UI when it loaded the change.
|
|
|
|
[[context_delete]]
|
|
context.delete()
|
|
~~~~~~~~~~~~~~~~
|
|
Issues a DELETE REST API call to the URL associated with the action.
|
|
|
|
.Signature
|
|
----
|
|
context.delete(callback)
|
|
----
|
|
|
|
* callback: JavaScript function to be invoked with the parsed
|
|
JSON result of the API call. DELETE methods often return
|
|
`204 No Content`, which is passed as null.
|
|
|
|
----
|
|
context.delete(function () {});
|
|
----
|
|
|
|
[[context_get]]
|
|
context.get()
|
|
~~~~~~~~~~~~~
|
|
Issues a GET REST API call to the URL associated with the action.
|
|
|
|
.Signature
|
|
----
|
|
context.get(callback)
|
|
----
|
|
|
|
* callback: JavaScript function to be invoked with the parsed JSON
|
|
result of the API call. If the API returns a string the result is
|
|
a string, otherwise the result is a JavaScript object or array,
|
|
as described in the relevant REST API documentation.
|
|
|
|
----
|
|
context.get(function (result) {
|
|
// ... use result here ...
|
|
});
|
|
----
|
|
|
|
[[context_go]]
|
|
context.go()
|
|
~~~~~~~~~~~~
|
|
Go to a page. Shorthand for link:#Gerrit_go[`Gerrit.go()`].
|
|
|
|
[[context_hide]]
|
|
context.hide()
|
|
~~~~~~~~~~~~~~
|
|
Hide the currently visible popup displayed by
|
|
link:#context_popup[`context.popup()`].
|
|
|
|
[[context_post]]
|
|
context.post()
|
|
~~~~~~~~~~~~~~
|
|
Issues a POST REST API call to the URL associated with the action.
|
|
|
|
.Signature
|
|
----
|
|
context.post(input, callback)
|
|
----
|
|
|
|
* input: JavaScript object to serialize as the request payload.
|
|
|
|
* callback: JavaScript function to be invoked with the parsed JSON
|
|
result of the API call. If the API returns a string the result is
|
|
a string, otherwise the result is a JavaScript object or array,
|
|
as described in the relevant REST API documentation.
|
|
|
|
----
|
|
context.post(
|
|
{message: "..."},
|
|
function (result) {
|
|
// ... use result here ...
|
|
});
|
|
----
|
|
|
|
[[context_popup]]
|
|
context.popup()
|
|
~~~~~~~~~~~~~~~
|
|
|
|
Displays a small popup near the activation button to gather
|
|
additional input from the user before executing the REST API RPC.
|
|
|
|
The caller is always responsible for closing the popup with
|
|
link#context_hide[`context.hide()`]. Gerrit will handle closing a
|
|
popup if the user presses `Escape` while keyboard focus is within
|
|
the popup.
|
|
|
|
.Signature
|
|
----
|
|
context.popup(element)
|
|
----
|
|
|
|
* element: an HTML DOM element to display as the body of the
|
|
popup. This is typically a `div` element but can be any valid HTML
|
|
element. CSS can be used to style the element beyond the defaults.
|
|
|
|
A common usage is to gather more input:
|
|
----
|
|
self.onAction('revision', 'start-build', function (c) {
|
|
var l = c.checkbox();
|
|
var m = c.checkbox();
|
|
c.popup(c.div(
|
|
c.div(c.label(l, 'Linux')),
|
|
c.div(c.label(m, 'Mac OS X')),
|
|
c.button('Build', {onclick: function() {
|
|
c.call(
|
|
{
|
|
commit: c.revision.name,
|
|
linux: l.checked,
|
|
mac: m.checked,
|
|
},
|
|
function() { c.hide() });
|
|
});
|
|
});
|
|
----
|
|
|
|
[[context_put]]
|
|
context.put()
|
|
~~~~~~~~~~~~~
|
|
Issues a PUT REST API call to the URL associated with the action.
|
|
|
|
.Signature
|
|
----
|
|
context.put(input, callback)
|
|
----
|
|
|
|
* input: JavaScript object to serialize as the request payload.
|
|
|
|
* callback: JavaScript function to be invoked with the parsed JSON
|
|
result of the API call. If the API returns a string the result is
|
|
a string, otherwise the result is a JavaScript object or array,
|
|
as described in the relevant REST API documentation.
|
|
|
|
----
|
|
context.put(
|
|
{message: "..."},
|
|
function (result) {
|
|
// ... use result here ...
|
|
});
|
|
----
|
|
|
|
[[context_refresh]]
|
|
context.refresh()
|
|
~~~~~~~~~~~~~~~~~
|
|
Refresh the current display. Shorthand for
|
|
link:#Gerrit_refresh[`Gerrit.refresh()`].
|
|
|
|
[[context_revision]]
|
|
context.revision
|
|
~~~~~~~~~~~~~~~~
|
|
When the action is invoked on a specific revision of a change,
|
|
a link:rest-api-changes.html#revision-info[RevisionInfo]
|
|
object instance describing the revision. Available fields of the
|
|
RevisionInfo may vary based on the options used by the UI when it
|
|
loaded the change.
|
|
|
|
|
|
Action Context HTML Helpers
|
|
---------------------------
|
|
The link:#ActionContext[action context] includes some HTML helper
|
|
functions to make working with DOM based widgets less painful.
|
|
|
|
* `br()`: new `<br>` element.
|
|
|
|
* `button(label, options)`: new `<button>` with the string `label`
|
|
wrapped inside of a `div`. The optional `options` object may
|
|
define `onclick` as a function to be invoked upon clicking. This
|
|
calling pattern avoids circular references between the element
|
|
and the onclick handler.
|
|
|
|
* `checkbox()`: new `<input type='checkbox'>` element.
|
|
* `div(...)`: a new `<div>` wrapping the (optional) arguments.
|
|
* `hr()`: new `<hr>` element.
|
|
|
|
* `label(c, label)`: a new `<label>` element wrapping element `c`
|
|
and the string `label`. Used to wrap a checkbox with its label,
|
|
`label(checkbox(), 'Click Me')`.
|
|
|
|
* `prependLabel(label, c)`: a new `<label>` element wrapping element `c`
|
|
and the string `label`. Used to wrap an input field with its label,
|
|
`prependLabel('Greeting message', textfield())`.
|
|
|
|
* `textarea(options)`: new `<textarea>` element. The options
|
|
object may optionally include `rows` and `cols`. The textarea
|
|
comes with an onkeypress handler installed to play nicely with
|
|
Gerrit's keyboard binding system.
|
|
|
|
* `textfield()`: new `<input type='text'>` element. The text field
|
|
comes with an onkeypress handler installed to play nicely with
|
|
Gerrit's keyboard binding system.
|
|
|
|
* `span(...)`: a new `<span>` wrapping the (optional) arguments.
|
|
|
|
[[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_delete]]
|
|
Gerrit.delete()
|
|
~~~~~~~~~~~~~~~
|
|
Issues a DELETE REST API request to the Gerrit server. For plugin
|
|
private REST API URLs see link:#self_delete[self.delete()].
|
|
|
|
.Signature
|
|
----
|
|
Gerrit.delete(url, callback)
|
|
----
|
|
|
|
* url: URL relative to the Gerrit server. For example to access the
|
|
link:rest-api-changes.html[changes REST API] use `'/changes/'`.
|
|
|
|
* callback: JavaScript function to be invoked with the parsed
|
|
JSON result of the API call. DELETE methods often return
|
|
`204 No Content`, which is passed as null.
|
|
|
|
----
|
|
Gerrit.delete(
|
|
'/changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic',
|
|
function () {});
|
|
----
|
|
|
|
[[Gerrit_get]]
|
|
Gerrit.get()
|
|
~~~~~~~~~~~~
|
|
Issues a GET REST API request to the Gerrit server. For plugin
|
|
private REST API URLs see link:#self_get[self.get()].
|
|
|
|
.Signature
|
|
----
|
|
Gerrit.get(url, callback)
|
|
----
|
|
|
|
* url: URL relative to the Gerrit server. For example to access the
|
|
link:rest-api-changes.html[changes REST API] use `'/changes/'`.
|
|
|
|
* callback: JavaScript function to be invoked with the parsed JSON
|
|
result of the API call. If the API returns a string the result is
|
|
a string, otherwise the result is a JavaScript object or array,
|
|
as described in the relevant REST API documentation.
|
|
|
|
----
|
|
Gerrit.get('/changes/?q=status:open', function (open) {
|
|
for (var i = 0; i < open.length; i++) {
|
|
console.log(open.get(i).change_id);
|
|
}
|
|
});
|
|
----
|
|
|
|
[[Gerrit_getPluginName]]
|
|
Gerrit.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.
|
|
|
|
Unlike link:#self_getPluginName[`self.getPluginName()`] this method
|
|
must guess the name from the JavaScript call stack. Plugins are
|
|
encouraged to use `self.getPluginName()` whenever possible.
|
|
|
|
[[Gerrit_go]]
|
|
Gerrit.go()
|
|
~~~~~~~~~~~
|
|
Updates the web UI to display the view identified by the supplied
|
|
URL token. The URL token is the text after `#` in the browser URL.
|
|
|
|
----
|
|
Gerrit.go('/admin/projects/');
|
|
----
|
|
|
|
If the URL passed matches `http://...`, `https://...`, or `//...`
|
|
the current browser window will navigate to the non-Gerrit URL.
|
|
The user can return to Gerrit with the back button.
|
|
|
|
[[Gerrit_install]]
|
|
Gerrit.install()
|
|
~~~~~~~~~~~~~~~~
|
|
Registers a new plugin by invoking the supplied initialization
|
|
function. The function is passed the link:#self[plugin instance].
|
|
|
|
----
|
|
Gerrit.install(function (self) {
|
|
// ... plugin JavaScript code here ...
|
|
});
|
|
----
|
|
|
|
[[Gerrit_post]]
|
|
Gerrit.post()
|
|
~~~~~~~~~~~~~
|
|
Issues a POST REST API request to the Gerrit server. For plugin
|
|
private REST API URLs see link:#self_post[self.post()].
|
|
|
|
.Signature
|
|
----
|
|
Gerrit.post(url, input, callback)
|
|
----
|
|
|
|
* url: URL relative to the Gerrit server. For example to access the
|
|
link:rest-api-changes.html[changes REST API] use `'/changes/'`.
|
|
|
|
* input: JavaScript object to serialize as the request payload.
|
|
|
|
* callback: JavaScript function to be invoked with the parsed JSON
|
|
result of the API call. If the API returns a string the result is
|
|
a string, otherwise the result is a JavaScript object or array,
|
|
as described in the relevant REST API documentation.
|
|
|
|
----
|
|
Gerrit.post(
|
|
'/changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic',
|
|
{topic: 'tests', message: 'Classify work as for testing.'},
|
|
function (r) {});
|
|
----
|
|
|
|
[[Gerrit_put]]
|
|
Gerrit.put()
|
|
~~~~~~~~~~~~
|
|
Issues a PUT REST API request to the Gerrit server. For plugin
|
|
private REST API URLs see link:#self_put[self.put()].
|
|
|
|
.Signature
|
|
----
|
|
Gerrit.put(url, input, callback)
|
|
----
|
|
|
|
* url: URL relative to the Gerrit server. For example to access the
|
|
link:rest-api-changes.html[changes REST API] use `'/changes/'`.
|
|
|
|
* input: JavaScript object to serialize as the request payload.
|
|
|
|
* callback: JavaScript function to be invoked with the parsed JSON
|
|
result of the API call. If the API returns a string the result is
|
|
a string, otherwise the result is a JavaScript object or array,
|
|
as described in the relevant REST API documentation.
|
|
|
|
----
|
|
Gerrit.put(
|
|
'/changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic',
|
|
{topic: 'tests', message: 'Classify work as for testing.'},
|
|
function (r) {});
|
|
----
|
|
|
|
[[Gerrit_onAction]]
|
|
Gerrit.onAction()
|
|
~~~~~~~~~~~~~~~~~
|
|
Register a JavaScript callback to be invoked when the user clicks
|
|
on a button associated with a server side `UiAction`.
|
|
|
|
.Signature
|
|
----
|
|
Gerrit.onAction(type, view_name, callback);
|
|
----
|
|
|
|
* type: `'change'` or `'revision'`, indicating what sort of resource
|
|
the `UiAction` was bound to in the server.
|
|
|
|
* view_name: string appearing in URLs to name the view. This is the
|
|
second argument of the `get()`, `post()`, `put()`, and `delete()`
|
|
binding methods in a `RestApiModule`.
|
|
|
|
* callback: JavaScript function to invoke when the user clicks. The
|
|
function will be passed a link:#ActionContext[ActionContext].
|
|
|
|
[[Gerrit_refresh]]
|
|
Gerrit.refresh()
|
|
~~~~~~~~~~~~~~~~
|
|
Redisplays the current web UI view, refreshing all information.
|
|
|
|
[[Gerrit_url]]
|
|
Gerrit.url()
|
|
~~~~~~~~~~~~
|
|
Returns the URL of the Gerrit Code Review server. If invoked with
|
|
no parameter the URL of the site is returned. If passed a string
|
|
the argument is appended to the site URL.
|
|
|
|
----
|
|
Gerrit.url(); // "https://gerrit-review.googlesource.com/"
|
|
Gerrit.url('/123'); // "https://gerrit-review.googlesource.com/123"
|
|
----
|
|
|
|
For a plugin specific version see link:#self_url()[`self.url()`].
|
|
|
|
GERRIT
|
|
------
|
|
Part of link:index.html[Gerrit Code Review]
|