third_party/polymer/v1_0/components/iron-meta/iron-meta.html

   1 <!--
   2 @license
   3 Copyright (c) 2015 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="../polymer/polymer.html">
  12
  13 <!--
  14 `iron-meta` is a generic element you can use for sharing information across the DOM tree.
  15 It uses [monostate pattern](http://c2.com/cgi/wiki?MonostatePattern) such that any
  16 instance of iron-meta has access to the shared
  17 information. You can use `iron-meta` to share whatever you want (or create an extension
  18 [like x-meta] for enhancements).
  19
  20 The `iron-meta` instances containing your actual data can be loaded in an import,
  21 or constructed in any way you see fit. The only requirement is that you create them
  22 before you try to access them.
  23
  24 Examples:
  25
  26 If I create an instance like this:
  27
  28     <iron-meta key="info" value="foo/bar"></iron-meta>
  29
  30 Note that value="foo/bar" is the metadata I've defined. I could define more
  31 attributes or use child nodes to define additional metadata.
  32
  33 Now I can access that element (and it's metadata) from any iron-meta instance
  34 via the byKey method, e.g.
  35
  36     meta.byKey('info').getAttribute('value').
  37
  38 Pure imperative form would be like:
  39
  40     document.createElement('iron-meta').byKey('info').getAttribute('value');
  41
  42 Or, in a Polymer element, you can include a meta in your template:
  43
  44     <iron-meta id="meta"></iron-meta>
  45     ...
  46     this.$.meta.byKey('info').getAttribute('value');
  47
  48 @group Iron Elements
  49 @demo demo/index.html
  50 @hero hero.svg
  51 @element iron-meta
  52 -->
  53
  54 <script>
  55
  56   (function() {
  57
  58     // monostate data
  59     var metaDatas = {};
  60     var metaArrays = {};
  61
  62     Polymer.IronMeta = Polymer({
  63
  64       is: 'iron-meta',
  65
  66       properties: {
  67
  68         /**
  69          * The type of meta-data.  All meta-data of the same type is stored
  70          * together.
  71          */
  72         type: {
  73           type: String,
  74           value: 'default',
  75           observer: '_typeChanged'
  76         },
  77
  78         /**
  79          * The key used to store `value` under the `type` namespace.
  80          */
  81         key: {
  82           type: String,
  83           observer: '_keyChanged'
  84         },
  85
  86         /**
  87          * The meta-data to store or retrieve.
  88          */
  89         value: {
  90           type: Object,
  91           notify: true,
  92           observer: '_valueChanged'
  93         },
  94
  95         /**
  96          * If true, `value` is set to the iron-meta instance itself.
  97          */
  98          self: {
  99           type: Boolean,
 100           observer: '_selfChanged'
 101         },
 102
 103         /**
 104          * Array of all meta-data values for the given type.
 105          */
 106         list: {
 107           type: Array,
 108           notify: true
 109         }
 110
 111       },
 112
 113       /**
 114        * Only runs if someone invokes the factory/constructor directly
 115        * e.g. `new Polymer.IronMeta()`
 116        */
 117       factoryImpl: function(config) {
 118         if (config) {
 119           for (var n in config) {
 120             switch(n) {
 121               case 'type':
 122               case 'key':
 123               case 'value':
 124                 this[n] = config[n];
 125                 break;
 126             }
 127           }
 128         }
 129       },
 130
 131       created: function() {
 132         // TODO(sjmiles): good for debugging?
 133         this._metaDatas = metaDatas;
 134         this._metaArrays = metaArrays;
 135       },
 136
 137       _keyChanged: function(key, old) {
 138         this._resetRegistration(old);
 139       },
 140
 141       _valueChanged: function(value) {
 142         this._resetRegistration(this.key);
 143       },
 144
 145       _selfChanged: function(self) {
 146         if (self) {
 147           this.value = this;
 148         }
 149       },
 150
 151       _typeChanged: function(type) {
 152         this._unregisterKey(this.key);
 153         if (!metaDatas[type]) {
 154           metaDatas[type] = {};
 155         }
 156         this._metaData = metaDatas[type];
 157         if (!metaArrays[type]) {
 158           metaArrays[type] = [];
 159         }
 160         this.list = metaArrays[type];
 161         this._registerKeyValue(this.key, this.value);
 162       },
 163
 164       /**
 165        * Retrieves meta data value by key.
 166        *
 167        * @method byKey
 168        * @param {string} key The key of the meta-data to be returned.
 169        * @return {*}
 170        */
 171       byKey: function(key) {
 172         return this._metaData && this._metaData[key];
 173       },
 174
 175       _resetRegistration: function(oldKey) {
 176         this._unregisterKey(oldKey);
 177         this._registerKeyValue(this.key, this.value);
 178       },
 179
 180       _unregisterKey: function(key) {
 181         this._unregister(key, this._metaData, this.list);
 182       },
 183
 184       _registerKeyValue: function(key, value) {
 185         this._register(key, value, this._metaData, this.list);
 186       },
 187
 188       _register: function(key, value, data, list) {
 189         if (key && data && value !== undefined) {
 190           data[key] = value;
 191           list.push(value);
 192         }
 193       },
 194
 195       _unregister: function(key, data, list) {
 196         if (key && data) {
 197           if (key in data) {
 198             var value = data[key];
 199             delete data[key];
 200             this.arrayDelete(list, value);
 201           }
 202         }
 203       }
 204
 205     });
 206
 207     /**
 208     `iron-meta-query` can be used to access infomation stored in `iron-meta`.
 209
 210     Examples:
 211
 212     If I create an instance like this:
 213
 214         <iron-meta key="info" value="foo/bar"></iron-meta>
 215
 216     Note that value="foo/bar" is the metadata I've defined. I could define more
 217     attributes or use child nodes to define additional metadata.
 218
 219     Now I can access that element (and it's metadata) from any `iron-meta-query` instance:
 220
 221          var value = new Polymer.IronMetaQuery({key: 'info'}).value;
 222
 223     @group Polymer Iron Elements
 224     @element iron-meta-query
 225     */
 226     Polymer.IronMetaQuery = Polymer({
 227
 228       is: 'iron-meta-query',
 229
 230       properties: {
 231
 232         /**
 233          * The type of meta-data.  All meta-data of the same type is stored
 234          * together.
 235          */
 236         type: {
 237           type: String,
 238           value: 'default',
 239           observer: '_typeChanged'
 240         },
 241
 242         /**
 243          * Specifies a key to use for retrieving `value` from the `type`
 244          * namespace.
 245          */
 246         key: {
 247           type: String,
 248           observer: '_keyChanged'
 249         },
 250
 251         /**
 252          * The meta-data to store or retrieve.
 253          */
 254         value: {
 255           type: Object,
 256           notify: true,
 257           readOnly: true
 258         },
 259
 260         /**
 261          * Array of all meta-data values for the given type.
 262          */
 263         list: {
 264           type: Array,
 265           notify: true
 266         }
 267
 268       },
 269
 270       /**
 271        * Actually a factory method, not a true constructor. Only runs if
 272        * someone invokes it directly (via `new Polymer.IronMeta()`);
 273        */
 274       factoryImpl: function(config) {
 275         if (config) {
 276           for (var n in config) {
 277             switch(n) {
 278               case 'type':
 279               case 'key':
 280                 this[n] = config[n];
 281                 break;
 282             }
 283           }
 284         }
 285       },
 286
 287       created: function() {
 288         // TODO(sjmiles): good for debugging?
 289         this._metaDatas = metaDatas;
 290         this._metaArrays = metaArrays;
 291       },
 292
 293       _keyChanged: function(key) {
 294         this._setValue(this._metaData && this._metaData[key]);
 295       },
 296
 297       _typeChanged: function(type) {
 298         this._metaData = metaDatas[type];
 299         this.list = metaArrays[type];
 300         if (this.key) {
 301           this._keyChanged(this.key);
 302         }
 303       },
 304
 305       /**
 306        * Retrieves meta data value by key.
 307        * @param {string} key The key of the meta-data to be returned.
 308        * @return {*}
 309        */
 310       byKey: function(key) {
 311         return this._metaData && this._metaData[key];
 312       }
 313
 314     });
 315
 316   })();
 317 </script>