2fc17f4e52
The ServerInfo information provides information about the server configuration that is relevant for rendering the UI. UI plugins should be able to access it, e.g. they need the anonymous coward name to render user names the same way as Gerrit core does (use the anonymous coward name if the user has no full name). Change-Id: I272bcb96b5ce888007f6c4fa12f74ef750cc9862 Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
932 lines
28 KiB
Plaintext
932 lines
28 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_delete]]
|
|
=== self.delete() / self.del()
|
|
Issues a DELETE REST API request to the Gerrit server.
|
|
|
|
.Signature
|
|
[source,javascript]
|
|
----
|
|
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]]
|
|
=== self.get()
|
|
Issues a GET REST API request to the Gerrit server.
|
|
|
|
.Signature
|
|
[source,javascript]
|
|
----
|
|
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_getServerInfo]]
|
|
=== self.getServerInfo()
|
|
Returns the server's link:rest-api-config.html#server-info[ServerInfo]
|
|
data.
|
|
|
|
[[self_getCurrentUser]]
|
|
=== self.getCurrentUser()
|
|
Returns the currently signed in user's AccountInfo data; empty account
|
|
data if no user is currently signed in.
|
|
|
|
[[Gerrit_getUserPreferences]]
|
|
=== Gerrit.getUserPreferences()
|
|
Returns the preferences of the currently signed in user; the default
|
|
preferences if no user is currently signed in.
|
|
|
|
[[Gerrit_refreshUserPreferences]]
|
|
=== Gerrit.refreshUserPreferences()
|
|
Refreshes the preferences of the current user.
|
|
|
|
[[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
|
|
[source,javascript]
|
|
----
|
|
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.
|
|
|
|
[source,javascript]
|
|
----
|
|
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
|
|
[source,javascript]
|
|
----
|
|
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.
|
|
|
|
[source,javascript]
|
|
----
|
|
self.put(
|
|
'/builds',
|
|
{start_build: true, platform_type: 'Linux'},
|
|
function (r) {});
|
|
----
|
|
|
|
[[self_on]]
|
|
=== self.on()
|
|
Register a JavaScript callback to be invoked when events occur within
|
|
the web interface.
|
|
|
|
.Signature
|
|
[source,javascript]
|
|
----
|
|
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
|
|
link:rest-api-changes.html#change-info[ChangeInfo] and
|
|
link:rest-api-changes.html#revision-info[RevisionInfo]
|
|
are passed as arguments.
|
|
|
|
* `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.
|
|
|
|
[[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
|
|
[source,javascript]
|
|
----
|
|
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 link:#ActionContext[action context].
|
|
|
|
[[self_screen]]
|
|
=== 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 link:dev-plugins.html#top-menu-extensions[top menu].
|
|
The callback can populate the DOM with the screen's contents.
|
|
|
|
.Signature
|
|
[source,javascript]
|
|
----
|
|
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 link:#ScreenContext[screen 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.
|
|
|
|
[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"
|
|
----
|
|
|
|
|
|
[[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
|
|
An 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
|
|
[source,javascript]
|
|
----
|
|
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.
|
|
|
|
[source,javascript]
|
|
----
|
|
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
|
|
[source,javascript]
|
|
----
|
|
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.
|
|
|
|
[source,javascript]
|
|
----
|
|
context.delete(function () {});
|
|
----
|
|
|
|
[[context_get]]
|
|
=== context.get()
|
|
Issues a GET REST API call to the URL associated with the action.
|
|
|
|
.Signature
|
|
[source,javascript]
|
|
----
|
|
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.
|
|
|
|
[source,javascript]
|
|
----
|
|
context.get(function (result) {
|
|
// ... use result here ...
|
|
});
|
|
----
|
|
|
|
[[context_go]]
|
|
=== context.go()
|
|
Go to a screen. 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
|
|
[source,javascript]
|
|
----
|
|
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.
|
|
|
|
[source,javascript]
|
|
----
|
|
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
|
|
[source,javascript]
|
|
----
|
|
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:
|
|
|
|
[source,javascript]
|
|
----
|
|
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
|
|
[source,javascript]
|
|
----
|
|
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.
|
|
|
|
[source,javascript]
|
|
----
|
|
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.
|
|
|
|
[[context_project]]
|
|
=== context.project
|
|
When the action is invoked on a specific project,
|
|
the name of the project.
|
|
|
|
=== 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.
|
|
|
|
* `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.
|
|
|
|
|
|
[[ScreenContext]]
|
|
== Screen Context
|
|
A new screen context is passed to the `screen` callback function
|
|
each time the user navigates to a matching URL.
|
|
|
|
[[screen_body]]
|
|
=== 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]]
|
|
=== 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]]
|
|
=== 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]]
|
|
=== 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
|
|
[source,javascript]
|
|
----
|
|
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]]
|
|
=== 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
|
|
[source,javascript]
|
|
----
|
|
screen.setPageTitle(titleText)
|
|
----
|
|
|
|
[[screen.setWindowTitle]]
|
|
=== 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
|
|
[source,javascript]
|
|
----
|
|
screen.setWindowTitle(titleText)
|
|
----
|
|
|
|
[[screen_show]]
|
|
=== 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]]
|
|
== 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()
|
|
~~~~~~~~~~~~
|
|
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 link:#Gerrit_html[`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
|
|
[source,javascript]
|
|
----
|
|
Gerrit.install(function(self)) {
|
|
var style = {
|
|
name: Gerrit.css('background: #fff; color: #000;'),
|
|
};
|
|
});
|
|
----
|
|
|
|
[[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
|
|
[source,javascript]
|
|
----
|
|
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.
|
|
|
|
[source,javascript]
|
|
----
|
|
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
|
|
[source,javascript]
|
|
----
|
|
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.
|
|
|
|
[source,javascript]
|
|
----
|
|
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]]
|
|
=== Gerrit.getCurrentUser()
|
|
Returns the currently signed in user's AccountInfo data; empty account
|
|
data if no user is currently signed in.
|
|
|
|
[[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 screen identified by the supplied
|
|
URL token. The URL token is the text after `#` in the browser URL.
|
|
|
|
[source,javascript]
|
|
----
|
|
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]]
|
|
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
|
|
[source,javascript]
|
|
----
|
|
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
|
|
[source,javascript]
|
|
----
|
|
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
|
|
[source,javascript]
|
|
----
|
|
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
|
|
[source,javascript]
|
|
----
|
|
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
|
|
link:#screen_onUnload[screen.onUnload()] to define a callback function
|
|
to perform this cleanup:
|
|
|
|
[source,javascript]
|
|
----
|
|
var w = Gerrit.html(...);
|
|
screen.body.appendElement(w.root);
|
|
screen.onUnload(function() { w.clear() });
|
|
----
|
|
|
|
[[Gerrit_injectCss]]
|
|
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 link:#Gerrit_css[`css()`].
|
|
|
|
[source,javascript]
|
|
----
|
|
Gerrit.injectCss('.myplugin_bg {background: #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_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
|
|
[source,javascript]
|
|
----
|
|
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.
|
|
|
|
[source,javascript]
|
|
----
|
|
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
|
|
[source,javascript]
|
|
----
|
|
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.
|
|
|
|
[source,javascript]
|
|
----
|
|
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
|
|
[source,javascript]
|
|
----
|
|
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 link:#ActionContext[ActionContext].
|
|
|
|
[[Gerrit_screen]]
|
|
=== Gerrit.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 link:dev-plugins.html#top-menu-extensions[top menu].
|
|
The callback can populate the DOM with the screen's contents.
|
|
|
|
.Signature
|
|
[source,javascript]
|
|
----
|
|
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 link:#ScreenContext[screen context].
|
|
|
|
[[Gerrit_refresh]]
|
|
=== Gerrit.refresh()
|
|
Redisplays the current web UI view, refreshing all information.
|
|
|
|
[[Gerrit_refreshMenuBar]]
|
|
=== Gerrit.refreshMenuBar()
|
|
Refreshes Gerrit's menu bar.
|
|
|
|
[[Gerrit_isSignedIn]]
|
|
=== Gerrit.isSignedIn()
|
|
Checks if user is signed in.
|
|
|
|
[[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.
|
|
|
|
[source,javascript]
|
|
----
|
|
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_showError]]
|
|
=== Gerrit.showError(message)
|
|
Displays the given message in the Gerrit ErrorDialog.
|
|
|
|
GERRIT
|
|
------
|
|
Part of link:index.html[Gerrit Code Review]
|
|
|
|
SEARCHBOX
|
|
---------
|