third_party/polymer/components/core-signals/core-signals.html

   1 <!--
   2 Copyright (c) 2014 The Polymer Project Authors. All rights reserved.
   3 This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE
   4 The complete set of authors may be found at http://polymer.github.io/AUTHORS
   5 The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS
   6 Code distributed by Google as part of the polymer project is also
   7 subject to an additional IP rights grant found at http://polymer.github.io/PATENTS
   8 -->
   9 <link rel="import" href="../polymer/polymer.html">
  10
  11 <!--
  12 `core-signals` provides basic publish-subscribe functionality.
  13
  14 Note: avoid using `core-signals` whenever you can use
  15 a controller (parent element) to mediate communication
  16 instead.
  17
  18 To send a signal, fire a custom event of type `core-signal`, with
  19 a detail object containing `name` and `data` fields.
  20
  21     this.fire('core-signal', {name: 'hello', data: null});
  22
  23 To receive a signal, listen for `core-signal-<name>` event on a
  24 `core-signals` element.
  25
  26   <core-signals on-core-signal-hello="{{helloSignal}}">
  27
  28 You can fire a signal event from anywhere, and all
  29 `core-signals` elements will receive the event, regardless
  30 of where they are in DOM.
  31
  32 @group Polymer Core Elements
  33 @element core-signals
  34 @status stable
  35 @homepage github.io
  36 -->
  37 <polymer-element name="core-signals">
  38 <script>
  39 (function(){
  40
  41   Polymer({
  42     attached: function() {
  43       signals.push(this);
  44     },
  45     removed: function() {
  46       var i = signals.indexOf(this);
  47       if (i >= 0) {
  48         signals.splice(i, 1);
  49       }
  50     }
  51   });
  52
  53   // private shared database
  54   var signals = [];
  55
  56   // signal dispatcher
  57   function notify(name, data) {
  58     // convert generic-signal event to named-signal event
  59     var signal = new CustomEvent('core-signal-' + name, {
  60       // if signals bubble, it's easy to get confusing duplicates
  61       // (1) listen on a container on behalf of local child
  62       // (2) some deep child ignores the event and it bubbles
  63       //     up to said container
  64       // (3) local child event bubbles up to container
  65       // also, for performance, we avoid signals flying up the
  66       // tree from all over the place
  67       bubbles: false,
  68       detail: data
  69     });
  70     // dispatch named-signal to all 'signals' instances,
  71     // only interested listeners will react
  72     signals.forEach(function(s) {
  73       s.dispatchEvent(signal);
  74     });
  75   }
  76
  77   // signal listener at document
  78   document.addEventListener('core-signal', function(e) {
  79     notify(e.detail.name, e.detail.data);
  80   });
  81
  82 })();
  83 </script>
  84 </polymer-element>