Mutation API (#1074)

* [API] Allow selection

* [API] Keep in sync using model

* [API] Add selection as EventEmitter

* [API] Use selection from ToDo tutorial

* Object events prototype

* Added examples

* Transitional API

* Modified todo list code to work with new setters

* [API] Removed emitting of events on container when property changes value to remove ambiguity. Listeners must be listening to the same path used in the setter to catch changes

main.js

@@ -56,6 +56,9 @@ requirejs.config({
         },
         "zepto": {
             "exports": "Zepto"
+        },
+        "lodash": {
+            "exports": "lodash"
         }
     }
 });

src/MCT.js

@@ -5,6 +5,7 @@ define([
     './api/api',
     'text!./adapter/templates/edit-object-replacement.html',
     './ui/Dialog',
+    './Selection',
     './api/objects/bundle'
 ], function (
     EventEmitter,
@@ -12,11 +13,15 @@ define([
     uuid,
     api,
     editObjectTemplate,
-    Dialog
+    Dialog,
+    Selection
 ) {
     function MCT() {
         EventEmitter.call(this);
         this.legacyBundle = { extensions: {} };
+
+        this.selection = new Selection();
+        this.on('navigation', this.selection.clear.bind(this.selection));
     }
 
     MCT.prototype = Object.create(EventEmitter.prototype);
@@ -91,6 +96,14 @@ define([
     };
 
     MCT.prototype.start = function () {
+        this.legacyExtension('runs', {
+            depends: ['navigationService'],
+            implementation: function (navigationService) {
+                navigationService
+                    .addListener(this.emit.bind(this, 'navigation'));
+            }.bind(this)
+        });
+
         legacyRegistry.register('adapter', this.legacyBundle);
         this.emit('start');
     };
@@ -100,19 +113,5 @@ define([
         toolbar: "TOOLBAR"
     };
 
-    MCT.prototype.verbs = {
-        mutate: function (domainObject, mutator) {
-            return domainObject.useCapability('mutation', mutator)
-                .then(function () {
-                    var persistence = domainObject.getCapability('persistence');
-                    return persistence.persist();
-                });
-        },
-        observe: function (domainObject, callback) {
-            var mutation = domainObject.getCapability('mutation');
-            return mutation.listen(callback);
-        }
-    };
-
     return MCT;
 });

src/Selection.js

@@ -0,0 +1,32 @@
+define(['EventEmitter'], function (EventEmitter) {
+    function Selection() {
+        EventEmitter.call(this);
+        this.selectedValues = [];
+    }
+
+    Selection.prototype = Object.create(EventEmitter.prototype);
+
+    Selection.prototype.select = function (value) {
+        this.selectedValues.push(value);
+        this.emit('change');
+        return this.deselect.bind(this, value);
+    };
+
+    Selection.prototype.deselect = function (value) {
+        this.selectedValues = this.selectedValues.filter(function (v) {
+            return v !== value;
+        });
+        this.emit('change');
+    };
+
+    Selection.prototype.selected = function () {
+        return this.selectedValues;
+    };
+
+    Selection.prototype.clear = function () {
+        this.selectedValues = [];
+        this.emit('change');
+    };
+
+    return Selection;
+});

src/api/objects/MutableObject.js

@@ -0,0 +1,43 @@
+define([
+    'lodash'
+], function (
+    _
+) {
+    function MutableObject(eventEmitter, object) {
+        this.eventEmitter = eventEmitter;
+        this.object = object;
+        this.unlisteners = [];
+    }
+
+    function qualifiedEventName(object, eventName) {
+        return [object.key.identifier, eventName].join(':');
+    }
+
+    MutableObject.prototype.stopListening = function () {
+        this.unlisteners.forEach(function (unlisten) {
+            unlisten();
+        })
+    };
+
+    MutableObject.prototype.on = function(path, callback) {
+        var fullPath = qualifiedEventName(this.object, path);
+        this.eventEmitter.on(fullPath, callback);
+        this.unlisteners.push(this.eventEmitter.off.bind(this.eventEmitter, fullPath, callback));
+    };
+
+    MutableObject.prototype.set = function (path, value) {
+
+        _.set(this.object, path, value);
+
+        //Emit event specific to property
+        this.eventEmitter.emit(qualifiedEventName(this.object, path), value);
+        //Emit wildcare event
+        this.eventEmitter.emit(qualifiedEventName(this.object, '*'), this.object);
+    };
+
+    MutableObject.prototype.get = function (path) {
+        return _.get(this.object, path);
+    };
+
+    return MutableObject;
+});

src/api/objects/MutableObjectSpec.js

@@ -0,0 +1,110 @@
+/*****************************************************************************
+ * Open MCT Web, Copyright (c) 2014-2015, United States Government
+ * as represented by the Administrator of the National Aeronautics and Space
+ * Administration. All rights reserved.
+ *
+ * Open MCT Web is licensed under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ * Open MCT Web includes source code licensed under additional open source
+ * licenses. See the Open Source Licenses file (LICENSES.md) included with
+ * this source code distribution or the Licensing information page available
+ * at runtime from the About dialog for additional information.
+ *****************************************************************************/
+
+define(['./MutableObject'], function (MutableObject) {
+    describe('Mutable Domain Objects', function () {
+        var domainObject,
+            mutableObject,
+            eventEmitter,
+            arrayProperty,
+            objectProperty,
+            identifier;
+
+        beforeEach(function () {
+            identifier = 'objectId';
+            arrayProperty = [
+                'First array element',
+                'Second array element',
+                'Third array element'
+            ];
+            objectProperty = {
+                prop1: 'val1',
+                prop2: 'val2',
+                prop3: {
+                    propA: 'valA',
+                    propB: 'valB',
+                    propC: []
+                }
+            };
+            domainObject = {
+                    key: {
+                        identifier: identifier
+                    },
+                    stringProperty: 'stringValue',
+                    objectProperty: objectProperty,
+                    arrayProperty: arrayProperty
+                };
+            eventEmitter = jasmine.createSpyObj('eventEmitter', [
+                'emit'
+            ]);
+            mutableObject = new MutableObject(eventEmitter, domainObject);
+        });
+
+        it('Supports getting and setting of object properties', function () {
+            expect(mutableObject.get('stringProperty')).toEqual('stringValue');
+            mutableObject.set('stringProperty', 'updated');
+            expect(mutableObject.get('stringProperty')).toEqual('updated');
+
+            var newArrayProperty = [];
+            expect(mutableObject.get('arrayProperty')).toEqual(arrayProperty);
+            mutableObject.set('arrayProperty', newArrayProperty);
+            expect(mutableObject.get('arrayProperty')).toEqual(newArrayProperty);
+
+            var newObjectProperty = [];
+            expect(mutableObject.get('objectProperty')).toEqual(objectProperty);
+            mutableObject.set('objectProperty', newObjectProperty);
+            expect(mutableObject.get('objectProperty')).toEqual(newObjectProperty);
+        });
+
+        it('Supports getting and setting of nested properties', function () {
+            expect(mutableObject.get('objectProperty')).toEqual(objectProperty);
+            expect(mutableObject.get('objectProperty.prop1')).toEqual(objectProperty.prop1);
+            expect(mutableObject.get('objectProperty.prop3.propA')).toEqual(objectProperty.prop3.propA);
+
+            mutableObject.set('objectProperty.prop1', 'new-prop-1');
+            expect(domainObject.objectProperty.prop1).toEqual('new-prop-1');
+
+            mutableObject.set('objectProperty.prop3.propA', 'new-prop-A');
+            expect(domainObject.objectProperty.prop3.propA).toEqual('new-prop-A');
+
+            mutableObject.set('arrayProperty.1', 'New Second Array Element');
+            expect(arrayProperty[1]).toEqual('New Second Array Element');
+        });
+
+        it('Fires events when properties change', function () {
+            var newString = 'updated'
+            mutableObject.set('stringProperty', newString);
+            expect(eventEmitter.emit).toHaveBeenCalledWith([identifier, 'stringProperty'].join(':'), newString);
+
+            var newArray = [];
+            mutableObject.set('arrayProperty', newArray);
+            expect(eventEmitter.emit).toHaveBeenCalledWith([identifier, 'arrayProperty'].join(':'), newArray);
+
+        });
+
+        it('Fires wildcard event when any property changes', function () {
+            var newString = 'updated'
+            mutableObject.set('objectProperty.prop3.propA', newString);
+            expect(eventEmitter.emit).toHaveBeenCalledWith([identifier, '*'].join(':'), domainObject);
+        });
+    });
+});

src/api/objects/ObjectAPI.js

@@ -1,9 +1,13 @@
 define([
     'lodash',
-    './object-utils'
+    'EventEmitter',
+    './object-utils',
+    './MutableObject'
 ], function (
     _,
-    utils
+    EventEmitter,
+    utils,
+    MutableObject
 ) {
 
     /**
@@ -23,14 +27,13 @@ define([
     var Objects = {},
         ROOT_REGISTRY = [],
         PROVIDER_REGISTRY = {},
-        FALLBACK_PROVIDER;
+        FALLBACK_PROVIDER,
+        eventEmitter = new EventEmitter();
 
     Objects._supersecretSetFallbackProvider = function (p) {
         FALLBACK_PROVIDER = p;
     };
 
-
-
     // Root provider is hardcoded in; can't be skipped.
     var RootProvider = {
         'get': function () {
@@ -48,7 +51,7 @@ define([
             return RootProvider;
         }
         return PROVIDER_REGISTRY[key.namespace] || FALLBACK_PROVIDER;
-    };
+    }
 
     Objects.addProvider = function (namespace, provider) {
         PROVIDER_REGISTRY[namespace] = provider;
@@ -88,5 +91,9 @@ define([
         });
     };
 
+    Objects.getMutable = function (object) {
+        return new MutableObject(eventEmitter, object);
+    };
+
     return Objects;
 });

test-main.js

@@ -55,7 +55,8 @@ requirejs.config({
         "screenfull": "bower_components/screenfull/dist/screenfull.min",
         "text": "bower_components/text/text",
         "uuid": "bower_components/node-uuid/uuid",
-        "zepto": "bower_components/zepto/zepto.min"
+        "zepto": "bower_components/zepto/zepto.min",
+        "lodash": "bower_components/lodash/lodash"
     },
 
     "shim": {
@@ -76,6 +77,9 @@ requirejs.config({
         },
         "zepto": {
             "exports": "Zepto"
+        },
+        "lodash": {
+            "exports": "lodash"
         }
     },
 

tutorials/todo/todo.js

@@ -3,8 +3,9 @@ define([
     "text!./todo-task.html",
     "text!./todo-toolbar.html",
     "text!./todo-dialog.html",
+    "../../src/api/objects/object-utils",
     "zepto"
-], function (todoTemplate, taskTemplate, toolbarTemplate, dialogTemplate, $) {
+], function (todoTemplate, taskTemplate, toolbarTemplate, dialogTemplate, utils, $) {
     /**
      * @param {mct.MCT} mct
      */
@@ -25,31 +26,46 @@ define([
 
         function TodoView(domainObject) {
             this.domainObject = domainObject;
+            this.mutableObject = undefined;
+
             this.filterValue = "all";
+            this.render = this.render.bind(this);
+            this.objectChanged = this.objectChanged.bind(this);
         }
 
-        TodoView.prototype.show = function (container) {
-            this.destroy();
-
-            this.$els = $(todoTemplate);
-            this.$buttons = {
-                all: this.$els.find('.example-todo-button-all'),
-                incomplete: this.$els.find('.example-todo-button-incomplete'),
-                complete: this.$els.find('.example-todo-button-complete')
-            };
-
-            $(container).empty().append(this.$els);
-
-            this.initialize();
+        TodoView.prototype.objectChanged = function (object) {
+            if (this.mutableObject) {
+                this.mutableObject.stopListening();
+            }
+            this.mutableObject = mct.Objects.getMutable(object);
             this.render();
 
-            mct.verbs.observe(this.domainObject, this.render.bind(this));
+            //If anything on object changes, re-render view
+            this.mutableObject.on("*", this.objectChanged);
+        };
+
+        TodoView.prototype.show = function (container) {
+            var self = this;
+            this.destroy();
+
+            mct.Objects.get(utils.parseKeyString(self.domainObject.getId())).then(function (object) {
+                self.$els = $(todoTemplate);
+                self.$buttons = {
+                    all: self.$els.find('.example-todo-button-all'),
+                    incomplete: self.$els.find('.example-todo-button-incomplete'),
+                    complete: self.$els.find('.example-todo-button-complete')
+                };
+
+                $(container).empty().append(self.$els);
+
+                self.initialize();
+                self.objectChanged(object)
+            });
         };
 
         TodoView.prototype.destroy = function () {
-            if (this.unlisten) {
-                this.unlisten();
-                this.unlisten = undefined;
+            if (this.mutableObject) {
+                this.mutableObject.stopListening();
             }
         };
 
@@ -62,12 +78,14 @@ define([
             Object.keys(this.$buttons).forEach(function (k) {
                 this.$buttons[k].on('click', this.setFilter.bind(this, k));
             }, this);
+
+            mct.selection.on('change', this.render);
         };
 
         TodoView.prototype.render = function () {
             var $els = this.$els;
-            var domainObject = this.domainObject;
-            var tasks = domainObject.getModel().tasks;
+            var mutableObject = this.mutableObject;
+            var tasks = mutableObject.get('tasks');
             var $message = $els.find('.example-message');
             var $list = $els.find('.example-todo-task-list');
             var $buttons = this.$buttons;
@@ -83,6 +101,7 @@ define([
                 }
             };
             var filterValue = this.filterValue;
+            var selected = mct.selection.selected();
 
             Object.keys($buttons).forEach(function (k) {
                 $buttons[k].toggleClass('selected', filterValue === k);
@@ -93,59 +112,97 @@ define([
             tasks.forEach(function (task, index) {
                 var $taskEls = $(taskTemplate);
                 var $checkbox = $taskEls.find('.example-task-checked');
+                var $desc = $taskEls.find('.example-task-description');
                 $checkbox.prop('checked', task.completed);
-                $taskEls.find('.example-task-description')
-                    .text(task.description);
+                $desc.text(task.description);
 
                 $checkbox.on('change', function () {
                     var checked = !!$checkbox.prop('checked');
-                    mct.verbs.mutate(domainObject, function (model) {
-                        model.tasks[index].completed = checked;
-                    });
+                    mutableObject.set("tasks." + index + ".completed", checked);
                 });
 
+                $desc.on('click', function () {
+                    mct.selection.clear();
+                    mct.selection.select({ index: index });
+                });
+
+                if (selected.length > 0 && selected[0].index === index) {
+                    $desc.addClass('selected');
+                }
+
                 $list.append($taskEls);
             });
 
             $message.toggle(tasks.length < 1);
         };
 
-
-
         function TodoToolbarView(domainObject) {
             this.domainObject = domainObject;
+            this.mutableObject = undefined;
+
+            this.handleSelectionChange = this.handleSelectionChange.bind(this);
         }
 
         TodoToolbarView.prototype.show = function (container) {
-            var $els = $(toolbarTemplate);
-            var $add = $els.find('a.example-add');
-            var $remove = $els.find('a.example-remove');
-            var domainObject = this.domainObject;
+            var self = this;
+            this.destroy();
 
-            $(container).append($els);
+            mct.Objects.get(utils.parseKeyString(this.domainObject.getId())).then(function (wrappedObject){
 
-            $add.on('click', function () {
-                var $dialog = $(dialogTemplate),
-                    view = {
-                        show: function (container) {
-                            $(container).append($dialog);
-                        },
-                        destroy: function () {}
-                    };
+                self.mutableObject = mct.Objects.getMutable(wrappedObject);
 
-                mct.dialog(view, "Add a Task").then(function () {
-                    var description = $dialog.find('input').val();
-                    mct.verbs.mutate(domainObject, function (model) {
-                        model.tasks.push({ description: description });
-                        console.log(model);
+                var $els = $(toolbarTemplate);
+                var $add = $els.find('a.example-add');
+                var $remove = $els.find('a.example-remove');
+
+                $(container).append($els);
+
+                $add.on('click', function () {
+                    var $dialog = $(dialogTemplate),
+                        view = {
+                            show: function (container) {
+                                $(container).append($dialog);
+                            },
+                            destroy: function () {}
+                        };
+
+                    mct.dialog(view, "Add a Task").then(function () {
+                        var description = $dialog.find('input').val();
+                        var tasks = self.mutableObject.get('tasks');
+                        tasks.push({ description: description });
+                        self.mutableObject.set('tasks', tasks);
                     });
                 });
+                $remove.on('click', function () {
+                    var index = mct.selection.selected()[0].index;
+                    if (index !== undefined) {
+                        var tasks = self.mutableObject.get('tasks').filter(function (t, i) {
+                            return i !== index;
+                        });
+                        self.mutableObject.set("tasks", tasks);
+                        self.mutableObject.set("selected", undefined);
+                        mct.selection.clear();
+                    }
+                });
+                self.$remove = $remove;
+                self.handleSelectionChange();
+                mct.selection.on('change', self.handleSelectionChange);
             });
-            $remove.on('click', window.alert.bind(window, "Remove!"));
+        };
+
+        TodoToolbarView.prototype.handleSelectionChange = function () {
+            var selected = mct.selection.selected();
+            if (this.$remove) {
+                this.$remove.toggle(selected.length > 0);
+            }
         };
 
         TodoToolbarView.prototype.destroy = function () {
-
+            mct.selection.off('change', this.handleSelectionChange);
+            this.$remove = undefined;
+            if (this.mutableObject) {
+                this.mutableObject.stopListening();
+            }
         };
 
         mct.type('example.todo', todoType);