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 ...
});

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.del()

Issues a DELETE REST API request to the Gerrit server.

Signature

Gerrit.delete(url, callback)
Gerrit.del(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.

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.getCurrentUser()

Returns the currently signed in user’s AccountInfo data; empty account data if no user is currently signed in.

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.

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()

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.on()

Signature

Gerrit.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 ChangeInfo and RevisionInfo are passed as arguments.
submitchange: Invoked when the submit button is clicked on a change. A ChangeInfo and 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.

self.onAction()

Signature

self.onAction(type, view_name, callback);

type: 'change', 'edit', 'revision', 'project', or 'branch' indicating which type 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 action context.

self.screen()

Register a JavaScript callback to be invoked when the user navigates to an extension screen provided by the plugin. Extension screens are usually linked from the top menu. The callback can populate the DOM with the screen’s contents.

Signature

self.screen(pattern, callback);

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.
callback: JavaScript function to invoke when the user navigates to the screen. The function will be passed a screen 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.

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

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.

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()

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()

Go to a screen. 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.

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()

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()

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()

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.

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 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.
select(a,i): a new <select> element containing one <option> element for each entry in the provided array a. The option with the index i will be pre-selected in the drop-down-list.
selected(s): returns the text of the <option> element that is currently selected in the provided <select> element s.
span(…): a new <span> wrapping the (optional) arguments.
msg(label): a new label.

Screen Context

A new screen context is passed to the screen callback function each time the user navigates to a matching URL.

screen.body

Empty HTML <div> node the plugin should add its content to. The node is already attached to the document, but is invisible. Plugins must call screen.show() to display the DOM node. Deferred display allows an implementor to partially populate the DOM, make remote HTTP requests, finish populating when the callbacks arrive, and only then make the view visible to the user.

screen.token

URL token fragment that activated this screen. The value is identical to screen.token_match[0]. If the URL is /#/x/hello/list the token will be "list".

screen.token_match

Array of matching subgroups from the pattern specified to screen(). This is identical to the result of RegExp.exec. Index 0 contains the entire matching expression; index 1 the first matching group, etc.

screen.onUnload()

Configures an optional callback to be invoked just before the screen is deleted from the browser DOM. Plugins can use this callback to remove event listeners from DOM nodes, preventing memory leaks.

Signature

screen.onUnload(callback)

callback: JavaScript function to be invoked just before the screen.body DOM element is removed from the browser DOM. This event happens when the user navigates to another screen.

screen.setTitle()

Sets the heading text to be displayed when the screen is visible. This is presented in a large bold font below the menus, but above the content in screen.body. Setting the title also sets the window title to the same string, if it has not already been set.

Signature

screen.setPageTitle(titleText)

screen.setWindowTitle()

Sets the text to be displayed in the browser’s title bar when the screen is visible. Plugins should always prefer this method over trying to set window.title directly. The window title defaults to the title given to setTitle.

Signature

screen.setWindowTitle(titleText)

screen.show()

Destroy the currently visible screen and display the plugin’s screen. This method must be called after adding content to screen.body.

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()

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. See Gerrit.html() for an easy way to use generated class names.

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

Gerrit.install(function(self)) {
  var style = {
    name: Gerrit.css('background: #fff; color: #000;'),
  };
});

Gerrit.delete()

Issues a DELETE REST API request to the Gerrit server. For plugin private REST API URLs see self.delete().

Signature

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().

Signature

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.getCurrentUser()

Returns the currently signed in user’s AccountInfo data; empty account data if no user is currently signed in.

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 screen 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.html()

Parses an HTML fragment after performing template replacements. If the HTML has a single root element or node that node is returned, otherwise it is wrapped inside a <div> and the div is returned.

Signature

Gerrit.html(htmlText, options, wantElements);

htmlText: string of HTML to be parsed. A new unattached <div> is created in the browser’s document and the innerHTML property is assigned to the passed string, after performing replacements. If the div has exactly one child, that child will be returned instead of the div.
options: optional object reference supplying replacements for any {name} references in htmlText. Navigation through objects is supported permitting {style.bar} to be replaced with "foo" if options was {style: {bar: "foo"}}. Value replacements are HTML escaped before being inserted into the document fragment.
wantElements: if options is given and wantElements is also true an object consisting of {root: parsedElement, elements: {…}} is returned instead of the parsed element. The elements object contains a property for each element using id={name} in htmlText.

Example

var style = {bar: Gerrit.css('background: yellow')};
Gerrit.html(
  '<span class="{style.bar}">Hello {name}!</span>',
  {style: style, name: "World"});

Event handlers can be automatically attached to elements referenced through an attribute id. Object navigation is not supported for ids, and the parser strips the id attribute before returning the result. Handler functions must begin with on and be a function to be installed on the element. This approach is useful for onclick and other handlers that do not want to create circular references that will eventually leak browser memory.

Example

var options = {
  link: {
    onclick: function(e) { window.close() },
  },
};
Gerrit.html('<a href="javascript:;" id="{link}">Close</a>', options);

When using options to install handlers care must be taken to not accidentally include the returned element into the event handler’s closure. This is why options is built before calling Gerrit.html() and not inline as a shown above with "Hello World".

DOM nodes can optionally be returned, allowing handlers to access the elements identified by id={name} at a later point in time.

Example

var w = Gerrit.html(
    '<div>Name: <input type="text" id="{name}"></div>'
  + '<div>Age: <input type="text" id="{age}"></div>'
  + '<button id="{submit}"><div>Save</div></button>',
  {
    submit: {
      onclick: function(s) {
        var e = w.elements;
        window.alert(e.name.value + " is " + e.age.value);
      },
    },
  }, true);

To prevent memory leaks w.root and w.elements should be set to null when the elements are no longer necessary. Screens can use screen.onUnload() to define a callback function to perform this cleanup:

var w = Gerrit.html(...);
screen.body.appendElement(w.root);
screen.onUnload(function() { w.clear() });

Gerrit.injectCss()

Injects CSS rules into the document by appending onto the end of the existing rule list. CSS rules are global to the entire application and must be manually scoped by each plugin. For an automatic scoping alternative see css().

Gerrit.injectCss('.myplugin_bg {background: #000}');

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().

Signature

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().

Signature

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()

Signature

Gerrit.onAction(type, view_name, callback);

type: 'change', 'edit', 'revision', 'project' or 'branch' 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 ActionContext.

Gerrit.screen()

Signature

Gerrit.screen(pattern, callback);

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.
callback: JavaScript function to invoke when the user navigates to the screen. The function will be passed screen context.

Gerrit.refresh()

Redisplays the current web UI view, refreshing all information.

Gerrit.refreshMenuBar()

Refreshes Gerrit’s menu bar.

Gerrit.isSignedIn()

Checks if user is signed in.

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().

Gerrit.showError(message)

Displays the given message in the Gerrit ErrorDialog.

Part of Gerrit Code Review