240 lines
5.3 KiB
Plaintext
240 lines
5.3 KiB
Plaintext
= Gerrit Code Review - PolyGerrit Plugin Development
|
|
|
|
[[loading]]
|
|
== Plugin loading and initialization
|
|
|
|
link:https://gerrit-review.googlesource.com/Documentation/js-api.html#_entry_point[Entry
|
|
point] for the plugin and the loading method is based on
|
|
link:http://w3c.github.io/webcomponents/spec/imports/[HTML Imports] spec.
|
|
|
|
* The plugin provides index.html, similar to
|
|
link:https://gerrit-review.googlesource.com/Documentation/dev-plugins.html#deployment[.js
|
|
Web UI plugins]
|
|
* index.html contains a `dom-module` tag with a script that uses
|
|
`Gerrit.install()`.
|
|
* PolyGerrit imports index.html along with all required resources defined in it
|
|
(fonts, styles, etc)
|
|
* For standalone plugins, the entry point file is a `pluginname.html` file
|
|
located in `gerrit-site/plugins` folder, where `pluginname` is an alphanumeric
|
|
plugin name.
|
|
|
|
Here's a sample `myplugin.html`:
|
|
|
|
``` html
|
|
<dom-module id="my-plugin">
|
|
<script>
|
|
Gerrit.install(function() { console.log('Ready.'); });
|
|
</script>
|
|
</dom-module>
|
|
```
|
|
|
|
[[low-level-api-concepts]]
|
|
== Low-level DOM API concepts
|
|
|
|
Basically, the DOM is the API surface. Low-level API provides methods for
|
|
decorating, replacing, and styling DOM elements exposed through a set of
|
|
endpoints.
|
|
|
|
PolyGerrit provides a simple way for accessing the DOM via DOM hooks API. A DOM
|
|
hook is a custom element that is instantiated for the plugin endpoint. In the
|
|
decoration case, a hook is set with a `content` attribute that points to the DOM
|
|
element.
|
|
|
|
1. Get the DOM hook API instance via `plugin.hook(endpointName)`
|
|
2. Set up an `onAttached` callback
|
|
3. Callback is called when the hook element is created and inserted into DOM
|
|
4. Use element.content to get UI element
|
|
|
|
``` js
|
|
Gerrit.install(function(plugin) {
|
|
const domHook = plugin.hook('reply-text');
|
|
domHook.onAttached(element => {
|
|
if (!element.content) { return; }
|
|
// element.content is a reply dialog text area.
|
|
});
|
|
});
|
|
```
|
|
|
|
[[low-level-decorating]]
|
|
=== Decorating DOM Elements
|
|
|
|
For each endpoint, PolyGerrit provides a list of DOM properties (such as
|
|
attributes and events) that are supported in the long-term.
|
|
|
|
NOTE: TODO: Insert link to the full endpoints API.
|
|
|
|
``` js
|
|
Gerrit.install(function(plugin) {
|
|
const domHook = plugin.hook('reply-text');
|
|
domHook.onAttached(element => {
|
|
if (!element.content) { return; }
|
|
element.content.style.border = '1px red dashed';
|
|
});
|
|
});
|
|
```
|
|
|
|
[[low-level-replacing]]
|
|
=== Replacing DOM Elements
|
|
|
|
An endpoint's contents can be replaced by passing the replace attribute as an
|
|
option.
|
|
|
|
``` js
|
|
Gerrit.install(function(plugin) {
|
|
const domHook = plugin.hook('header-title', {replace: true});
|
|
domHook.onAttached(element => {
|
|
element.appendChild(document.createElement('my-site-header'));
|
|
});
|
|
});
|
|
```
|
|
|
|
[[low-level-style]]
|
|
=== Styling DOM Elements
|
|
|
|
A plugin may provide Polymer's
|
|
https://www.polymer-project.org/2.0/docs/devguide/style-shadow-dom#style-modules[style
|
|
modules] to style individual endpoints using
|
|
`plugin.registerStyleModule(endpointName, moduleName)`. A style must be defined
|
|
as a standalone `<dom-module>` defined in the same .html file.
|
|
|
|
Note: TODO: Insert link to the full styling API.
|
|
|
|
``` html
|
|
<dom-module id="my-plugin">
|
|
<script>
|
|
Gerrit.install(function(plugin) {
|
|
plugin.registerStyleModule('change-metadata', 'some-style-module');
|
|
});
|
|
</script>
|
|
</dom-module>
|
|
|
|
<dom-module id="some-style-module">
|
|
<style>
|
|
html {
|
|
--change-metadata-label-status: {
|
|
display: none;
|
|
}
|
|
--change-metadata-strategy: {
|
|
display: none;
|
|
}
|
|
}
|
|
</style>
|
|
</dom-module>
|
|
```
|
|
|
|
[[high-level-api-concepts]]
|
|
== High-level DOM API concepts
|
|
|
|
High leve API is based on low-level DOM API and is essentially a standartized
|
|
way for doing common tasks. It's less flexible, but will be a bit more stable.
|
|
|
|
Common way to access high-leve API is through `plugin` instance passed into
|
|
setup callback parameter of `Gerrit.install()`, also sometimes referred as
|
|
`self`.
|
|
|
|
[[low-level-api]]
|
|
== Low-level DOM API
|
|
|
|
Low-level DOM API methods are the base of all UI customization.
|
|
|
|
=== attributeHelper
|
|
`plugin.attributeHelper(element)`
|
|
|
|
Note: TODO
|
|
|
|
=== eventHelper
|
|
`plugin.eventHelper(element)`
|
|
|
|
Note: TODO
|
|
|
|
=== hook
|
|
`plugin.hook(endpointName, opt_options)`
|
|
|
|
Note: TODO
|
|
|
|
=== registerCustomComponent
|
|
`plugin.registerCustomComponent(endpointName, opt_moduleName, opt_options)`
|
|
|
|
Note: TODO
|
|
|
|
=== registerStyleModule
|
|
`plugin.registerStyleModule(endpointName, moduleName)`
|
|
|
|
Note: TODO
|
|
|
|
[[high-level-api]]
|
|
== High-level API
|
|
|
|
Plugin instance provides access to number of more specific APIs and methods
|
|
to be used by plugin authors.
|
|
|
|
=== changeReply
|
|
`plugin.changeReply()`
|
|
|
|
Note: TODO
|
|
|
|
=== changeView
|
|
`plugin.changeView()`
|
|
|
|
Note: TODO
|
|
|
|
=== delete
|
|
`plugin.delete(url, opt_callback)`
|
|
|
|
Note: TODO
|
|
|
|
=== get
|
|
`plugin.get(url, opt_callback)`
|
|
|
|
Note: TODO
|
|
|
|
=== getPluginName
|
|
`plugin.getPluginName()`
|
|
|
|
Note: TODO
|
|
|
|
=== getServerInfo
|
|
`plugin.getServerInfo()`
|
|
|
|
Note: TODO
|
|
|
|
=== on
|
|
`plugin.on(eventName, callback)`
|
|
|
|
Note: TODO
|
|
|
|
=== popup
|
|
`plugin.popup(moduleName)`
|
|
|
|
Note: TODO
|
|
|
|
=== post
|
|
`plugin.post(url, payload, opt_callback)`
|
|
|
|
Note: TODO
|
|
|
|
[plugin-project]
|
|
=== project
|
|
`plugin.project()`
|
|
|
|
.Params:
|
|
- none
|
|
|
|
.Returns:
|
|
- Instance of link:pg-plugin-project-api.html[GrProjectApi].
|
|
|
|
=== put
|
|
`plugin.put(url, payload, opt_callback)`
|
|
|
|
Note: TODO
|
|
|
|
=== theme
|
|
`plugin.theme()`
|
|
|
|
Note: TODO
|
|
|
|
=== url
|
|
`plugin.url(opt_path)`
|
|
|
|
Note: TODO
|