Merge branch 'feature/cleanModelUsingDestroyStrategy' of https://github.com/jbsaff/angular-schema-form into jbsaff-feature/cleanModelUsingDestroyStrategy

Author: davidlgj

docs/index.md

@@ -193,6 +193,7 @@ attribute which should be placed along side `sf-schema`.
 | formDefaults | an object that will be used as a default for all form definitions |
 | validationMessage | an object or a function that will be used as default validation message for all fields. See [Validation Messages](#validation-messages) for details. |
 | setSchemaDefaults | boolean, set to false an no defaults from the schema will be set on the model. |
+| destroyStrategy | the default strategy to use for cleaning the model when a form element is removed. see [destroyStrategy](#destroyStrategy) below |
 
 *formDefaults* is mostly useful for setting global [ngModelOptions](#ngmodeloptions)
 i.e. changing the entire form to validate on blur.
@@ -635,6 +636,7 @@ General options most field types can handle:
   labelHtmlClass: "street"     // CSS Class(es) to be added to the label of the field (or similar)
   copyValueTo: ["address.street"],     // Copy values to these schema keys.
   condition: "person.age < 18" // Show or hide field depending on an angular expression
+  destroyStrategy: null        // One of null, empty string, undefined, or 'retain'. Changes model on $destroy event.
 }
 ```
 
@@ -824,6 +826,15 @@ function FormCtrl($scope) {
 Note that arrays inside arrays won't work with conditions.
 
 
+### destroyStrategy
+By default, when a field is removed from the DOM and the $destroy event is broadcast, the schema-validate directive 
+will update the model to set the field value to undefined. This can be overridden by setting the destroyStrategy 
+on a field to one of null, empty string (""), undefined, or "retain". Any other value will be ignored and the default  
+behavior will apply. The empty string option only applies to fields that have a type of string; using the empty string 
+with other field types will just be set to the default destroyStrategy. If you'd like to set the destroyStrategy for 
+an entire form, add it to the [globalOptions](#global-options)
+
+
 
 
 Specific options and types

src/directives/decorators/bootstrap/checkboxes.html

@@ -9,7 +9,7 @@
              sf-changed="form"
              class="{{form.fieldHtmlClass}}"
              ng-model="titleMapValues[$index]"
-             schema-validate="form"
+             schema-vaidate="form"
              name="{{form.key.slice(-1)[0]}}">
       <span ng-bind-html="form.titleMap[$index].name"></span>
     </label>

src/directives/decorators/bootstrap/textarea.html

@@ -1,5 +1,5 @@
 <div class="form-group has-feedback {{form.htmlClass}} schema-form-textarea" ng-class="{'has-error': form.disableErrorState !== true && hasError(), 'has-success': form.disableSuccessState !== true &&  hasSuccess()}">
-  <label class="control-label {{form.labelHtmlClass}}" ng-class="{'sr-only': !showTitle()}" for="{{form.key.slice(-1)[0]}}">{{form.title}}</label>
+  <label class="{{form.labelHtmlClass}}" ng-class="{'sr-only': !showTitle()}" for="{{form.key.slice(-1)[0]}}">{{form.title}}</label>
 
   <textarea ng-if="!form.fieldAddonLeft && !form.fieldAddonRight"
             class="form-control {{form.fieldHtmlClass}}"

src/directives/schema-form.js

@@ -5,8 +5,8 @@ FIXME: real documentation
 
 angular.module('schemaForm')
        .directive('sfSchema',
-['$compile', 'schemaForm', 'schemaFormDecorators', 'sfSelect', 'sfPath',
-  function($compile,  schemaForm,  schemaFormDecorators, sfSelect, sfPath) {
+['$compile', 'schemaForm', 'schemaFormDecorators', 'sfSelect', 'sfPath', 'sfRetainModel',
+  function($compile,  schemaForm,  schemaFormDecorators, sfSelect, sfPath, sfRetainModel) {
 
     var SNAKE_CASE_REGEXP = /[A-Z]/g;
     var snakeCase = function(name, separator) {
@@ -161,6 +161,9 @@ angular.module('schemaForm')
           }
         });
 
+        scope.$on('$destroy', function() {
+          sfRetainModel.setFlag(true);
+        });
       }
     };
   }

src/directives/schema-validate.js

@@ -1,110 +1,190 @@
-angular.module('schemaForm').directive('schemaValidate', ['sfValidator', 'sfSelect', function(sfValidator, sfSelect) {
-  return {
-    restrict: 'A',
-    scope: false,
-    // We want the link function to be *after* the input directives link function so we get access
-    // the parsed value, ex. a number instead of a string
-    priority: 500,
-    require: 'ngModel',
-    link: function(scope, element, attrs, ngModel) {
-
-
-      // We need the ngModelController on several places,
-      // most notably for errors.
-      // So we emit it up to the decorator directive so it can put it on scope.
-      scope.$emit('schemaFormPropagateNgModelController', ngModel);
-
-      var error = null;
-
-      var getForm = function() {
-        if (!form) {
-          form = scope.$eval(attrs.schemaValidate);
-        }
-        return form;
-      };
-      var form   = getForm();
-      if (form.copyValueTo) {
-        ngModel.$viewChangeListeners.push(function() {
-          var paths = form.copyValueTo;
-          angular.forEach(paths, function(path) {
-            sfSelect(path, scope.model, ngModel.$modelValue);
+angular.module('schemaForm').directive('schemaValidate', ['sfValidator', 'sfSelect', 'sfUnselect', '$parse', 'sfRetainModel',
+  function(sfValidator, sfSelect, sfUnselect, $parse, sfRetainModel) {
+
+    return {
+      restrict: 'A',
+      scope: false,
+      // We want the link function to be *after* the input directives link function so we get access
+      // the parsed value, ex. a number instead of a string
+      priority: 500,
+      require: 'ngModel',
+      link: function(scope, element, attrs, ngModel) {
+
+        // We need the ngModelController on several places,
+        // most notably for errors.
+        // So we emit it up to the decorator directive so it can put it on scope.
+        scope.$emit('schemaFormPropagateNgModelController', ngModel);
+
+        var error = null;
+
+        var getForm = function() {
+          if (!form) {
+            form = scope.$eval(attrs.schemaValidate);
+          }
+          return form;
+        };
+        var form   = getForm();
+        if (form.copyValueTo) {
+          ngModel.$viewChangeListeners.push(function() {
+            var paths = form.copyValueTo;
+            angular.forEach(paths, function(path) {
+              sfSelect(path, scope.model, ngModel.$modelValue);
+            });
           });
-        });
-      }
+        }
 
-      // Validate against the schema.
+        // Validate against the schema.
 
-      var validate = function(viewValue) {
-        form = getForm();
-        //Still might be undefined
-        if (!form) {
-          return viewValue;
-        }
+        var validate = function(viewValue) {
+          form = getForm();
+          //Still might be undefined
+          if (!form) {
+            return viewValue;
+          }
 
-        // Omit TV4 validation
-        if (scope.options && scope.options.tv4Validation === false) {
-          return viewValue;
-        }
+          // Omit TV4 validation
+          if (scope.options && scope.options.tv4Validation === false) {
+            return viewValue;
+          }
 
-        var result =  sfValidator.validate(form, viewValue);
-        // Since we might have different tv4 errors we must clear all
-        // errors that start with tv4-
-        Object.keys(ngModel.$error)
+          var result =  sfValidator.validate(form, viewValue);
+          // Since we might have different tv4 errors we must clear all
+          // errors that start with tv4-
+          Object.keys(ngModel.$error)
               .filter(function(k) { return k.indexOf('tv4-') === 0; })
               .forEach(function(k) { ngModel.$setValidity(k, true); });
 
-        if (!result.valid) {
-          // it is invalid, return undefined (no model update)
-          ngModel.$setValidity('tv4-' + result.error.code, false);
-          error = result.error;
-          return undefined;
+          if (!result.valid) {
+            // it is invalid, return undefined (no model update)
+            ngModel.$setValidity('tv4-' + result.error.code, false);
+            error = result.error;
+            return undefined;
+          }
+          return viewValue;
+        };
+
+        // Custom validators, parsers, formatters etc
+        if (typeof form.ngModel === 'function') {
+          form.ngModel(ngModel);
         }
-        return viewValue;
-      };
 
-      // Custom validators, parsers, formatters etc
-      if (typeof form.ngModel === 'function') {
-        form.ngModel(ngModel);
-      }
+        ['$parsers', '$viewChangeListeners', '$formatters'].forEach(function(attr) {
+          if (form[attr] && ngModel[attr]) {
+            form[attr].forEach(function(fn) {
+              ngModel[attr].push(fn);
+            });
+          }
+        });
 
-      ['$parsers', '$viewChangeListeners', '$formatters'].forEach(function(attr) {
-        if (form[attr] && ngModel[attr]) {
-          form[attr].forEach(function(fn) {
-            ngModel[attr].push(fn);
-          });
-        }
-      });
+        ['$validators', '$asyncValidators'].forEach(function(attr) {
+          // Check if our version of angular has i, i.e. 1.3+
+          if (form[attr] && ngModel[attr]) {
+            angular.forEach(form[attr], function(fn, name) {
+              ngModel[attr][name] = fn;
+            });
+          }
+        });
 
-      ['$validators', '$asyncValidators'].forEach(function(attr) {
-        // Check if our version of angular has i, i.e. 1.3+
-        if (form[attr] && ngModel[attr]) {
-          angular.forEach(form[attr], function(fn, name) {
-            ngModel[attr][name] = fn;
-          });
-        }
-      });
-
-      // Get in last of the parses so the parsed value has the correct type.
-      // We don't use $validators since we like to set different errors depeding tv4 error codes
-      ngModel.$parsers.push(validate);
-
-      // Listen to an event so we can validate the input on request
-      scope.$on('schemaFormValidate', function() {
-        if (ngModel.$setDirty) {
-          // Angular 1.3+
-          ngModel.$setDirty();
-          validate(ngModel.$modelValue);
-        } else {
-          // Angular 1.2
-          ngModel.$setViewValue(ngModel.$viewValue);
+        // Get in last of the parses so the parsed value has the correct type.
+        // We don't use $validators since we like to set different errors depeding tv4 error codes
+        ngModel.$parsers.push(validate);
+
+        // Listen to an event so we can validate the input on request
+        scope.$on('schemaFormValidate', function() {
+          if (ngModel.$setDirty) {
+            // Angular 1.3+
+            ngModel.$setDirty();
+            validate(ngModel.$modelValue);
+          } else {
+            // Angular 1.2
+            ngModel.$setViewValue(ngModel.$viewValue);
+          }
+
+        });
+
+
+        var DEFAULT_DESTROY_STRATEGY = getGlobalOptionsDestroyStrategy();
+
+        function getGlobalOptionsDestroyStrategy() {
+          var defaultStrategy = undefined;
+          if (scope.options && scope.options.hasOwnProperty('destroyStrategy')) {
+            var globalOptionsDestroyStrategy = scope.options.destroyStrategy;
+            var isValidFormDefaultDestroyStrategy = (globalOptionsDestroyStrategy === undefined ||
+                                                    globalOptionsDestroyStrategy === '' ||
+                                                    globalOptionsDestroyStrategy === null ||
+                                                    globalOptionsDestroyStrategy === 'retain');
+            if (isValidFormDefaultDestroyStrategy) {
+              defaultStrategy = globalOptionsDestroyStrategy;
+            }
+            else {
+              console.warn('Unrecognized globalOptions destroyStrategy: %s \'%s\'. Used undefined instead.',
+                  typeof globalOptionsDestroyStrategy, globalOptionsDestroyStrategy);
+            }
+          }
+          return defaultStrategy;
         }
 
-      });
+        // Clean up the model when the corresponding form field is $destroy-ed.
+        // Default behavior can be supplied as a globalOption, and behavior can be overridden in the form definition.
+        scope.$on('$destroy', function() {
+
+          var form = getForm();
+          var conditionResult = $parse(form.condition);
+          var formModelNotRetained = !sfRetainModel.getFlag();
+
+          // If condition is defined and not satisfied and the sfSchema model should not be retained.
+          if (form.hasOwnProperty('condition') && !conditionResult(scope) && formModelNotRetained) {
+
+            // Either set in form definition, or as part of globalOptions.
+            var destroyStrategy =
+                !form.hasOwnProperty('destroyStrategy') ? DEFAULT_DESTROY_STRATEGY : form.destroyStrategy;
+            var schemaType = getSchemaType();
+
+            if (destroyStrategy && destroyStrategy !== 'retain') {
+              // Don't recognize the strategy, so give a warning.
+              console.warn('%s has defined unrecognized destroyStrategy: \'%s\'. Used default instead.',
+                  attrs.name, destroyStrategy);
+              destroyStrategy = DEFAULT_DESTROY_STRATEGY;
+            }
+            else if (schemaType !== 'string' && destroyStrategy === '') {
+              // Only 'string' type fields can have an empty string value as a valid option.
+              console.warn('%s attempted to use empty string destroyStrategy on non-string form type. ' +
+                  'Used default instead.', attrs.name);
+              destroyStrategy = DEFAULT_DESTROY_STRATEGY;
+            }
+
+            if (destroyStrategy === 'retain') {
+              return; // Valid option to avoid destroying data in the model.
+            }
+
+            destroyUsingStrategy(destroyStrategy);
+
+            function destroyUsingStrategy(strategy) {
+              var strategyIsDefined = (strategy === null || strategy === '' || strategy === undefined);
+              if (!strategyIsDefined) {
+                strategy = DEFAULT_DESTROY_STRATEGY;
+              }
+              sfUnselect(scope.form.key, scope.model, strategy);
+            }
+
+            function getSchemaType() {
+              var sType;
+              if (form.schema) {
+                sType = form.schema.type;
+              }
+              else {
+                sType = null;
+              }
+              return sType;
+            }
+          }
+        });
+
 
-      scope.schemaError = function() {
-        return error;
-      };
+        scope.schemaError = function() {
+          return error;
+        };
 
-    }
-  };
-}]);
+      }
+    };
+  }]);

src/services/retainModel.js

@@ -0,0 +1,37 @@
+angular.module('schemaForm').factory('sfRetainModel', function() {
+
+  var data = {retainModelFlag: false };
+
+  return {
+    /**
+     * @description
+     * Utility service to indicate if the sfSchema model should be retained.
+     * Set to true to prevent an operation that would have destroyed the model
+     * from doing so (such as wrapping the form in an ng-if).
+     *
+     * ex.
+     * var foo = sfRetainModel.getFlag();
+     *
+     * @returns {boolean} returns the current value of the retainModelFlag.
+     */
+    getFlag: function () {
+      return data.retainModelFlag;
+    },
+
+    /**
+     * @description
+     * Set the value of the retainModelFlag.
+     * True prevents cleaning the data in the model, while false follows the configured destroyStrategy.
+     *
+     * ex.
+     * var bar = sfRetainModel.setFlag(true);
+     *
+     * @param {boolean} value  The boolean value to set as the retainModelFlag
+     * @returns {boolean} returns the value of the retainModelFlag after toggling.
+     */
+    setFlag: function(value) {
+      data.retainModelFlag = value;
+      return data.retainModelFlag;
+    }
+  }
+});