Resolved merge conflicts

platform/commonUI/edit/src/capabilities/EditorCapability.js

@@ -24,24 +24,42 @@ define(
     [],
     function () {
 
+        /**
+         * A capability that implements an editing 'session' for a domain
+         * object. An editing session is initiated via a call to .edit().
+         * Once initiated, any persist operations will be queued pending a
+         * subsequent call to [.save()](@link #save) or [.cancel()](@link
+         * #cancel).
+         * @param transactionService
+         * @param domainObject
+         * @constructor
+         */
         function EditorCapability(
             transactionService,
-            dirtyModelCache,
             domainObject
         ) {
             this.transactionService = transactionService;
-            this.dirtyModelCache = dirtyModelCache;
             this.domainObject = domainObject;
         }
 
+        /**
+         * Initiate an editing session. This will start a transaction during
+         * which any persist operations will be deferred until either save()
+         * or cancel() are called.
+         */
         EditorCapability.prototype.edit = function () {
             this.transactionService.startTransaction();
             this.domainObject.getCapability('status').set('editing', true);
         };
 
+        function isEditContextRoot (domainObject) {
+            return domainObject.getCapability('status').get('editing');
+        }
+
         function isEditing (domainObject) {
-            return domainObject.getCapability('status').get('editing') ||
-                domainObject.hasCapability('context') && isEditing(domainObject.getCapability('context').getParent());
+            return isEditContextRoot(domainObject) ||
+                domainObject.hasCapability('context') &&
+                isEditing(domainObject.getCapability('context').getParent());
         }
 
         /**
@@ -53,6 +71,20 @@ define(
             return isEditing(this.domainObject);
         };
 
+        /**
+         * Is this the root editing object (ie. the object that the user
+         * clicked 'edit' on)?
+         * @returns {*}
+         */
+        EditorCapability.prototype.isEditContextRoot = function () {
+            return isEditContextRoot(this.domainObject);
+        };
+
+        /**
+         * Save any changes from this editing session. This will flush all
+         * pending persists and end the current transaction
+         * @returns {*}
+         */
         EditorCapability.prototype.save = function () {
             var domainObject = this.domainObject;
             return this.transactionService.commit().then(function() {
@@ -62,6 +94,11 @@ define(
 
         EditorCapability.prototype.invoke = EditorCapability.prototype.edit;
 
+        /**
+         * Cancel the current editing session. This will discard any pending
+         * persist operations
+         * @returns {*}
+         */
         EditorCapability.prototype.cancel = function () {
             var domainObject = this.domainObject;
             return this.transactionService.cancel().then(function(){
@@ -70,15 +107,14 @@ define(
             });
         };
 
+        /**
+         * @returns {boolean} true if there have been any domain model
+         * modifications since the last persist, false otherwise.
+         */
         EditorCapability.prototype.dirty = function () {
-            return this.dirtyModelCache.isDirty(this.domainObject);
+            return (this.domainObject.getModel().modified || 0) > (this.domainObject.getModel().persisted || 0);
         };
 
-        EditorCapability.prototype.appliesTo = function(context) {
-            var domainObject = context.domainObject;
-            return domainObject && domainObject.getType().hasFeature("creation");
-        }
-
         return EditorCapability;
     }
 );

platform/commonUI/edit/src/capabilities/TransactionCapabilityDecorator.js

@@ -26,23 +26,30 @@ define(
     function (TransactionalPersistenceCapability) {
         'use strict';
 
-        function TransactionDecorator(
+        /**
+         * Wraps the [PersistenceCapability]{@link PersistenceCapability} with
+         * transactional capabilities.
+         * @param $q
+         * @param transactionService
+         * @param capabilityService
+         * @see TransactionalPersistenceCapability
+         * @constructor
+         */
+        function TransactionCapabilityDecorator(
             $q,
             transactionService,
-            dirtyModelCache,
             capabilityService
         ) {
             this.capabilityService = capabilityService;
             this.transactionService = transactionService;
-            this.dirtyModelCache = dirtyModelCache;
             this.$q = $q;
         }
 
         /**
-         * Decorate PersistenceCapability to ignore persistence calls when a
+         * Decorate PersistenceCapability to queue persistence calls when a
          * transaction is in progress.
          */
-        TransactionDecorator.prototype.getCapabilities = function (model) {
+        TransactionCapabilityDecorator.prototype.getCapabilities = function (model) {
             var self = this,
                 capabilities = this.capabilityService.getCapabilities(model),
                 persistenceCapability = capabilities.persistence;
@@ -55,7 +62,6 @@ define(
                 return new TransactionalPersistenceCapability(
                     self.$q,
                     self.transactionService,
-                    self.dirtyModelCache,
                     original,
                     domainObject
                 );
@@ -63,6 +69,6 @@ define(
             return capabilities;
         };
 
-        return TransactionDecorator;
+        return TransactionCapabilityDecorator;
     }
 );

platform/commonUI/edit/src/capabilities/TransactionalPersistenceCapability.js

@@ -26,44 +26,51 @@ define(
     function () {
         'use strict';
 
+        /**
+         * Wraps persistence capability to enable transactions. Transactions
+         * will cause persist calls not to be invoked immediately, but
+         * rather queued until [EditorCapability.save()]{@link EditorCapability#save}
+         * or [EditorCapability.cancel()]{@link EditorCapability#cancel} are
+         * called.
+         * @memberof platform/commonUI/edit/capabilities
+         * @param $q
+         * @param transactionService
+         * @param persistenceCapability
+         * @param domainObject
+         * @constructor
+         */
         function TransactionalPersistenceCapability(
             $q,
             transactionService,
-            dirtyModelCache,
             persistenceCapability,
             domainObject
         ) {
             this.transactionService = transactionService;
-            this.dirtyModelCache = dirtyModelCache;
-            this.persistenceCapability = Object.create(persistenceCapability);
+            this.persistenceCapability = persistenceCapability;
             this.domainObject = domainObject;
             this.$q = $q;
         }
 
+        /**
+         * The wrapped persist function. If a transaction is active, persist
+         * will be queued until the transaction is committed or cancelled.
+         * @returns {*}
+         */
         TransactionalPersistenceCapability.prototype.persist = function () {
-            var domainObject = this.domainObject,
-                dirtyModelCache = this.dirtyModelCache;
-            if (this.transactionService.isActive() && !this.transactionService.isCommitting()) {
-                dirtyModelCache.markDirty(domainObject);
-                //Using $q here because need to return something
-                // from which 'catch' can be chained
+            if (this.transactionService.isActive()) {
+                this.transactionService.addToTransaction(
+                    this.persistenceCapability.persist.bind(this.persistenceCapability),
+                    this.persistenceCapability.refresh.bind(this.persistenceCapability)
+                );
+                //Need to return a promise from this function
                 return this.$q.when(true);
             } else {
-                return this.persistenceCapability.persist().then(function (result) {
-                    dirtyModelCache.markClean(domainObject);
-                    return result;
-                });
+                return this.persistenceCapability.persist();
             }
         };
 
         TransactionalPersistenceCapability.prototype.refresh = function () {
-            var domainObject = this.domainObject,
-                dirtyModelCache = this.dirtyModelCache;
-
-            return this.persistenceCapability.refresh().then(function (result) {
-                dirtyModelCache.markClean(domainObject);
-                return result;
-            });
+            return this.persistenceCapability.refresh();
         };
 
         TransactionalPersistenceCapability.prototype.getSpace = function () {