Update PolyGerrit plugin documentation
Add plugin.project() docs, placeholders for other methods, minor
cleanup.
Change-Id: I7307a0ec6be6f920c58582b6f619db00de2249b3
diff --git a/Documentation/pg-plugin-dev.txt b/Documentation/pg-plugin-dev.txt
new file mode 100644
index 0000000..92c52f6
--- /dev/null
+++ b/Documentation/pg-plugin-dev.txt
@@ -0,0 +1,239 @@
+= 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
