blob: fcda916cd8903b285e00c63c45053cb55cb72916 [file] [log] [blame]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08001= Gerrit Code Review - JavaScript API
Shawn Pearce92a1fa82013-07-16 15:01:40 -07002
3Gerrit Code Review supports an API for JavaScript plugins to interact
4with the web UI and the server process.
5
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08006== Entry Point
Shawn Pearce92a1fa82013-07-16 15:01:40 -07007
8JavaScript is loaded using a standard `<script src='...'>` HTML tag.
9Plugins should protect the global namespace by defining their code
10within an anonymous function passed to `Gerrit.install()`. The plugin
11will be passed an object describing its registration with Gerrit:
12
David Pursehouse68153d72013-09-04 10:09:17 +090013[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -070014----
15Gerrit.install(function (self) {
16 // ... plugin JavaScript code here ...
17});
18----
19
20
21[[self]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -080022== Plugin Instance
Shawn Pearce92a1fa82013-07-16 15:01:40 -070023
24The plugin instance is passed to the plugin's initialization function
25and provides a number of utility services to plugin authors.
26
David Pursehouse8d0b5202013-08-01 14:13:17 +090027[[self_delete]]
Edwin Kempinfc998c42014-02-03 17:51:20 +010028=== self.delete() / self.del()
Shawn Pearce92a1fa82013-07-16 15:01:40 -070029Issues a DELETE REST API request to the Gerrit server.
30
31.Signature
David Pursehouse68153d72013-09-04 10:09:17 +090032[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -070033----
34Gerrit.delete(url, callback)
Edwin Kempinfc998c42014-02-03 17:51:20 +010035Gerrit.del(url, callback)
Shawn Pearce92a1fa82013-07-16 15:01:40 -070036----
37
38* url: URL relative to the plugin's URL space. The JavaScript
39 library prefixes the supplied URL with `/plugins/{getPluginName}/`.
40
41* callback: JavaScript function to be invoked with the parsed
42 JSON result of the API call. DELETE methods often return
43 `204 No Content`, which is passed as null.
44
David Pursehouse8d0b5202013-08-01 14:13:17 +090045[[self_get]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -080046=== self.get()
Shawn Pearce92a1fa82013-07-16 15:01:40 -070047Issues a GET REST API request to the Gerrit server.
48
49.Signature
David Pursehouse68153d72013-09-04 10:09:17 +090050[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -070051----
52self.get(url, callback)
53----
54
55* url: URL relative to the plugin's URL space. The JavaScript
56 library prefixes the supplied URL with `/plugins/{getPluginName}/`.
57
58* callback: JavaScript function to be invoked with the parsed JSON
59 result of the API call. If the API returns a string the result is
60 a string, otherwise the result is a JavaScript object or array,
61 as described in the relevant REST API documentation.
62
David Ostrovsky0a4c0ff2014-09-21 23:06:52 +020063[[self_getCurrentUser]]
64=== self.getCurrentUser()
65Returns the currently signed in user's AccountInfo data; empty account
66data if no user is currently signed in.
67
David Pursehouse8d0b5202013-08-01 14:13:17 +090068[[self_getPluginName]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -080069=== self.getPluginName()
Shawn Pearce92a1fa82013-07-16 15:01:40 -070070Returns the name this plugin was installed as by the server
71administrator. The plugin name is required to access REST API
72views installed by the plugin, or to access resources.
73
David Pursehouse8d0b5202013-08-01 14:13:17 +090074[[self_post]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -080075=== self.post()
Shawn Pearce92a1fa82013-07-16 15:01:40 -070076Issues a POST REST API request to the Gerrit server.
77
78.Signature
David Pursehouse68153d72013-09-04 10:09:17 +090079[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -070080----
81self.post(url, input, callback)
82----
83
84* url: URL relative to the plugin's URL space. The JavaScript
85 library prefixes the supplied URL with `/plugins/{getPluginName}/`.
86
87* input: JavaScript object to serialize as the request payload.
88
89* callback: JavaScript function to be invoked with the parsed JSON
90 result of the API call. If the API returns a string the result is
91 a string, otherwise the result is a JavaScript object or array,
92 as described in the relevant REST API documentation.
93
David Pursehouse68153d72013-09-04 10:09:17 +090094[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -070095----
96self.post(
97 '/my-servlet',
98 {start_build: true, platform_type: 'Linux'},
99 function (r) {});
100----
101
David Pursehouse8d0b5202013-08-01 14:13:17 +0900102[[self_put]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800103=== self.put()
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700104Issues a PUT REST API request to the Gerrit server.
105
106.Signature
David Pursehouse68153d72013-09-04 10:09:17 +0900107[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700108----
109self.put(url, input, callback)
110----
111
112* url: URL relative to the plugin's URL space. The JavaScript
113 library prefixes the supplied URL with `/plugins/{getPluginName}/`.
114
115* input: JavaScript object to serialize as the request payload.
116
117* callback: JavaScript function to be invoked with the parsed JSON
118 result of the API call. If the API returns a string the result is
119 a string, otherwise the result is a JavaScript object or array,
120 as described in the relevant REST API documentation.
121
David Pursehouse68153d72013-09-04 10:09:17 +0900122[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700123----
124self.put(
125 '/builds',
126 {start_build: true, platform_type: 'Linux'},
127 function (r) {});
128----
129
Shawn Pearcedb284cd2013-11-29 20:48:21 -0800130[[self_on]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800131=== self.on()
Shawn Pearcedb284cd2013-11-29 20:48:21 -0800132Register a JavaScript callback to be invoked when events occur within
133the web interface.
134
135.Signature
136[source,javascript]
137----
138Gerrit.on(event, callback);
139----
140
141* event: A supported event type. See below for description.
142
143* callback: JavaScript function to be invoked when event happens.
144 Arguments may be passed to this function, depending on the event.
145
146Supported events:
147
Shawn Pearced5c844f2013-12-26 15:32:26 -0800148* `history`: Invoked when the view is changed to a new screen within
149 the Gerrit web application. The token after "#" is passed as the
Shawn Pearcea48826e2013-11-29 20:38:55 -0800150 argument to the callback function, for example "/c/42/" while
151 showing change 42.
152
Shawn Pearcedb284cd2013-11-29 20:48:21 -0800153* `showchange`: Invoked when a change is made visible. A
154 link:rest-api-changes.html#change-info[ChangeInfo] and
155 link:rest-api-changes.html#revision-info[RevisionInfo]
156 are passed as arguments.
157
Shawn Pearce7c418992013-11-29 20:34:28 -0800158* `submitchange`: Invoked when the submit button is clicked
159 on a change. A link:rest-api-changes.html#change-info[ChangeInfo]
160 and link:rest-api-changes.html#revision-info[RevisionInfo] are
161 passed as arguments. Similar to a form submit validation, the
162 function must return true to allow the operation to continue, or
163 false to prevent it.
164
David Pursehouse8d0b5202013-08-01 14:13:17 +0900165[[self_onAction]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800166=== self.onAction()
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700167Register a JavaScript callback to be invoked when the user clicks
168on a button associated with a server side `UiAction`.
169
170.Signature
David Pursehouse68153d72013-09-04 10:09:17 +0900171[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700172----
Shawn Pearced5c844f2013-12-26 15:32:26 -0800173self.onAction(type, view_name, callback);
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700174----
175
David Ostrovskycdda3312014-08-03 14:03:13 +0200176* type: `'change'`, `'edit'`, `'revision'`, `'project'`, or `'branch'`
Shawn Pearced1cf9622014-03-24 16:21:51 -0700177 indicating which type of resource the `UiAction` was bound to
178 in the server.
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700179
180* view_name: string appearing in URLs to name the view. This is the
181 second argument of the `get()`, `post()`, `put()`, and `delete()`
182 binding methods in a `RestApiModule`.
183
184* callback: JavaScript function to invoke when the user clicks. The
185 function will be passed a link:#ActionContext[action context].
186
Shawn Pearced5c844f2013-12-26 15:32:26 -0800187[[self_screen]]
188=== self.screen()
189Register a JavaScript callback to be invoked when the user navigates
190to an extension screen provided by the plugin. Extension screens are
191usually linked from the link:dev-plugins.html#top-menu-extensions[top menu].
192The callback can populate the DOM with the screen's contents.
193
194.Signature
195[source,javascript]
196----
197self.screen(pattern, callback);
198----
199
200* pattern: URL token pattern to identify the screen. Argument can be
201 either a string (`'index'`) or a RegExp object (`/list\/(.*)/`).
202 If a RegExp is used the matching groups will be available inside of
203 the context as `token_match`.
204
205* callback: JavaScript function to invoke when the user navigates to
206 the screen. The function will be passed a link:#ScreenContext[screen context].
207
David Pursehouse8d0b5202013-08-01 14:13:17 +0900208[[self_url]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800209=== self.url()
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700210Returns a URL within the plugin's URL space. If invoked with no
David Pursehouse8d0b5202013-08-01 14:13:17 +0900211parameter the URL of the plugin is returned. If passed a string
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700212the argument is appended to the plugin URL.
213
David Pursehouse68153d72013-09-04 10:09:17 +0900214[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700215----
216self.url(); // "https://gerrit-review.googlesource.com/plugins/demo/"
217self.url('/static/icon.png'); // "https://gerrit-review.googlesource.com/plugins/demo/static/icon.png"
218----
219
220
221[[ActionContext]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800222== Action Context
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700223A new action context is passed to the `onAction` callback function
224each time the associated action button is clicked by the user. A
225context is initialized with sufficient state to issue the associated
226REST API RPC.
227
David Pursehouse8d0b5202013-08-01 14:13:17 +0900228[[context_action]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800229=== context.action
David Pursehouse68153d72013-09-04 10:09:17 +0900230An link:rest-api-changes.html#action-info[ActionInfo] object instance
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700231supplied by the server describing the UI button the user used to
232invoke the action.
233
David Pursehouse8d0b5202013-08-01 14:13:17 +0900234[[context_call]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800235=== context.call()
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700236Issues the REST API call associated with the action. The HTTP method
237used comes from `context.action.method`, hiding the JavaScript from
238needing to care.
239
240.Signature
David Pursehouse68153d72013-09-04 10:09:17 +0900241[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700242----
243context.call(input, callback)
244----
245
246* input: JavaScript object to serialize as the request payload. This
247 parameter is ignored for GET and DELETE methods.
248
249* callback: JavaScript function to be invoked with the parsed JSON
250 result of the API call. If the API returns a string the result is
251 a string, otherwise the result is a JavaScript object or array,
252 as described in the relevant REST API documentation.
253
David Pursehouse68153d72013-09-04 10:09:17 +0900254[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700255----
256context.call(
257 {message: "..."},
258 function (result) {
259 // ... use result here ...
260 });
261----
262
David Pursehouse8d0b5202013-08-01 14:13:17 +0900263[[context_change]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800264=== context.change
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700265When the action is invoked on a change a
266link:rest-api-changes.html#change-info[ChangeInfo] object instance
267describing the change. Available fields of the ChangeInfo may vary
268based on the options used by the UI when it loaded the change.
269
David Pursehouse8d0b5202013-08-01 14:13:17 +0900270[[context_delete]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800271=== context.delete()
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700272Issues a DELETE REST API call to the URL associated with the action.
273
274.Signature
David Pursehouse68153d72013-09-04 10:09:17 +0900275[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700276----
277context.delete(callback)
278----
279
280* callback: JavaScript function to be invoked with the parsed
281 JSON result of the API call. DELETE methods often return
282 `204 No Content`, which is passed as null.
283
David Pursehouse68153d72013-09-04 10:09:17 +0900284[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700285----
286context.delete(function () {});
287----
288
David Pursehouse8d0b5202013-08-01 14:13:17 +0900289[[context_get]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800290=== context.get()
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700291Issues a GET REST API call to the URL associated with the action.
292
293.Signature
David Pursehouse68153d72013-09-04 10:09:17 +0900294[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700295----
296context.get(callback)
297----
298
299* callback: JavaScript function to be invoked with the parsed JSON
300 result of the API call. If the API returns a string the result is
301 a string, otherwise the result is a JavaScript object or array,
302 as described in the relevant REST API documentation.
303
David Pursehouse68153d72013-09-04 10:09:17 +0900304[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700305----
306context.get(function (result) {
307 // ... use result here ...
308});
309----
310
David Pursehouse8d0b5202013-08-01 14:13:17 +0900311[[context_go]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800312=== context.go()
Shawn Pearced5c844f2013-12-26 15:32:26 -0800313Go to a screen. Shorthand for link:#Gerrit_go[`Gerrit.go()`].
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700314
David Pursehouse8d0b5202013-08-01 14:13:17 +0900315[[context_hide]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800316=== context.hide()
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700317Hide the currently visible popup displayed by
David Pursehouse8d0b5202013-08-01 14:13:17 +0900318link:#context_popup[`context.popup()`].
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700319
David Pursehouse8d0b5202013-08-01 14:13:17 +0900320[[context_post]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800321=== context.post()
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700322Issues a POST REST API call to the URL associated with the action.
323
324.Signature
David Pursehouse68153d72013-09-04 10:09:17 +0900325[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700326----
327context.post(input, callback)
328----
329
330* input: JavaScript object to serialize as the request payload.
331
332* callback: JavaScript function to be invoked with the parsed JSON
333 result of the API call. If the API returns a string the result is
334 a string, otherwise the result is a JavaScript object or array,
335 as described in the relevant REST API documentation.
336
David Pursehouse68153d72013-09-04 10:09:17 +0900337[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700338----
339context.post(
340 {message: "..."},
341 function (result) {
342 // ... use result here ...
343 });
344----
345
David Pursehouse8d0b5202013-08-01 14:13:17 +0900346[[context_popup]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800347=== context.popup()
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700348
349Displays a small popup near the activation button to gather
350additional input from the user before executing the REST API RPC.
351
352The caller is always responsible for closing the popup with
David Pursehouse8d0b5202013-08-01 14:13:17 +0900353link#context_hide[`context.hide()`]. Gerrit will handle closing a
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700354popup if the user presses `Escape` while keyboard focus is within
355the popup.
356
357.Signature
David Pursehouse68153d72013-09-04 10:09:17 +0900358[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700359----
360context.popup(element)
361----
362
363* element: an HTML DOM element to display as the body of the
364 popup. This is typically a `div` element but can be any valid HTML
365 element. CSS can be used to style the element beyond the defaults.
366
367A common usage is to gather more input:
David Pursehouse68153d72013-09-04 10:09:17 +0900368
369[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700370----
371self.onAction('revision', 'start-build', function (c) {
372 var l = c.checkbox();
373 var m = c.checkbox();
374 c.popup(c.div(
375 c.div(c.label(l, 'Linux')),
376 c.div(c.label(m, 'Mac OS X')),
377 c.button('Build', {onclick: function() {
378 c.call(
379 {
380 commit: c.revision.name,
381 linux: l.checked,
382 mac: m.checked,
383 },
384 function() { c.hide() });
385 });
386});
387----
388
David Pursehouse8d0b5202013-08-01 14:13:17 +0900389[[context_put]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800390=== context.put()
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700391Issues a PUT REST API call to the URL associated with the action.
392
393.Signature
David Pursehouse68153d72013-09-04 10:09:17 +0900394[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700395----
396context.put(input, callback)
397----
398
399* input: JavaScript object to serialize as the request payload.
400
401* callback: JavaScript function to be invoked with the parsed JSON
402 result of the API call. If the API returns a string the result is
403 a string, otherwise the result is a JavaScript object or array,
404 as described in the relevant REST API documentation.
405
David Pursehouse68153d72013-09-04 10:09:17 +0900406[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700407----
408context.put(
409 {message: "..."},
410 function (result) {
411 // ... use result here ...
412 });
413----
414
David Pursehouse8d0b5202013-08-01 14:13:17 +0900415[[context_refresh]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800416=== context.refresh()
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700417Refresh the current display. Shorthand for
David Pursehouse8d0b5202013-08-01 14:13:17 +0900418link:#Gerrit_refresh[`Gerrit.refresh()`].
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700419
David Pursehouse8d0b5202013-08-01 14:13:17 +0900420[[context_revision]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800421=== context.revision
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700422When the action is invoked on a specific revision of a change,
423a link:rest-api-changes.html#revision-info[RevisionInfo]
424object instance describing the revision. Available fields of the
425RevisionInfo may vary based on the options used by the UI when it
426loaded the change.
427
David Ostrovsky9e8b2fb2013-08-30 08:09:53 +0200428[[context_project]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800429=== context.project
David Ostrovsky9e8b2fb2013-08-30 08:09:53 +0200430When the action is invoked on a specific project,
431the name of the project.
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700432
Shawn Pearced5c844f2013-12-26 15:32:26 -0800433=== HTML Helpers
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700434The link:#ActionContext[action context] includes some HTML helper
435functions to make working with DOM based widgets less painful.
436
437* `br()`: new `<br>` element.
438
439* `button(label, options)`: new `<button>` with the string `label`
440 wrapped inside of a `div`. The optional `options` object may
441 define `onclick` as a function to be invoked upon clicking. This
442 calling pattern avoids circular references between the element
443 and the onclick handler.
444
445* `checkbox()`: new `<input type='checkbox'>` element.
446* `div(...)`: a new `<div>` wrapping the (optional) arguments.
447* `hr()`: new `<hr>` element.
448
449* `label(c, label)`: a new `<label>` element wrapping element `c`
450 and the string `label`. Used to wrap a checkbox with its label,
451 `label(checkbox(), 'Click Me')`.
452
David Ostrovskya1067a32013-08-19 09:09:17 +0200453* `prependLabel(label, c)`: a new `<label>` element wrapping element `c`
454 and the string `label`. Used to wrap an input field with its label,
455 `prependLabel('Greeting message', textfield())`.
456
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700457* `textarea(options)`: new `<textarea>` element. The options
458 object may optionally include `rows` and `cols`. The textarea
459 comes with an onkeypress handler installed to play nicely with
460 Gerrit's keyboard binding system.
461
462* `textfield()`: new `<input type='text'>` element. The text field
463 comes with an onkeypress handler installed to play nicely with
464 Gerrit's keyboard binding system.
465
Edwin Kempin15ce80c2013-11-14 17:16:24 +0100466* `select(a,i)`: a new `<select>` element containing one `<option>`
467 element for each entry in the provided array `a`. The option with
468 the index `i` will be pre-selected in the drop-down-list.
469
470* `selected(s)`: returns the text of the `<option>` element that is
471 currently selected in the provided `<select>` element `s`.
472
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700473* `span(...)`: a new `<span>` wrapping the (optional) arguments.
474
David Ostrovsky7dfc8022013-08-25 23:05:50 +0200475* `msg(label)`: a new label.
476
Shawn Pearced5c844f2013-12-26 15:32:26 -0800477
478[[ScreenContext]]
479== Screen Context
480A new screen context is passed to the `screen` callback function
481each time the user navigates to a matching URL.
482
483[[screen_body]]
484=== screen.body
485Empty HTML `<div>` node the plugin should add its content to. The
486node is already attached to the document, but is invisible. Plugins
487must call `screen.show()` to display the DOM node. Deferred display
488allows an implementor to partially populate the DOM, make remote HTTP
489requests, finish populating when the callbacks arrive, and only then
490make the view visible to the user.
491
492[[screen_token]]
493=== screen.token
494URL token fragment that activated this screen. The value is identical
495to `screen.token_match[0]`. If the URL is `/#/x/hello/list` the token
496will be `"list"`.
497
498[[screen_token_match]]
499=== screen.token_match
500Array of matching subgroups from the pattern specified to `screen()`.
501This is identical to the result of RegExp.exec. Index 0 contains the
502entire matching expression; index 1 the first matching group, etc.
503
504[[screen_onUnload]]
505=== screen.onUnload()
506Configures an optional callback to be invoked just before the screen
507is deleted from the browser DOM. Plugins can use this callback to
508remove event listeners from DOM nodes, preventing memory leaks.
509
510.Signature
511[source,javascript]
512----
513screen.onUnload(callback)
514----
515
516* callback: JavaScript function to be invoked just before the
517 `screen.body` DOM element is removed from the browser DOM.
518 This event happens when the user navigates to another screen.
519
520[[screen.setTitle]]
521=== screen.setTitle()
522Sets the heading text to be displayed when the screen is visible.
523This is presented in a large bold font below the menus, but above the
524content in `screen.body`. Setting the title also sets the window
525title to the same string, if it has not already been set.
526
527.Signature
528[source,javascript]
529----
530screen.setPageTitle(titleText)
531----
532
533[[screen.setWindowTitle]]
534=== screen.setWindowTitle()
535Sets the text to be displayed in the browser's title bar when the
536screen is visible. Plugins should always prefer this method over
537trying to set `window.title` directly. The window title defaults to
538the title given to `setTitle`.
539
540.Signature
541[source,javascript]
542----
543screen.setWindowTitle(titleText)
544----
545
546[[screen_show]]
547=== screen.show()
548Destroy the currently visible screen and display the plugin's screen.
549This method must be called after adding content to `screen.body`.
550
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700551[[Gerrit]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800552== Gerrit
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700553
554The `Gerrit` object is the only symbol provided into the global
555namespace by Gerrit Code Review. All top-level functions can be
556accessed through this name.
557
Shawn Pearce210b5392013-12-07 22:41:36 -0800558[[Gerrit_css]]
559Gerrit.css()
560~~~~~~~~~~~~
561Creates a new unique CSS class and injects it into the document.
562The name of the class is returned and can be used by the plugin.
563See link:#Gerrit_html[`Gerrit.html()`] for an easy way to use
564generated class names.
565
566Classes created with this function should be created once at install
567time and reused throughout the plugin. Repeatedly creating the same
568class will explode the global stylesheet.
569
570.Signature
571[source,javascript]
572----
573Gerrit.install(function(self)) {
574 var style = {
575 name: Gerrit.css('background: #fff; color: #000;'),
576 };
577});
578----
579
David Pursehouse8d0b5202013-08-01 14:13:17 +0900580[[Gerrit_delete]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800581=== Gerrit.delete()
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700582Issues a DELETE REST API request to the Gerrit server. For plugin
David Pursehouse8d0b5202013-08-01 14:13:17 +0900583private REST API URLs see link:#self_delete[self.delete()].
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700584
585.Signature
David Pursehouse68153d72013-09-04 10:09:17 +0900586[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700587----
588Gerrit.delete(url, callback)
589----
590
591* url: URL relative to the Gerrit server. For example to access the
592 link:rest-api-changes.html[changes REST API] use `'/changes/'`.
593
594* callback: JavaScript function to be invoked with the parsed
595 JSON result of the API call. DELETE methods often return
596 `204 No Content`, which is passed as null.
597
David Pursehouse68153d72013-09-04 10:09:17 +0900598[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700599----
600Gerrit.delete(
601 '/changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic',
602 function () {});
603----
604
David Pursehouse8d0b5202013-08-01 14:13:17 +0900605[[Gerrit_get]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800606=== Gerrit.get()
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700607Issues a GET REST API request to the Gerrit server. For plugin
David Pursehouse8d0b5202013-08-01 14:13:17 +0900608private REST API URLs see link:#self_get[self.get()].
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700609
610.Signature
David Pursehouse68153d72013-09-04 10:09:17 +0900611[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700612----
613Gerrit.get(url, callback)
614----
615
616* url: URL relative to the Gerrit server. For example to access the
617 link:rest-api-changes.html[changes REST API] use `'/changes/'`.
618
619* callback: JavaScript function to be invoked with the parsed JSON
620 result of the API call. If the API returns a string the result is
621 a string, otherwise the result is a JavaScript object or array,
622 as described in the relevant REST API documentation.
623
David Pursehouse68153d72013-09-04 10:09:17 +0900624[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700625----
626Gerrit.get('/changes/?q=status:open', function (open) {
627 for (var i = 0; i < open.length; i++) {
628 console.log(open.get(i).change_id);
629 }
630});
631----
632
David Ostrovsky0a4c0ff2014-09-21 23:06:52 +0200633[[Gerrit_getCurrentUser]]
634=== Gerrit.getCurrentUser()
635Returns the currently signed in user's AccountInfo data; empty account
636data if no user is currently signed in.
637
David Pursehouse8d0b5202013-08-01 14:13:17 +0900638[[Gerrit_getPluginName]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800639=== Gerrit.getPluginName()
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700640Returns the name this plugin was installed as by the server
641administrator. The plugin name is required to access REST API
642views installed by the plugin, or to access resources.
643
David Pursehouse8d0b5202013-08-01 14:13:17 +0900644Unlike link:#self_getPluginName[`self.getPluginName()`] this method
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700645must guess the name from the JavaScript call stack. Plugins are
646encouraged to use `self.getPluginName()` whenever possible.
647
David Pursehouse8d0b5202013-08-01 14:13:17 +0900648[[Gerrit_go]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800649=== Gerrit.go()
Shawn Pearced5c844f2013-12-26 15:32:26 -0800650Updates the web UI to display the screen identified by the supplied
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700651URL token. The URL token is the text after `#` in the browser URL.
652
David Pursehouse68153d72013-09-04 10:09:17 +0900653[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700654----
655Gerrit.go('/admin/projects/');
656----
657
658If the URL passed matches `http://...`, `https://...`, or `//...`
659the current browser window will navigate to the non-Gerrit URL.
660The user can return to Gerrit with the back button.
661
Shawn Pearce210b5392013-12-07 22:41:36 -0800662[[Gerrit_html]]
663Gerrit.html()
664~~~~~~~~~~~~~
665Parses an HTML fragment after performing template replacements. If
666the HTML has a single root element or node that node is returned,
667otherwise it is wrapped inside a `<div>` and the div is returned.
668
669.Signature
670[source,javascript]
671----
672Gerrit.html(htmlText, options, wantElements);
673----
674
675* htmlText: string of HTML to be parsed. A new unattached `<div>` is
676 created in the browser's document and the innerHTML property is
677 assigned to the passed string, after performing replacements. If
678 the div has exactly one child, that child will be returned instead
679 of the div.
680
681* options: optional object reference supplying replacements for any
682 `{name}` references in htmlText. Navigation through objects is
683 supported permitting `{style.bar}` to be replaced with `"foo"` if
684 options was `{style: {bar: "foo"}}`. Value replacements are HTML
685 escaped before being inserted into the document fragment.
686
687* wantElements: if options is given and wantElements is also true
688 an object consisting of `{root: parsedElement, elements: {...}}` is
689 returned instead of the parsed element. The elements object contains
690 a property for each element using `id={name}` in htmlText.
691
692.Example
693[source,javascript]
694----
695var style = {bar: Gerrit.css('background: yellow')};
696Gerrit.html(
697 '<span class="{style.bar}">Hello {name}!</span>',
698 {style: style, name: "World"});
699----
700
701Event handlers can be automatically attached to elements referenced
702through an attribute id. Object navigation is not supported for ids,
703and the parser strips the id attribute before returning the result.
704Handler functions must begin with `on` and be a function to be
705installed on the element. This approach is useful for onclick and
706other handlers that do not want to create circular references that
707will eventually leak browser memory.
708
709.Example
710[source,javascript]
711----
712var options = {
713 link: {
714 onclick: function(e) { window.close() },
715 },
716};
717Gerrit.html('<a href="javascript:;" id="{link}">Close</a>', options);
718----
719
720When using options to install handlers care must be taken to not
721accidentally include the returned element into the event handler's
722closure. This is why options is built before calling `Gerrit.html()`
723and not inline as a shown above with "Hello World".
724
725DOM nodes can optionally be returned, allowing handlers to access the
726elements identified by `id={name}` at a later point in time.
727
728.Example
729[source,javascript]
730----
731var w = Gerrit.html(
732 '<div>Name: <input type="text" id="{name}"></div>'
733 + '<div>Age: <input type="text" id="{age}"></div>'
734 + '<button id="{submit}"><div>Save</div></button>',
735 {
736 submit: {
737 onclick: function(s) {
738 var e = w.elements;
739 window.alert(e.name.value + " is " + e.age.value);
740 },
741 },
742 }, true);
743----
744
745To prevent memory leaks `w.root` and `w.elements` should be set to
746null when the elements are no longer necessary. Screens can use
747link:#screen_onUnload[screen.onUnload()] to define a callback function
748to perform this cleanup:
749
750[source,javascript]
751----
752var w = Gerrit.html(...);
753screen.body.appendElement(w.root);
754screen.onUnload(function() { w.clear() });
755----
756
757[[Gerrit_injectCss]]
758Gerrit.injectCss()
759~~~~~~~~~~~~~~~~~~
760Injects CSS rules into the document by appending onto the end of the
761existing rule list. CSS rules are global to the entire application
762and must be manually scoped by each plugin. For an automatic scoping
763alternative see link:#Gerrit_css[`css()`].
764
765[source,javascript]
766----
767Gerrit.injectCss('.myplugin_bg {background: #000}');
768----
769
David Pursehouse8d0b5202013-08-01 14:13:17 +0900770[[Gerrit_install]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800771=== Gerrit.install()
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700772Registers a new plugin by invoking the supplied initialization
773function. The function is passed the link:#self[plugin instance].
774
David Pursehouse68153d72013-09-04 10:09:17 +0900775[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700776----
777Gerrit.install(function (self) {
778 // ... plugin JavaScript code here ...
779});
780----
781
David Pursehouse8d0b5202013-08-01 14:13:17 +0900782[[Gerrit_post]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800783=== Gerrit.post()
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700784Issues a POST REST API request to the Gerrit server. For plugin
David Pursehouse8d0b5202013-08-01 14:13:17 +0900785private REST API URLs see link:#self_post[self.post()].
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700786
787.Signature
David Pursehouse68153d72013-09-04 10:09:17 +0900788[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700789----
790Gerrit.post(url, input, callback)
791----
792
793* url: URL relative to the Gerrit server. For example to access the
794 link:rest-api-changes.html[changes REST API] use `'/changes/'`.
795
796* input: JavaScript object to serialize as the request payload.
797
798* callback: JavaScript function to be invoked with the parsed JSON
799 result of the API call. If the API returns a string the result is
800 a string, otherwise the result is a JavaScript object or array,
801 as described in the relevant REST API documentation.
802
David Pursehouse68153d72013-09-04 10:09:17 +0900803[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700804----
805Gerrit.post(
806 '/changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic',
807 {topic: 'tests', message: 'Classify work as for testing.'},
808 function (r) {});
809----
810
David Pursehouse8d0b5202013-08-01 14:13:17 +0900811[[Gerrit_put]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800812=== Gerrit.put()
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700813Issues a PUT REST API request to the Gerrit server. For plugin
David Pursehouse8d0b5202013-08-01 14:13:17 +0900814private REST API URLs see link:#self_put[self.put()].
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700815
816.Signature
David Pursehouse68153d72013-09-04 10:09:17 +0900817[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700818----
819Gerrit.put(url, input, callback)
820----
821
822* url: URL relative to the Gerrit server. For example to access the
823 link:rest-api-changes.html[changes REST API] use `'/changes/'`.
824
825* input: JavaScript object to serialize as the request payload.
826
827* callback: JavaScript function to be invoked with the parsed JSON
828 result of the API call. If the API returns a string the result is
829 a string, otherwise the result is a JavaScript object or array,
830 as described in the relevant REST API documentation.
831
David Pursehouse68153d72013-09-04 10:09:17 +0900832[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700833----
834Gerrit.put(
835 '/changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic',
836 {topic: 'tests', message: 'Classify work as for testing.'},
837 function (r) {});
838----
839
David Pursehouse8d0b5202013-08-01 14:13:17 +0900840[[Gerrit_onAction]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800841=== Gerrit.onAction()
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700842Register a JavaScript callback to be invoked when the user clicks
843on a button associated with a server side `UiAction`.
844
845.Signature
David Pursehouse68153d72013-09-04 10:09:17 +0900846[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700847----
848Gerrit.onAction(type, view_name, callback);
849----
850
David Ostrovskycdda3312014-08-03 14:03:13 +0200851* type: `'change'`, `'edit'`, `'revision'`, `'project'` or `'branch'`
852 indicating what sort of resource the `UiAction` was bound to in the server.
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700853
854* view_name: string appearing in URLs to name the view. This is the
855 second argument of the `get()`, `post()`, `put()`, and `delete()`
856 binding methods in a `RestApiModule`.
857
858* callback: JavaScript function to invoke when the user clicks. The
859 function will be passed a link:#ActionContext[ActionContext].
860
Shawn Pearced5c844f2013-12-26 15:32:26 -0800861[[Gerrit_screen]]
862=== Gerrit.screen()
863Register a JavaScript callback to be invoked when the user navigates
864to an extension screen provided by the plugin. Extension screens are
865usually linked from the link:dev-plugins.html#top-menu-extensions[top menu].
866The callback can populate the DOM with the screen's contents.
867
868.Signature
869[source,javascript]
870----
871Gerrit.screen(pattern, callback);
872----
873
874* pattern: URL token pattern to identify the screen. Argument can be
875 either a string (`'index'`) or a RegExp object (`/list\/(.*)/`).
876 If a RegExp is used the matching groups will be available inside of
877 the context as `token_match`.
878
879* callback: JavaScript function to invoke when the user navigates to
880 the screen. The function will be passed link:#ScreenContext[screen context].
881
David Pursehouse8d0b5202013-08-01 14:13:17 +0900882[[Gerrit_refresh]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800883=== Gerrit.refresh()
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700884Redisplays the current web UI view, refreshing all information.
885
Edwin Kempin049c3552014-04-15 11:26:23 +0200886[[Gerrit_refreshMenuBar]]
887=== Gerrit.refreshMenuBar()
888Refreshes Gerrit's menu bar.
889
David Pursehouse8d0b5202013-08-01 14:13:17 +0900890[[Gerrit_url]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800891=== Gerrit.url()
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700892Returns the URL of the Gerrit Code Review server. If invoked with
893no parameter the URL of the site is returned. If passed a string
894the argument is appended to the site URL.
895
David Pursehouse68153d72013-09-04 10:09:17 +0900896[source,javascript]
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700897----
898Gerrit.url(); // "https://gerrit-review.googlesource.com/"
899Gerrit.url('/123'); // "https://gerrit-review.googlesource.com/123"
900----
901
David Pursehouse8d0b5202013-08-01 14:13:17 +0900902For a plugin specific version see link:#self_url()[`self.url()`].
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700903
Edwin Kempin792c8d82014-01-31 16:16:52 +0100904[[Gerrit_showError]]
905=== Gerrit.showError(message)
906Displays the given message in the Gerrit ErrorDialog.
907
Shawn Pearce92a1fa82013-07-16 15:01:40 -0700908GERRIT
909------
910Part of link:index.html[Gerrit Code Review]
Yuxuan 'fishy' Wang99cb68d2013-10-31 17:26:00 -0700911
912SEARCHBOX
913---------