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.delete()
Issues a DELETE REST API request to the Gerrit server.
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()
Issues a GET REST API request to the Gerrit server.
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()
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()
Issues a POST REST API request to the Gerrit server.
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()
Issues a PUT REST API request to the Gerrit server.
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()
Register a JavaScript callback to be invoked when the user clicks
on a button associated with a server side UiAction
.
Gerrit.onAction(type, view_name, callback);
-
type:
'change'
,'revision'
or'project'
, indicating which type of resource theUiAction
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()
, anddelete()
binding methods in aRestApiModule
. -
callback: JavaScript function to invoke when the user clicks. The function will be passed a action context.
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"
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
An ActionInfo object instance supplied by the server describing the UI button the user used to invoke the action.
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.
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
When the action is invoked on a change a 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()
Issues a DELETE REST API call to the URL associated with the action.
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()
Issues a GET REST API call to the URL associated with the action.
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()
Go to a page. Shorthand for Gerrit.go()
.
context.hide()
Hide the currently visible popup displayed by
context.popup()
.
context.post()
Issues a POST REST API call to the URL associated with the action.
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()
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.
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()
Issues a PUT REST API call to the URL associated with the action.
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()
Refresh the current display. Shorthand for
Gerrit.refresh()
.
context.revision
When the action is invoked on a specific revision of a change, a 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.
context.project
When the action is invoked on a specific project, the name of the project.
Action Context HTML Helpers
The 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 stringlabel
wrapped inside of adiv
. The optionaloptions
object may defineonclick
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 elementc
and the stringlabel
. Used to wrap a checkbox with its label,label(checkbox(), 'Click Me')
. -
prependLabel(label, c)
: a new<label>
element wrapping elementc
and the stringlabel
. Used to wrap an input field with its label,prependLabel('Greeting message', textfield())
. -
textarea(options)
: new<textarea>
element. The options object may optionally includerows
andcols
. 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. -
msg(label)
: a new label.
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()
Issues a DELETE REST API request to the Gerrit server. For plugin private REST API URLs see self.delete().
Gerrit.delete(url, callback)
-
url: URL relative to the Gerrit server. For example to access the 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()
Issues a GET REST API request to the Gerrit server. For plugin private REST API URLs see self.get().
Gerrit.get(url, callback)
-
url: URL relative to the Gerrit server. For example to access the 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()
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 self.getPluginName()
this method
must guess the name from the JavaScript call stack. Plugins are
encouraged to use self.getPluginName()
whenever possible.
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()
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 ...
});
Gerrit.post()
Issues a POST REST API request to the Gerrit server. For plugin private REST API URLs see self.post().
Gerrit.post(url, input, callback)
-
url: URL relative to the Gerrit server. For example to access the 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()
Issues a PUT REST API request to the Gerrit server. For plugin private REST API URLs see self.put().
Gerrit.put(url, input, callback)
-
url: URL relative to the Gerrit server. For example to access the 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()
Register a JavaScript callback to be invoked when the user clicks
on a button associated with a server side UiAction
.
Gerrit.onAction(type, view_name, callback);
-
type:
'change'
or'revision'
, indicating what sort of resource theUiAction
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()
, anddelete()
binding methods in aRestApiModule
. -
callback: JavaScript function to invoke when the user clicks. The function will be passed a ActionContext.
Gerrit.refresh()
Redisplays the current web UI view, refreshing all information.
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 self.url()
.
Part of Gerrit Code Review