gitweb.starshipfights.net Git - factbooks/blob

   1 <!--
   2 @license
   3 Copyright (c) 2017 The Polymer Project Authors. All rights reserved.
   4 This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
   5 The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
   6 The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
   7 Code distributed by Google as part of the polymer project is also
   8 subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
   9 -->
  10
  11 <link rel="import" href="../mixins/mutable-data.html">
  12
  13 <script>
  14 (function() {
  15   'use strict';
  16
  17   let mutablePropertyChange = Polymer.MutableData._mutablePropertyChange;
  18
  19   /**
  20    * Legacy element behavior to skip strict dirty-checking for objects and arrays,
  21    * (always consider them to be "dirty") for use on legacy API Polymer elements.
  22    *
  23    * By default, `Polymer.PropertyEffects` performs strict dirty checking on
  24    * objects, which means that any deep modifications to an object or array will
  25    * not be propagated unless "immutable" data patterns are used (i.e. all object
  26    * references from the root to the mutation were changed).
  27    *
  28    * Polymer also provides a proprietary data mutation and path notification API
  29    * (e.g. `notifyPath`, `set`, and array mutation API's) that allow efficient
  30    * mutation and notification of deep changes in an object graph to all elements
  31    * bound to the same object graph.
  32    *
  33    * In cases where neither immutable patterns nor the data mutation API can be
  34    * used, applying this mixin will cause Polymer to skip dirty checking for
  35    * objects and arrays (always consider them to be "dirty").  This allows a
  36    * user to make a deep modification to a bound object graph, and then either
  37    * simply re-set the object (e.g. `this.items = this.items`) or call `notifyPath`
  38    * (e.g. `this.notifyPath('items')`) to update the tree.  Note that all
  39    * elements that wish to be updated based on deep mutations must apply this
  40    * mixin or otherwise skip strict dirty checking for objects/arrays.
  41    *
  42    * In order to make the dirty check strategy configurable, see
  43    * `Polymer.OptionalMutableDataBehavior`.
  44    *
  45    * Note, the performance characteristics of propagating large object graphs
  46    * will be worse as opposed to using strict dirty checking with immutable
  47    * patterns or Polymer's path notification API.
  48    *
  49    * @polymerBehavior
  50    * @memberof Polymer
  51    * @summary Behavior to skip strict dirty-checking for objects and
  52    *   arrays
  53    */
  54   Polymer.MutableDataBehavior = {
  55
  56     /**
  57      * Overrides `Polymer.PropertyEffects` to provide option for skipping
  58      * strict equality checking for Objects and Arrays.
  59      *
  60      * This method pulls the value to dirty check against from the `__dataTemp`
  61      * cache (rather than the normal `__data` cache) for Objects.  Since the temp
  62      * cache is cleared at the end of a turn, this implementation allows
  63      * side-effects of deep object changes to be processed by re-setting the
  64      * same object (using the temp cache as an in-turn backstop to prevent
  65      * cycles due to 2-way notification).
  66      *
  67      * @param {string} property Property name
  68      * @param {*} value New property value
  69      * @param {*} old Previous property value
  70      * @return {boolean} Whether the property should be considered a change
  71      * @protected
  72      */
  73     _shouldPropertyChange(property, value, old) {
  74       return mutablePropertyChange(this, property, value, old, true);
  75     }
  76   };
  77
  78   /**
  79    * Legacy element behavior to add the optional ability to skip strict
  80    * dirty-checking for objects and arrays (always consider them to be
  81    * "dirty") by setting a `mutable-data` attribute on an element instance.
  82    *
  83    * By default, `Polymer.PropertyEffects` performs strict dirty checking on
  84    * objects, which means that any deep modifications to an object or array will
  85    * not be propagated unless "immutable" data patterns are used (i.e. all object
  86    * references from the root to the mutation were changed).
  87    *
  88    * Polymer also provides a proprietary data mutation and path notification API
  89    * (e.g. `notifyPath`, `set`, and array mutation API's) that allow efficient
  90    * mutation and notification of deep changes in an object graph to all elements
  91    * bound to the same object graph.
  92    *
  93    * In cases where neither immutable patterns nor the data mutation API can be
  94    * used, applying this mixin will allow Polymer to skip dirty checking for
  95    * objects and arrays (always consider them to be "dirty").  This allows a
  96    * user to make a deep modification to a bound object graph, and then either
  97    * simply re-set the object (e.g. `this.items = this.items`) or call `notifyPath`
  98    * (e.g. `this.notifyPath('items')`) to update the tree.  Note that all
  99    * elements that wish to be updated based on deep mutations must apply this
 100    * mixin or otherwise skip strict dirty checking for objects/arrays.
 101    *
 102    * While this behavior adds the ability to forgo Object/Array dirty checking,
 103    * the `mutableData` flag defaults to false and must be set on the instance.
 104    *
 105    * Note, the performance characteristics of propagating large object graphs
 106    * will be worse by relying on `mutableData: true` as opposed to using
 107    * strict dirty checking with immutable patterns or Polymer's path notification
 108    * API.
 109    *
 110    * @polymerBehavior
 111    * @memberof Polymer
 112    * @summary Behavior to optionally skip strict dirty-checking for objects and
 113    *   arrays
 114    */
 115   Polymer.OptionalMutableDataBehavior = {
 116
 117     properties: {
 118       /**
 119        * Instance-level flag for configuring the dirty-checking strategy
 120        * for this element.  When true, Objects and Arrays will skip dirty
 121        * checking, otherwise strict equality checking will be used.
 122        */
 123       mutableData: Boolean
 124     },
 125
 126     /**
 127      * Overrides `Polymer.PropertyEffects` to skip strict equality checking
 128      * for Objects and Arrays.
 129      *
 130      * Pulls the value to dirty check against from the `__dataTemp` cache
 131      * (rather than the normal `__data` cache) for Objects.  Since the temp
 132      * cache is cleared at the end of a turn, this implementation allows
 133      * side-effects of deep object changes to be processed by re-setting the
 134      * same object (using the temp cache as an in-turn backstop to prevent
 135      * cycles due to 2-way notification).
 136      *
 137      * @param {string} property Property name
 138      * @param {*} value New property value
 139      * @param {*} old Previous property value
 140      * @return {boolean} Whether the property should be considered a change
 141      * @protected
 142      */
 143     _shouldPropertyChange(property, value, old) {
 144       return mutablePropertyChange(this, property, value, old, this.mutableData);
 145     }
 146   };
 147
 148 })();
 149
 150 </script>