[Tables] #801 Documented MctTable directive

platform/features/table/src/controllers/MCTTableController.js

@@ -85,7 +85,7 @@ define(
                 then: function (callback) {
                     return fastPromise(callback(returnValue));
                 }
-            }
+            };
         }
 
         /**

platform/features/table/src/controllers/RealtimeTableController.js

@@ -68,6 +68,10 @@ define(
 
         RealtimeTableController.prototype = Object.create(TableController.prototype);
 
+        /**
+         * Overrides method on TelemetryTableController providing handling
+         * for realtime data.
+         */
         RealtimeTableController.prototype.addRealtimeData = function() {
             var self = this,
                 datum,
@@ -89,7 +93,7 @@ define(
                         self.$scope.rows.length - 1);
                 }
             });
-        }
+        };
 
         return RealtimeTableController;
     }

platform/features/table/src/controllers/TableOptionsController.js

@@ -55,8 +55,15 @@ define(
 
             $scope.columnsForm = {};
 
+            function unlisten() {
+                self.listeners.forEach(function (listener) {
+                    listener();
+                });
+            }
+
             $scope.$watch('domainObject', function(domainObject) {
-               self.populateForm(domainObject.getModel());
+                unlisten();
+                self.populateForm(domainObject.getModel());
 
                 self.listeners.push(self.domainObject.getCapability('mutation').listen(function (model) {
                     self.populateForm(model);
@@ -79,11 +86,7 @@ define(
             /**
              * Destroy all mutation listeners
              */
-            $scope.$on('$destroy', function () {
-                self.listeners.forEach(function (listener) {
-                   listener();
-                });
-            })
+            $scope.$on('$destroy', unlisten);
 
         }
 

platform/features/table/src/controllers/TelemetryTableController.js

@@ -77,7 +77,7 @@ define(
                 return listener && listener();
             });
             this.changeListeners = [];
-        }
+        };
 
         /**
          * Defer registration of change listeners until domain object is
@@ -156,7 +156,7 @@ define(
 
             if (handle) {
                 handle.promiseTelemetryObjects().then(function () {
-                    self.$scope.headers = []
+                    self.$scope.headers = [];
                     self.$scope.rows = [];
                     table.populateColumns(handle.getMetadata());
 

platform/features/table/src/directives/MCTTable.js

@@ -12,6 +12,51 @@ define(
          * Defines a generic 'Table' component. The table can be populated
          * en-masse by setting the rows attribute, or rows can be added as
          * needed via a broadcast 'addRow' event.
+         *
+         * This directive accepts parameters specifying header and row
+         * content, as well as some additional options.
+         *
+         * Two broadcast events for notifying the table that the rows have
+         * changed. For performance reasons, the table does not monitor the
+         * content of `rows` constantly.
+         * - 'add:row': A $broadcast event that will notify the table that
+         * a new row has been added to the table.
+         * eg.
+         * <pre><code>
+         * $scope.rows.push(newRow);
+         * $scope.$broadcast('add:row', $scope.rows.length-1);
+         * </code></pre>
+         * The code above adds a new row, and alerts the table using the
+         * add:row event. Sorting and filtering will be applied
+         * automatically by the table component.
+         *
+         * - 'remove:row': A $broadcast event that will notify the table that a
+         * row should be removed from the table.
+         * eg.
+         * <pre><code>
+         * $scope.rows.slice(5, 1);
+         * $scope.$broadcast('remove:row', 5);
+         * </code></pre>
+         * The code above removes a row from the rows array, and then alerts
+         * the table to its removal.
+         *
+         * @memberof platform/features/table
+         * @param {string[]} headers The column titles to appear at the top
+         * of the table. Corresponding values are specified in the rows
+         * using the header title provided here.
+         * @param {Object[]} rows The row content. Each row is an object
+         * with key-value pairs where the key corresponds to a header
+         * specified in the headers parameter.
+         * @param {boolean} enableFilter If true, values will be searchable
+         * and results filtered
+         * @param {boolean} enableSort If true, sorting will be enabled
+         * allowing sorting by clicking on column headers
+         * @param {boolean} autoScroll If true, table will automatically
+         * scroll to the bottom as new data arrives. Auto-scroll can be
+         * disengaged manually by scrolling away from the bottom of the
+         * table, and can also be enabled manually by scrolling to the bottom of
+         * the table rows.
+         *
          * @constructor
          */
         function MCTTable($timeout) {

platform/features/table/test/controllers/TableOptionsControllerSpec.js

@@ -63,6 +63,18 @@ define(
                 controller = new TableOptionsController(mockScope);
             });
 
+            it('Listens for changing domain object', function() {
+                expect(mockScope.$watch).toHaveBeenCalledWith('domainObject', jasmine.any(Function));
+            });
+
+            it('On destruction of controller, destroys listeners', function() {
+                var unlistenFunc = jasmine.createSpy("unlisten");
+                controller.listeners.push(unlistenFunc);
+                expect(mockScope.$on).toHaveBeenCalledWith('$destroy', jasmine.any(Function));
+                mockScope.$on.mostRecentCall.args[1]();
+                expect(unlistenFunc).toHaveBeenCalled();
+            });
+
             it('Registers a listener for mutation events on the object', function() {
                 mockScope.$watch.mostRecentCall.args[1](mockDomainObject);
                 expect(mockCapability.listen).toHaveBeenCalled();