pvc-globals.html

<link rel="import" href="../polymer/polymer.html">

<!--
Document-wide globals with instant cross-element propagation.

##### Example

    <pvc-globals namespace="org" values="{{globals}}"></pvc-globals>

Globals are shared across all instances of the `pvc-globals` element, so
changing a value in one will be reflected in every other element with the
same namespace.

You can bind to the values directly, but you can also listen for events.
Each element will trigger a `pvc-globals-*` event with `*` being one of
`add`, `remove`, `change`, or `update`. The `update` event fires when
any of the other events happens and includes an `event` key in its detail
to tell you which.

    <pvc-globals on-pvc-globals-update="{{handleUpdate}}"></pvc-globals>

If you need to observe deeply nested global properties, you can register
them using the standard Polymer observe:

    <polymer-element name="globals-watcher">
      <template>
        <pvc-globals id='globals'></pvc-globals>
      </template>
      <script>
        Polymer('globals-watcher', {
          observe: {
            '$.globals.values.deep.key.to.watch': 'deepChange'
          },
          deepChange: function(){
            // ...
          }
        });
      </script>
    </polymer-element>

@element pvc-globals
@blurb Document-wide globals with instant cross-element propagation.
@status alpha
@homepage http://code.divshot.com/pvc-globals
-->
<polymer-element name="pvc-globals" attributes="namespace">
  <script>
    (function() {
      var _globals = {};
      var _observers = {};
      var _instances = [];
      
      var _fire = function(name, detail) {
        _instances.forEach(function(instance) {
          if (instance.namespace === detail.namespace) {
            instance.fire(name, detail);
          }
        });
      }
                               
      var _observeFn = function(namespace, added, removed, changed, getOldValueFn) {
        if (namespace === '__default'){ namespace = null; }
        Object.keys(added).forEach(function(prop) {
          var detail =  {
            event: 'add',
            namespace: namespace, 
            property: prop, 
            value: added[prop], 
            oldValue: getOldValueFn(prop)
          }
          _fire('pvc-globals-update', detail);
          _fire('pvc-globals-add', detail);
        });
          
        Object.keys(removed).forEach(function(prop) {
          var detail =  {
            event: 'remove',
            namespace: namespace, 
            property: prop, 
            value: undefined,
            oldValue: getOldValueFn(prop)
          }
          _fire('pvc-globals-update', detail);
          _fire('pvc-globals-remove', detail);
        });
          
        Object.keys(changed).forEach(function(prop) {
          var detail =  {
            event: 'change',
            namespace: namespace, 
            property: prop, 
            value: changed[prop], 
            oldValue: getOldValueFn(prop)
          }
          _fire('pvc-globals-update', detail);
          _fire('pvc-globals-change', detail);
        });
      }
      
      var _makeAndObserve = function(namespace) {
        _globals[namespace] || (_globals[namespace] = {});
        _observers[namespace] = new ObjectObserver(_globals[namespace]);
        _observers[namespace].open(function(a,r,c,o) {
          _observeFn(namespace,a,r,c,o);
        });
        return _globals[namespace];
      };
      
      Polymer('pvc-globals', {
        publish: {
          values: undefined
        },
        observe: {
          namespace: 'resetData'
        },
        
        /**
         * The (optional) `namespace` attribute lets you have multiple
         * scopes of globals.
         * 
         * @attribute namespace
         * @type string
         */
        namespace: undefined,

        /**
         * The `values` attribute is an object containing the set globals for
         * the current namespace. You can bind to this.
         * 
         * @attribute values
         * @type object
         */
        created: function() {
          _instances.push(this);
          this.resetData();
        },

        get _ns() {
          return this.namespace || '__default';
        },
        
        get values() {
          this.resetData();
          return _globals[this._ns];
        },
        
        set values(data) {
          throw "[pvc-globals] ERROR: Globals objects are immutable. You can only work on subkeys.";
        },
        
        resetData: function() {
          if (!_globals[this._ns]) {
            _makeAndObserve(this._ns);
          }
        }

        /**
         * The `pvc-globals-change` event is fired on each element whenever a
         * global variable is added. The detail is an object including the 
         * `namespace`, `property`, `value`, and `oldValue`.
         * 
         * @event pvc-globals-add
         */
         
        /**
         * The `pvc-globals-change` event is fired on each element whenever a
         * global variable is removed. The detail is an object including the 
         * `namespace`, `property`, `value`, and `oldValue`.
         * 
         * @event pvc-globals-remove
         */
        
        /**
         * The `pvc-globals-change` event is fired on each element whenever a
         * global variable is modified. The detail is an object including the 
         * `namespace`, `property`, `value`, `oldValue`.
         * 
         * @event pvc-globals-change
         */
        
        /**
         * The `pvc-globals-update` event is fired on each element whenever any
         * kind of alteration (add, remove, change) is made. The detail is an
         * object including the `namespace`, `property`, `value`, `oldValue`.
         * 
         * @event pvc-globals-update
         */

      });
    })();
  </script>
</polymer-element>