third_party/polymer/components/core-icon/core-icon.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.txt
   4 The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
   5 The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
   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.txt
   8 -->
   9 <!--
  10
  11 The `core-icon` element displays an icon. By default an icon renders as a 24px square.
  12
  13 Example using src:
  14
  15     <core-icon src="star.png"></core-icon>
  16
  17 Example setting size to 32px x 32px:
  18
  19     <core-icon class="big" src="big_star.png"></core-icon>
  20
  21     <style>
  22       .big {
  23         height: 32px;
  24         width: 32px;
  25       }
  26     </style>
  27
  28 The core elements include several sets of icons.
  29 To use the default set of icons, import  `core-icons.html` and use the `icon` attribute to specify an icon:
  30
  31     &lt;!-- import default iconset and core-icon --&gt;
  32     <link rel="import" href="/components/core-icons/core-icons.html">
  33
  34     <core-icon icon="menu"></core-icon>
  35
  36 To use a different built-in set of icons, import  `core-icons/<iconset>-icons.html`, and
  37 specify the icon as `<iconset>:<icon>`. For example:
  38
  39     &lt;!-- import communication iconset and core-icon --&gt;
  40     <link rel="import" href="/components/core-icons/communication-icons.html">
  41
  42     <core-icon icon="communication:email"></core-icon>
  43
  44 You can also create custom icon sets of bitmap or SVG icons.
  45
  46 Example of using an icon named `cherry` from a custom iconset with the ID `fruit`:
  47
  48     <core-icon icon="fruit:cherry"></core-icon>
  49
  50 See [core-iconset](#core-iconset) and [core-iconset-svg](#core-iconset-svg) for more information about
  51 how to create a custom iconset.
  52
  53 See [core-icons](http://www.polymer-project.org/components/core-icons/demo.html) for the default set of icons.
  54
  55 @group Polymer Core Elements
  56 @element core-icon
  57 @homepage polymer.github.io
  58 -->
  59 <link rel="import" href="../core-iconset/core-iconset.html">
  60
  61 <link rel="stylesheet" href="core-icon.css" shim-shadowdom>
  62
  63 <polymer-element name="core-icon" attributes="src icon alt">
  64 <script>
  65 (function() {
  66
  67   // mono-state
  68   var meta;
  69
  70   Polymer('core-icon', {
  71
  72     /**
  73      * The URL of an image for the icon. If the src property is specified,
  74      * the icon property should not be.
  75      *
  76      * @attribute src
  77      * @type string
  78      * @default ''
  79      */
  80     src: '',
  81
  82     /**
  83      * Specifies the icon name or index in the set of icons available in
  84      * the icon's icon set. If the icon property is specified,
  85      * the src property should not be.
  86      *
  87      * @attribute icon
  88      * @type string
  89      * @default ''
  90      */
  91     icon: '',
  92
  93     /**
  94      * Alternative text content for accessibility support.
  95      * If alt is present and not empty, it will set the element's role to img and add an aria-label whose content matches alt.
  96      * If alt is present and is an empty string, '', it will hide the element from the accessibility layer
  97      * If alt is not present, it will set the element's role to img and the element will fallback to using the icon attribute for its aria-label.
  98      *
  99      * @attribute alt
 100      * @type string
 101      * @default ''
 102      */
 103     alt: null,
 104
 105     observe: {
 106       'icon': 'updateIcon',
 107       'alt': 'updateAlt'
 108     },
 109
 110     defaultIconset: 'icons',
 111
 112     ready: function() {
 113       if (!meta) {
 114         meta = document.createElement('core-iconset');
 115       }
 116
 117       // Allow user-provided `aria-label` in preference to any other text alternative.
 118       if (this.hasAttribute('aria-label')) {
 119         // Set `role` if it has not been overridden.
 120         if (!this.hasAttribute('role')) {
 121           this.setAttribute('role', 'img');
 122         }
 123         return;
 124       }
 125       this.updateAlt();
 126     },
 127
 128     srcChanged: function() {
 129       var icon = this._icon || document.createElement('div');
 130       icon.textContent = '';
 131       icon.setAttribute('fit', '');
 132       icon.style.backgroundImage = 'url(' + this.src + ')';
 133       icon.style.backgroundPosition = 'center';
 134       icon.style.backgroundSize = '100%';
 135       if (!icon.parentNode) {
 136         this.appendChild(icon);
 137       }
 138       this._icon = icon;
 139     },
 140
 141     getIconset: function(name) {
 142       return meta.byId(name || this.defaultIconset);
 143     },
 144
 145     updateIcon: function(oldVal, newVal) {
 146       if (!this.icon) {
 147         this.updateAlt();
 148         return;
 149       }
 150       var parts = String(this.icon).split(':');
 151       var icon = parts.pop();
 152       if (icon) {
 153         var set = this.getIconset(parts.pop());
 154         if (set) {
 155           this._icon = set.applyIcon(this, icon);
 156           if (this._icon) {
 157             this._icon.setAttribute('fit', '');
 158           }
 159         }
 160       }
 161       // Check to see if we're using the old icon's name for our a11y fallback
 162       if (oldVal) {
 163         if (oldVal.split(':').pop() == this.getAttribute('aria-label')) {
 164           this.updateAlt();
 165         }
 166       }
 167     },
 168
 169     updateAlt: function() {
 170       // Respect the user's decision to remove this element from
 171       // the a11y tree
 172       if (this.getAttribute('aria-hidden')) {
 173         return;
 174       }
 175
 176       // Remove element from a11y tree if `alt` is empty, otherwise
 177       // use `alt` as `aria-label`.
 178       if (this.alt === '') {
 179         this.setAttribute('aria-hidden', 'true');
 180         if (this.hasAttribute('role')) {
 181           this.removeAttribute('role');
 182         }
 183         if (this.hasAttribute('aria-label')) {
 184           this.removeAttribute('aria-label');
 185         }
 186       } else {
 187         this.setAttribute('aria-label', this.alt ||
 188                                         this.icon.split(':').pop());
 189         if (!this.hasAttribute('role')) {
 190           this.setAttribute('role', 'img');
 191         }
 192         if (this.hasAttribute('aria-hidden')) {
 193           this.removeAttribute('aria-hidden');
 194         }
 195       }
 196     }
 197
 198   });
 199
 200 })();
 201 </script>
 202
 203 </polymer-element>