• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<!--
2@license
3Copyright (c) 2015 The Polymer Project Authors. All rights reserved.
4This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
5The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
6The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
7Code distributed by Google as part of the polymer project is also
8subject 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-a11y-announcer` is a singleton element that is intended to add a11y
15to features that require on-demand announcement from screen readers. In
16order to make use of the announcer, it is best to request its availability
17in the announcing element.
18
19Example:
20
21    Polymer({
22
23      is: 'x-chatty',
24
25      attached: function() {
26        // This will create the singleton element if it has not
27        // been created yet:
28        Polymer.IronA11yAnnouncer.requestAvailability();
29      }
30    });
31
32After the `iron-a11y-announcer` has been made available, elements can
33make announces by firing bubbling `iron-announce` events.
34
35Example:
36
37    this.fire('iron-announce', {
38      text: 'This is an announcement!'
39    }, { bubbles: true });
40
41Note: announcements are only audible if you have a screen reader enabled.
42
43@group Iron Elements
44@demo demo/index.html
45-->
46
47<dom-module id="iron-a11y-announcer">
48  <style>
49    :host {
50      display: inline-block;
51      position: fixed;
52      clip: rect(0px,0px,0px,0px);
53    }
54  </style>
55
56  <template>
57    <div aria-live$="[[mode]]">[[_text]]</div>
58  </template>
59
60  <script>
61
62    (function() {
63      'use strict';
64
65      Polymer.IronA11yAnnouncer = Polymer({
66        is: 'iron-a11y-announcer',
67
68        properties: {
69
70          /**
71           * The value of mode is used to set the `aria-live` attribute
72           * for the element that will be announced. Valid values are: `off`,
73           * `polite` and `assertive`.
74           */
75          mode: {
76            type: String,
77            value: 'polite'
78          },
79
80          _text: {
81            type: String,
82            value: ''
83          }
84        },
85
86        created: function() {
87          if (!Polymer.IronA11yAnnouncer.instance) {
88            Polymer.IronA11yAnnouncer.instance = this;
89          }
90
91          document.body.addEventListener('iron-announce', this._onIronAnnounce.bind(this));
92        },
93
94        /**
95         * Cause a text string to be announced by screen readers.
96         *
97         * @param {string} text The text that should be announced.
98         */
99        announce: function(text) {
100          this._text = '';
101          this.async(function() {
102            this._text = text;
103          }, 100);
104        },
105
106        _onIronAnnounce: function(event) {
107          if (event.detail && event.detail.text) {
108            this.announce(event.detail.text);
109          }
110        }
111      });
112
113      Polymer.IronA11yAnnouncer.instance = null;
114
115      Polymer.IronA11yAnnouncer.requestAvailability = function() {
116        if (!Polymer.IronA11yAnnouncer.instance) {
117          Polymer.IronA11yAnnouncer.instance = document.createElement('iron-a11y-announcer');
118        }
119
120        document.body.appendChild(Polymer.IronA11yAnnouncer.instance);
121      };
122    })();
123
124  </script>
125</dom-module>
126