Home | History | Annotate | Download | only in iron-a11y-announcer 
      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-a11y-announcer` is a singleton element that is intended to add a11y
     15 to features that require on-demand announcement from screen readers. In
     16 order to make use of the announcer, it is best to request its availability
     17 in the announcing element.
     18 
     19 Example:
     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 
     32 After the `iron-a11y-announcer` has been made available, elements can
     33 make announces by firing bubbling `iron-announce` events.
     34 
     35 Example:
     36 
     37     this.fire('iron-announce', {
     38       text: 'This is an announcement!'
     39     }, { bubbles: true });
     40 
     41 Note: 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