Update PolyGerrit plugin documentation
Add plugin.project() docs, placeholders for other methods, minor cleanup. Change-Id: I7307a0ec6be6f920c58582b6f619db00de2249b3
This commit is contained in:
Viktar Donich
Paladox none
parent
3a6b923be4
commit
fd1985ac56
|
|
@ -1,61 +0,0 @@
|
|||
= Gerrit Code Review - PolyGerrit Plugin Styling
|
||||
|
||||
CAUTION: Work in progress. Hard hat area. +
|
||||
This document will be populated with details along with implementation. +
|
||||
link:https://groups.google.com/d/topic/repo-discuss/vb8WJ4m0hK0/discussion[Join the discussion.]
|
||||
|
||||
== Plugin styles
|
||||
|
||||
Plugins may provide link:https://www.polymer-project.org/2.0/docs/devguide/style-shadow-dom#style-modules[Polymer style modules] for UI CSS-based customization.
|
||||
|
||||
PolyGerrit UI implements number of styling endpoints, which apply CSS mixins link:https://tabatkins.github.io/specs/css-apply-rule/[using @apply] to its direct contents.
|
||||
|
||||
NOTE: Only items (ie CSS properties and mixin targets) documented here are guaranteed to work in the long term, since they are covered by integration tests. +
|
||||
When there is a need to add new property or endpoint, please link:https://bugs.chromium.org/p/gerrit/issues/entry?template=PolyGerrit%20Issue[file a bug] stating your usecase to track and maintain for future releases.
|
||||
|
||||
Plugin should be html-based and imported following PolyGerrit's link:dev-plugins-pg.html#loading[dev guide].
|
||||
|
||||
Plugin should provide Style Module, for example:
|
||||
|
||||
``` html
|
||||
<dom-module id="some-style">
|
||||
<style>
|
||||
:root {
|
||||
--css-mixin-name: {
|
||||
property: value;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
</dom-module>
|
||||
```
|
||||
|
||||
Plugin should register style module with a styling endpoint using `Plugin.prototype.registerStyleModule(endpointName, styleModuleName)`, for example:
|
||||
|
||||
``` js
|
||||
Gerrit.install(function(plugin) {
|
||||
plugin.registerStyleModule('some-endpoint', 'some-style');
|
||||
});
|
||||
```
|
||||
|
||||
== Available styling endpoints
|
||||
=== change-metadata
|
||||
Following custom css mixins are recognized:
|
||||
|
||||
* `--change-metadata-assignee`
|
||||
+
|
||||
is applied to `gr-change-metadata section.assignee`
|
||||
* `--change-metadata-label-status`
|
||||
+
|
||||
is applied to `gr-change-metadata section.labelStatus`
|
||||
* `--change-metadata-strategy`
|
||||
+
|
||||
is applied to `gr-change-metadata section.strategy`
|
||||
* `--change-metadata-topic`
|
||||
+
|
||||
is applied to `gr-change-metadata section.topic`
|
||||
|
||||
Following CSS properties have link:https://gerrit.googlesource.com/gerrit/+/master/polygerrit-ui/app/elements/change/gr-change-metadata/gr-change-metadata-it_test.html[long-term support via integration test]:
|
||||
|
||||
* `display`
|
||||
+
|
||||
can be set to `none` to hide a section.
|
||||
|
|
@ -1,10 +1,5 @@
|
|||
= Gerrit Code Review - PolyGerrit Plugin Development
|
||||
|
||||
CAUTION: Work in progress. Hard hat area. +
|
||||
This document will be populated with details along with implementation. +
|
||||
link:https://groups.google.com/d/topic/repo-discuss/vb8WJ4m0hK0/discussion[Join
|
||||
the discussion.]
|
||||
|
||||
[[loading]]
|
||||
== Plugin loading and initialization
|
||||
|
||||
|
|
@ -33,8 +28,8 @@ Here's a sample `myplugin.html`:
|
|||
</dom-module>
|
||||
```
|
||||
|
||||
[[low-level-api]]
|
||||
== Low-level DOM API
|
||||
[[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
|
||||
|
|
@ -126,3 +121,119 @@ Note: TODO: Insert link to the full styling API.
|
|||
</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
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
= Gerrit Code Review - Project admin customization API
|
||||
|
||||
This API is provided by link:pg-plugin-dev.html#plugin-project[plugin.project()]
|
||||
and provides customization to admin page.
|
||||
|
||||
== createCommand
|
||||
`projectApi.createCommand(title, checkVisibleCallback)`
|
||||
|
||||
Create a project command in the admin panel.
|
||||
|
||||
.Params
|
||||
- *title* String title.
|
||||
- *checkVisibleCallback* function to configure command visibility.
|
||||
|
||||
.Returns
|
||||
- GrProjectApi for chainging.
|
||||
|
||||
`checkVisibleCallback(projectName, projectConfig)`
|
||||
|
||||
.Params
|
||||
- *projectName* String project name.
|
||||
- *projectConfig* Object REST API response for project config.
|
||||
|
||||
.Returns
|
||||
- `false` to hide the command for the specific project.
|
||||
|
||||
== onTap
|
||||
`projectApi.onTap(tapCalback)`
|
||||
|
||||
Add a command tap callback.
|
||||
|
||||
.Params
|
||||
- *tapCallback* function that's excuted on command tap.
|
||||
|
||||
.Returns
|
||||
- Nothing
|
||||
|
|
@ -0,0 +1,69 @@
|
|||
= Gerrit Code Review - PolyGerrit Plugin Styling
|
||||
|
||||
== Plugin styles
|
||||
|
||||
Plugins may provide
|
||||
link:https://www.polymer-project.org/2.0/docs/devguide/style-shadow-dom#style-modules[Polymer
|
||||
style modules] for UI CSS-based customization.
|
||||
|
||||
PolyGerrit UI implements number of styling endpoints, which apply CSS mixins
|
||||
link:https://tabatkins.github.io/specs/css-apply-rule/[using @apply] to its
|
||||
direct contents.
|
||||
|
||||
NOTE: Only items (ie CSS properties and mixin targets) documented here are
|
||||
guaranteed to work in the long term, since they are covered by integration
|
||||
tests. + When there is a need to add new property or endpoint, please
|
||||
link:https://bugs.chromium.org/p/gerrit/issues/entry?template=PolyGerrit%20Issue[file
|
||||
a bug] stating your usecase to track and maintain for future releases.
|
||||
|
||||
Plugin should be html-based and imported following PolyGerrit's
|
||||
link:pg-plugin-dev.html#loading[dev guide].
|
||||
|
||||
Plugin should provide Style Module, for example:
|
||||
|
||||
``` html
|
||||
<dom-module id="some-style">
|
||||
<style>
|
||||
:root {
|
||||
--css-mixin-name: {
|
||||
property: value;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
</dom-module>
|
||||
```
|
||||
|
||||
Plugin should register style module with a styling endpoint using
|
||||
`Plugin.prototype.registerStyleModule(endpointName, styleModuleName)`, for
|
||||
example:
|
||||
|
||||
``` js
|
||||
Gerrit.install(function(plugin) {
|
||||
plugin.registerStyleModule('some-endpoint', 'some-style');
|
||||
});
|
||||
```
|
||||
|
||||
== Available styling endpoints
|
||||
=== change-metadata
|
||||
Following custom css mixins are recognized:
|
||||
|
||||
* `--change-metadata-assignee`
|
||||
+
|
||||
is applied to `gr-change-metadata section.assignee`
|
||||
* `--change-metadata-label-status`
|
||||
+
|
||||
is applied to `gr-change-metadata section.labelStatus`
|
||||
* `--change-metadata-strategy`
|
||||
+
|
||||
is applied to `gr-change-metadata section.strategy`
|
||||
* `--change-metadata-topic`
|
||||
+
|
||||
is applied to `gr-change-metadata section.topic`
|
||||
|
||||
Following CSS properties have
|
||||
link:https://gerrit.googlesource.com/gerrit/+/master/polygerrit-ui/app/elements/change/gr-change-metadata/gr-change-metadata-it_test.html[long-term
|
||||
support via integration test]:
|
||||
|
||||
* `display`
|
||||
+
|
||||
can be set to `none` to hide a section.
|
||||
Loading…
Reference in New Issue