diff --git a/Documentation/dev-plugin-pg-styling.txt b/Documentation/dev-plugin-pg-styling.txt deleted file mode 100644 index 618d984685..0000000000 --- a/Documentation/dev-plugin-pg-styling.txt +++ /dev/null @@ -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 - - - -``` - -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. diff --git a/Documentation/dev-plugins-pg.txt b/Documentation/pg-plugin-dev.txt similarity index 66% rename from Documentation/dev-plugins-pg.txt rename to Documentation/pg-plugin-dev.txt index e1bf39e22e..92c52f6b3f 100644 --- a/Documentation/dev-plugins-pg.txt +++ b/Documentation/pg-plugin-dev.txt @@ -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`: ``` -[[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. ``` + +[[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 diff --git a/Documentation/pg-plugin-project-api.txt b/Documentation/pg-plugin-project-api.txt new file mode 100644 index 0000000000..897430c8e7 --- /dev/null +++ b/Documentation/pg-plugin-project-api.txt @@ -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 diff --git a/Documentation/pg-plugin-styling.txt b/Documentation/pg-plugin-styling.txt new file mode 100644 index 0000000000..58b6d7a4ae --- /dev/null +++ b/Documentation/pg-plugin-styling.txt @@ -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 + + + +``` + +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.