Lightly document DOM Hooks API

plugin.getDomHook now returns a DOM Hook API instance that can be used
to setup callbacks for the dom hook insertion into DOM:

Change-Id: I720d760802ade24fb6e46d9a0a15cdb389182c9d

Documentation/dev-plugins-pg.txt

@@ -2,17 +2,26 @@
 
 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.]
+link:https://groups.google.com/d/topic/repo-discuss/vb8WJ4m0hK0/discussion[Join
+the discussion.]
 
 [[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.
+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.
 
-* 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.
+* 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`:
 
@@ -23,3 +32,97 @@ Here's a sample `myplugin.html`:
   </script>
 </dom-module>
 ```
+
+[[low-level-api]]
+== Low-level DOM API
+
+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.getDomHook(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.getDomHook('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.getDomHook('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.getDomHook('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>
+```