From b4e3ff1e89b4ce67da35f3d3cdfcb692fa8c2618 Mon Sep 17 00:00:00 2001
From: Cindy Lu <clu@us.ibm.com>
Date: Wed, 19 Oct 2016 15:55:51 -0700
Subject: [PATCH] Update customizing.rst with a how to use the NG registry

Since resourceRegistryService is good to go and since we're using
NG Images Panel by default (^_^), it would be nice
to provide some documentation for developers showing how easy it is to
customize panels in Angular.

Change-Id: I2589a53900df90717ac236d73babe18904541af4
---
 doc/source/topics/customizing.rst | 98 +++++++++++++++++++++++++++++++
 doc/source/tutorials/plugin.rst   |  4 +-
 2 files changed, 100 insertions(+), 2 deletions(-)

diff --git a/doc/source/topics/customizing.rst b/doc/source/topics/customizing.rst
index 4c5d0ef61..2080d40ff 100644
--- a/doc/source/topics/customizing.rst
+++ b/doc/source/topics/customizing.rst
@@ -544,6 +544,104 @@ define new column::
     views.IndexView.table_class = MyUsersTable
 
 
+Customize Angular dashboards
+============================
+
+In Angular, you may write a plugin to extend certain features. Two components
+in the Horizon framework that make this possible are the extensibility service and
+the resource type registry service. The ``extensibleService`` allows certain Horizon
+elements to be extended dynamically, including add, remove, and replace. The
+``resourceTypeRegistry`` service provides methods to set and get information
+pertaining to a resource type object. We use Heat type names like ``OS::Glance::Image``
+as our reference name.
+
+Some information you may place in the registry include:
+
+* API to fetch data from
+* Property names
+* Actions (e.g. "Create Volume")
+* URL paths to detail view or detail drawer
+* Property information like labels or formatting for property values
+
+These properties in the registry use the extensibility service (as of Newton release):
+
+* globalActions
+* batchActions
+* itemActions
+* detailViews
+* tableColumns
+* filterFacets
+
+Using the information from the registry, we can build out our dashboard panels.
+Panels use the high-level directive ``hzResourceTable`` that replaces common
+templates so we do not need to write boilerplate HTML and controller code.
+It gives developers a quick way to build a new table or change an existing table.
+
+.. note::
+
+    You may still choose to use the HTML template for complete control of form
+    and functionality. For example, you may want to create a custom footer.
+    You may also use the ``hzDynamicTable`` directive (what ``hzResourceTable``
+    uses under the hood) directly. However, neither of these is extensible.
+    You would need to override the panel completely.
+
+This is a sample module file to demonstrate how to make some customizations to the
+Images Panel.::
+
+    (function() {
+      'use strict';
+
+      angular
+        .module('horizon.app.core.images')
+        .run(customizeImagePanel);
+
+      customizeImagePanel.$inject = [
+        'horizon.framework.conf.resource-type-registry.service',
+        'horizon.app.core.images.basePath',
+        'horizon.app.core.images.resourceType',
+        'horizon.app.core.images.actions.surprise.service'
+      ];
+
+      function customizeImagePanel(registry, basePath, imageResourceType, surpriseService) {
+        // get registry for ``OS::Glance::Image``
+        registry = registry.getResourceType(imageResourceType);
+
+        // replace existing Size column to make the font color red
+        var column = {
+          id: 'size',
+          priority: 2,
+          template: '<a style="color:red;">{$ item.size | bytes $}</a>'
+        };
+        registry.tableColumns.replace('size', column);
+
+        // add a new detail view
+        registry.detailsViews
+          .append({
+            id: 'anotherDetailView',
+            name: gettext('Another Detail View'),
+            template: basePath + 'demo/detail.html'
+        });
+
+        // set a different summary drawer template
+        registry.setSummaryTemplateUrl(basePath + 'demo/drawer.html');
+
+        // add a new global action
+        registry.globalActions
+          .append({
+            id: 'surpriseAction',
+            service: surpriseService,
+            template: {
+              text: gettext('Surprise')
+            }
+        });
+      }
+    })();
+
+Additionally, you should have content defined in ``detail.html`` and ``drawer.html``,
+as well as define the ``surpriseService`` which is based off the ``actions``
+directive and needs allowed and perform methods defined.
+
+
 Icons
 =====
 
diff --git a/doc/source/tutorials/plugin.rst b/doc/source/tutorials/plugin.rst
index 8292b89c1..e9f036c2e 100644
--- a/doc/source/tutorials/plugin.rst
+++ b/doc/source/tutorials/plugin.rst
@@ -434,8 +434,8 @@ This section describes topics specific to Horizon plugins.
 ADD_INSTALLED_APPS
 ------------------
 
-Ensure to include ``<modulename>`` (``myplugin`` in this example)
-to ``ADD_INSTALLED_APPS`` in one of the ``enabled`` files.
+Be sure to include ``<modulename>`` (``myplugin`` in this example)
+in ``ADD_INSTALLED_APPS`` in the corresponding ``enabled`` file.
 
 * If you are preparing a new plugin, you will use ``<modulename>``
   as ``INSTALLED_APPS`` in most cases as suggested in this tutorial.