2 * Angular Material Design
3 * https://github.com/angular/material
7 (function( window, angular, undefined ){
12 * @name material.components.icon
16 angular.module('material.components.icon', [
19 .directive('mdIcon', mdIconDirective);
24 * @module material.components.icon
29 * The `<md-icon>` directive is an markup element useful for showing an icon based on a font-icon
30 * or a SVG. Icons are view-only elements that should not be used directly as buttons; instead nest a `<md-icon>`
31 * inside a `md-button` to add hover and click features.
33 * When using SVGs, both external SVGs (via URLs) or sets of SVGs [from icon sets] can be
34 * easily loaded and used.When use font-icons, developers must following three (3) simple steps:
37 * <li>Load the font library. e.g.<br/>
38 * <link href="https://fonts.googleapis.com/icon?family=Material+Icons"
39 * rel="stylesheet">
41 * <li> Use either (a) font-icon class names or (b) font ligatures to render the font glyph by using its textual name</li>
42 * <li> Use <md-icon md-font-icon="classname" /> or <br/>
43 * use <md-icon md-font-set="font library classname or alias"> textual_name </md-icon> or <br/>
44 * use <md-icon md-font-set="font library classname or alias"> numerical_character_reference </md-icon>
48 * Full details for these steps can be found:
51 * <li>http://google.github.io/material-design-icons/</li>
52 * <li>http://google.github.io/material-design-icons/#icon-font-for-the-web</li>
55 * The Material Design icon style <code>.material-icons</code> and the icon font references are published in
56 * Material Design Icons:
59 * <li>http://www.google.com/design/icons/</li>
60 * <li>https://www.google.com/design/icons/#ic_accessibility</li>
63 * <h2 id="material_design_icons">Material Design Icons</h2>
64 * Using the Material Design Icon-Selector, developers can easily and quickly search for a Material Design font-icon and
65 * determine its textual name and character reference code. Click on any icon to see the slide-up information
66 * panel with details regarding a SVG download or information on the font-icon usage.
68 * <a href="https://www.google.com/design/icons/#ic_accessibility" target="_blank" style="border-bottom:none;">
69 * <img src="https://cloud.githubusercontent.com/assets/210413/7902490/fe8dd14c-0780-11e5-98fb-c821cc6475e6.png"
70 * aria-label="Material Design Icon-Selector" style="max-width:75%;padding-left:10%">
73 * <span class="image_caption">
74 * Click on the image above to link to the
75 * <a href="https://www.google.com/design/icons/#ic_accessibility" target="_blank">Material Design Icon-Selector</a>.
78 * @param {string} md-font-icon Name of CSS icon associated with the font-face will be used
79 * to render the icon. Requires the fonts and the named CSS styles to be preloaded.
80 * @param {string} md-font-set CSS style name associated with the font library; which will be assigned as
81 * the class for the font-icon ligature. This value may also be an alias that is used to lookup the classname;
82 * internally use `$mdIconProvider.fontSet(<alias>)` to determine the style name.
83 * @param {string} md-svg-src URL [or expression ] used to load, cache, and display an external SVG.
84 * @param {string} md-svg-icon Name used for lookup of the icon from the internal cache; interpolated strings or
85 * expressions may also be used. Specific set names can be used with the syntax `<set name>:<icon name>`.<br/><br/>
86 * To use icon sets, developers are required to pre-register the sets using the `$mdIconProvider` service.
87 * @param {string=} aria-label Labels icon for accessibility. If an empty string is provided, icon
88 * will be hidden from accessibility layer with `aria-hidden="true"`. If there's no aria-label on the icon
89 * nor a label on the parent element, a warning will be logged to the console.
95 * <!-- Icon ID; may contain optional icon set prefix; icons must registered using $mdIconProvider -->
96 * <md-icon md-svg-icon="social:android" aria-label="android " ></md-icon>
98 * <!-- Icon urls; may be preloaded in templateCache -->
99 * <md-icon md-svg-src="/android.svg" aria-label="android " ></md-icon>
100 * <md-icon md-svg-src="{{ getAndroid() }}" aria-label="android " ></md-icon>
104 * Use the <code>$mdIconProvider</code> to configure your application with
108 * angular.module('appSvgIconSets', ['ngMaterial'])
109 * .controller('DemoCtrl', function($scope) {})
110 * .config(function($mdIconProvider) {
112 * .iconSet('social', 'img/icons/sets/social-icons.svg', 24)
113 * .defaultIconSet('img/icons/sets/core-icons.svg', 24);
118 * When using Font Icons with classnames:
121 * <md-icon md-font-icon="android" aria-label="android" ></md-icon>
122 * <md-icon class="icon_home" aria-label="Home" ></md-icon>
126 * When using Material Font Icons with ligatures:
128 * <!-- For Material Design Icons -->
129 * <!-- The class '.material-icons' is auto-added. -->
130 * <md-icon> face </md-icon>
131 * <md-icon class="md-light md-48"> face </md-icon>
132 * <md-icon md-font-set="material-icons"> face </md-icon>
133 * <md-icon> #xE87C; </md-icon>
136 * When using other Font-Icon libraries:
139 * // Specify a font-icon style alias
140 * angular.config(function($mdIconProvider) {
141 * $mdIconProvider.fontSet('fa', 'fontawesome');
146 * <md-icon md-font-set="fa">email</md-icon>
150 function mdIconDirective($mdIcon, $mdTheming, $mdAria, $interpolate ) {
154 fontSet : '@mdFontSet',
155 fontIcon: '@mdFontIcon',
156 svgIcon : '@mdSvgIcon',
161 template: getTemplate,
165 function getTemplate(element, attr) {
166 var isEmptyAttr = function(key) { return angular.isDefined(attr[key]) ? attr[key].length == 0 : false },
167 hasAttrValue = function(key) { return attr[key] && attr[key].length > 0; },
168 attrValue = function(key) { return hasAttrValue(key) ? attr[key] : '' };
170 // If using the deprecated md-font-icon API
171 // If using ligature-based font-icons, transclude the ligature or NRCs
173 var tmplFontIcon = '<span class="md-font {{classNames}}" ng-class="fontIcon"></span>';
174 var tmplFontSet = '<span class="{{classNames}}" ng-transclude></span>';
176 var tmpl = hasAttrValue('mdSvgIcon') ? '' :
177 hasAttrValue('mdSvgSrc') ? '' :
178 isEmptyAttr('mdFontIcon') ? '' :
179 hasAttrValue('mdFontIcon') ? tmplFontIcon : tmplFontSet;
181 // If available, lookup the fontSet style and add to the list of classnames
182 // NOTE: Material Icons expects classnames like `.material-icons.md-48` instead of `.material-icons .md-48`
184 var names = (tmpl == tmplFontSet) ? $mdIcon.fontSet(attrValue('mdFontSet')) + ' ' : '';
185 names = (names + attrValue('class')).trim();
187 return $interpolate( tmpl )({ classNames: names });
193 * Supports embedded SVGs, font-icons, & external SVGs
195 function postLink(scope, element, attr) {
198 // If using a font-icon, then the textual name of the icon itself
199 // provides the aria-label.
201 var label = attr.alt || scope.fontIcon || scope.svgIcon || element.text();
202 var attrName = attr.$normalize(attr.$attr.mdSvgIcon || attr.$attr.mdSvgSrc || '');
204 if ( !attr['aria-label'] ) {
206 if (label != '' && !parentsHaveText() ) {
208 $mdAria.expect(element, 'aria-label', label);
209 $mdAria.expect(element, 'role', 'img');
211 } else if ( !element.text() ) {
212 // If not a font-icon with ligature, then
213 // hide from the accessibility layer.
215 $mdAria.expect(element, 'aria-hidden', 'true');
220 // Use either pre-configured SVG or URL source, respectively.
221 attr.$observe(attrName, function(attrVal) {
225 $mdIcon(attrVal).then(function(svg) {
232 function parentsHaveText() {
233 var parent = element.parent();
234 if (parent.attr('aria-label') || parent.text()) {
237 else if(parent.parent().attr('aria-label') || parent.parent().text()) {
244 mdIconDirective.$inject = ["$mdIcon", "$mdTheming", "$mdAria", "$interpolate"];
247 .module('material.components.icon' )
248 .provider('$mdIcon', MdIconProvider);
252 * @name $mdIconProvider
253 * @module material.components.icon
256 * `$mdIconProvider` is used only to register icon IDs with URLs. These configuration features allow
257 * icons and icon sets to be pre-registered and associated with source URLs **before** the `<md-icon />`
258 * directives are compiled.
260 * If using font-icons, the developer is repsonsible for loading the fonts.
262 * If using SVGs, loading of the actual svg files are deferred to on-demand requests and are loaded
263 * internally by the `$mdIcon` service using the `$http` service. When an SVG is requested by name/ID,
264 * the `$mdIcon` service searches its registry for the associated source URL;
265 * that URL is used to on-demand load and parse the SVG dynamically.
269 * app.config(function($mdIconProvider) {
271 * // Configure URLs for icons specified by [set:]id.
274 * .defaultFontSet( 'fontawesome' )
275 * .defaultIconSet('my/app/icons.svg') // Register a default set of SVG icons
276 * .iconSet('social', 'my/app/social.svg') // Register a named icon set of SVGs
277 * .icon('android', 'my/app/android.svg') // Register a specific icon (by name)
278 * .icon('work:chair', 'my/app/chair.svg'); // Register icon in a specific set
282 * SVG icons and icon sets can be easily pre-loaded and cached using either (a) a build process or (b) a runtime
283 * **startup** process (shown below):
286 * app.config(function($mdIconProvider) {
288 * // Register a default set of SVG icon definitions
289 * $mdIconProvider.defaultIconSet('my/app/icons.svg')
292 * .run(function($http, $templateCache){
294 * // Pre-fetch icons sources by URL and cache in the $templateCache...
295 * // subsequent $http calls will look there first.
297 * var urls = [ 'imy/app/icons.svg', 'img/icons/android.svg'];
299 * angular.forEach(urls, function(url) {
300 * $http.get(url, {cache: $templateCache});
307 * NOTE: the loaded SVG data is subsequently cached internally for future requests.
313 * @name $mdIconProvider#icon
316 * Register a source URL for a specific icon name; the name may include optional 'icon set' name prefix.
317 * These icons will later be retrieved from the cache using `$mdIcon( <icon name> )`
319 * @param {string} id Icon name/id used to register the icon
320 * @param {string} url specifies the external location for the data file. Used internally by `$http` to load the
321 * data or as part of the lookup in `$templateCache` if pre-loading was configured.
322 * @param {string=} iconSize Number indicating the width and height of the icons in the set. All icons
323 * in the icon set must be the same size. Default size is 24.
325 * @returns {obj} an `$mdIconProvider` reference; used to support method call chains for the API
329 * app.config(function($mdIconProvider) {
331 * // Configure URLs for icons specified by [set:]id.
334 * .icon('android', 'my/app/android.svg') // Register a specific icon (by name)
335 * .icon('work:chair', 'my/app/chair.svg'); // Register icon in a specific set
342 * @name $mdIconProvider#iconSet
345 * Register a source URL for a 'named' set of icons; group of SVG definitions where each definition
346 * has an icon id. Individual icons can be subsequently retrieved from this cached set using
347 * `$mdIcon(<icon set name>:<icon name>)`
349 * @param {string} id Icon name/id used to register the iconset
350 * @param {string} url specifies the external location for the data file. Used internally by `$http` to load the
351 * data or as part of the lookup in `$templateCache` if pre-loading was configured.
352 * @param {string=} iconSize Number indicating the width and height of the icons in the set. All icons
353 * in the icon set must be the same size. Default size is 24.
355 * @returns {obj} an `$mdIconProvider` reference; used to support method call chains for the API
360 * app.config(function($mdIconProvider) {
362 * // Configure URLs for icons specified by [set:]id.
365 * .iconSet('social', 'my/app/social.svg') // Register a named icon set
372 * @name $mdIconProvider#defaultIconSet
375 * Register a source URL for the default 'named' set of icons. Unless explicitly registered,
376 * subsequent lookups of icons will failover to search this 'default' icon set.
377 * Icon can be retrieved from this cached, default set using `$mdIcon(<name>)`
379 * @param {string} url specifies the external location for the data file. Used internally by `$http` to load the
380 * data or as part of the lookup in `$templateCache` if pre-loading was configured.
381 * @param {string=} iconSize Number indicating the width and height of the icons in the set. All icons
382 * in the icon set must be the same size. Default size is 24.
384 * @returns {obj} an `$mdIconProvider` reference; used to support method call chains for the API
388 * app.config(function($mdIconProvider) {
390 * // Configure URLs for icons specified by [set:]id.
393 * .defaultIconSet( 'my/app/social.svg' ) // Register a default icon set
400 * @name $mdIconProvider#defaultFontSet
403 * When using Font-Icons, Angular Material assumes the the Material Design icons will be used and automatically
404 * configures the default font-set == 'material-icons'. Note that the font-set references the font-icon library
405 * class style that should be applied to the `<md-icon>`.
407 * Configuring the default means that the attributes
408 * `md-font-set="material-icons"` or `class="material-icons"` do not need to be explicitly declared on the
409 * `<md-icon>` markup. For example:
411 * `<md-icon> face </md-icon>`
413 * `<span class="material-icons"> face </span>`, and
415 * `<md-icon md-font-set="fa"> face </md-icon>`
417 * `<span class="fa"> face </span>`
419 * @param {string} name of the font-library style that should be applied to the md-icon DOM element
423 * app.config(function($mdIconProvider) {
424 * $mdIconProvider.defaultFontSet( 'fontawesome' );
432 * @name $mdIconProvider#defaultIconSize
435 * While `<md-icon />` markup can also be style with sizing CSS, this method configures
436 * the default width **and** height used for all icons; unless overridden by specific CSS.
437 * The default sizing is (24px, 24px).
439 * @param {string} iconSize Number indicating the width and height of the icons in the set. All icons
440 * in the icon set must be the same size. Default size is 24.
442 * @returns {obj} an `$mdIconProvider` reference; used to support method call chains for the API
446 * app.config(function($mdIconProvider) {
448 * // Configure URLs for icons specified by [set:]id.
451 * .defaultIconSize(36) // Register a default icon size (width == height)
459 defaultFontSet: 'material-icons',
463 function MdIconProvider() { }
465 MdIconProvider.prototype = {
467 icon : function icon(id, url, iconSize) {
468 if ( id.indexOf(':') == -1 ) id = '$default:' + id;
470 config[id] = new ConfigurationItem(url, iconSize );
473 iconSet : function iconSet(id, url, iconSize) {
474 config[id] = new ConfigurationItem(url, iconSize );
477 defaultIconSet : function defaultIconSet(url, iconSize) {
478 var setName = '$default';
480 if ( !config[setName] ) {
481 config[setName] = new ConfigurationItem(url, iconSize );
484 config[setName].iconSize = iconSize || config.defaultIconSize;
489 * Register an alias name associated with a font-icon library style ;
491 fontSet : function fontSet(alias, className) {
492 config.fontSets.push({
494 fontSet : className || alias
499 * Specify a default style name associated with a font-icon library
500 * fallback to Material Icons.
503 defaultFontSet : function defaultFontSet(className) {
504 config.defaultFontSet = !className ? '' : className;
508 defaultIconSize : function defaultIconSize(iconSize) {
509 config.defaultIconSize = iconSize;
513 preloadIcons: function ($templateCache) {
514 var iconProvider = this;
517 id : 'md-tabs-arrow',
518 url: 'md-tabs-arrow.svg',
519 svg: '<svg version="1.1" x="0px" y="0px" viewBox="0 0 24 24"><g><polygon points="15.4,7.4 14,6 8,12 14,18 15.4,16.6 10.8,12 "/></g></svg>'
524 svg: '<svg version="1.1" x="0px" y="0px" viewBox="0 0 24 24"><g><path d="M19 6.41l-1.41-1.41-5.59 5.59-5.59-5.59-1.41 1.41 5.59 5.59-5.59 5.59 1.41 1.41 5.59-5.59 5.59 5.59 1.41-1.41-5.59-5.59z"/></g></svg>'
528 url: 'md-cancel.svg',
529 svg: '<svg version="1.1" x="0px" y="0px" viewBox="0 0 24 24"><g><path d="M12 2c-5.53 0-10 4.47-10 10s4.47 10 10 10 10-4.47 10-10-4.47-10-10-10zm5 13.59l-1.41 1.41-3.59-3.59-3.59 3.59-1.41-1.41 3.59-3.59-3.59-3.59 1.41-1.41 3.59 3.59 3.59-3.59 1.41 1.41-3.59 3.59 3.59 3.59z"/></g></svg>'
534 svg: '<svg version="1.1" x="0px" y="0px" viewBox="0 0 100 100"><path d="M 50 0 L 100 14 L 92 80 L 50 100 L 8 80 L 0 14 Z" fill="#b2b2b2"></path><path d="M 50 5 L 6 18 L 13.5 77 L 50 94 Z" fill="#E42939"></path><path d="M 50 5 L 94 18 L 86.5 77 L 50 94 Z" fill="#B72833"></path><path d="M 50 7 L 83 75 L 72 75 L 65 59 L 50 59 L 50 50 L 61 50 L 50 26 Z" fill="#b2b2b2"></path><path d="M 50 7 L 17 75 L 28 75 L 35 59 L 50 59 L 50 50 L 39 50 L 50 26 Z" fill="#fff"></path></svg>'
537 id: 'md-toggle-arrow',
538 url: 'md-toggle-arrow-svg',
539 svg: '<svg version="1.1" x="0px" y="0px" viewBox="0 0 48 48"><path d="M24 16l-12 12 2.83 2.83 9.17-9.17 9.17 9.17 2.83-2.83z"/><path d="M0 0h48v48h-48z" fill="none"/></svg>'
543 svgRegistry.forEach(function(asset){
544 iconProvider.icon(asset.id, asset.url);
545 $templateCache.put(asset.url, asset.svg);
550 $get : ['$http', '$q', '$log', '$templateCache', function($http, $q, $log, $templateCache) {
551 this.preloadIcons($templateCache);
552 return MdIconService(config, $http, $q, $log, $templateCache);
557 * Configuration item stored in the Icon registry; used for lookups
558 * to load if not already cached in the `loaded` cache
560 function ConfigurationItem(url, iconSize) {
562 this.iconSize = iconSize || config.defaultIconSize;
568 * @module material.components.icon
571 * The `$mdIcon` service is a function used to lookup SVG icons.
573 * @param {string} id Query value for a unique Id or URL. If the argument is a URL, then the service will retrieve the icon element
574 * from its internal cache or load the icon and cache it first. If the value is not a URL-type string, then an ID lookup is
575 * performed. The Id may be a unique icon ID or may include an iconSet ID prefix.
577 * For the **id** query to work properly, this means that all id-to-URL mappings must have been previously configured
578 * using the `$mdIconProvider`.
580 * @returns {obj} Clone of the initial SVG DOM element; which was created from the SVG markup in the SVG data file.
584 * function SomeDirective($mdIcon) {
586 * // See if the icon has already been loaded, if not
587 * // then lookup the icon from the registry cache, load and cache
588 * // it for future requests.
589 * // NOTE: ID queries require configuration with $mdIconProvider
591 * $mdIcon('android').then(function(iconEl) { element.append(iconEl); });
592 * $mdIcon('work:chair').then(function(iconEl) { element.append(iconEl); });
594 * // Load and cache the external SVG using a URL
596 * $mdIcon('img/icons/android.svg').then(function(iconEl) {
597 * element.append(iconEl);
602 * NOTE: The `<md-icon /> ` directive internally uses the `$mdIcon` service to query, loaded, and instantiate
605 function MdIconService(config, $http, $q, $log, $templateCache) {
607 var urlRegex = /[-a-zA-Z0-9@:%_\+.~#?&//=]{2,256}\.[a-z]{2,4}\b(\/[-a-zA-Z0-9@:%_\+.~#?&//=]*)?/i;
609 Icon.prototype = { clone : cloneSVG, prepare: prepareAndStyle };
610 getIcon.fontSet = findRegisteredFontSet;
612 // Publish service...
616 * Actual $mdIcon service is essentially a lookup function
618 function getIcon(id) {
621 // If already loaded and cached, use a clone of the cached icon.
622 // Otherwise either load by URL, or lookup in the registry and then load by URL, and cache.
624 if ( iconCache[id] ) return $q.when( iconCache[id].clone() );
625 if ( urlRegex.test(id) ) return loadByURL(id).then( cacheIcon(id) );
626 if ( id.indexOf(':') == -1 ) id = '$default:' + id;
629 .catch(loadFromIconSet)
630 .catch(announceIdNotFound)
631 .catch(announceNotFound)
632 .then( cacheIcon(id) );
636 * Lookup registered fontSet style using its alias...
639 function findRegisteredFontSet(alias) {
640 var useDefault = angular.isUndefined(alias) || !(alias && alias.length);
641 if ( useDefault ) return config.defaultFontSet;
644 angular.forEach(config.fontSets, function(it){
645 if ( it.alias == alias ) result = it.fontSet || result;
652 * Prepare and cache the loaded icon for the specified `id`
654 function cacheIcon( id ) {
656 return function updateCache( icon ) {
657 iconCache[id] = isIcon(icon) ? icon : new Icon(icon, config[id]);
659 return iconCache[id].clone();
664 * Lookup the configuration in the registry, if !registered throw an error
665 * otherwise load the icon [on-demand] using the registered URL.
668 function loadByID(id) {
669 var iconConfig = config[id];
671 return !iconConfig ? $q.reject(id) : loadByURL(iconConfig.url).then(function(icon) {
672 return new Icon(icon, iconConfig);
677 * Loads the file as XML and uses querySelector( <id> ) to find
678 * the desired node...
680 function loadFromIconSet(id) {
681 var setName = id.substring(0, id.lastIndexOf(':')) || '$default';
682 var iconSetConfig = config[setName];
684 return !iconSetConfig ? $q.reject(id) : loadByURL(iconSetConfig.url).then(extractFromSet);
686 function extractFromSet(set) {
687 var iconName = id.slice(id.lastIndexOf(':') + 1);
688 var icon = set.querySelector('#' + iconName);
689 return !icon ? $q.reject(id) : new Icon(icon, iconSetConfig);
694 * Load the icon by URL (may use the $templateCache).
695 * Extract the data for later conversion to Icon
697 function loadByURL(url) {
699 .get(url, { cache: $templateCache })
700 .then(function(response) {
701 return angular.element('<div>').append(response.data).find('svg')[0];
706 * User did not specify a URL and the ID has not been registered with the $mdIcon
709 function announceIdNotFound(id) {
712 if (angular.isString(id)) {
713 msg = 'icon ' + id + ' not found';
717 return $q.reject(msg || id);
721 * Catch HTTP or generic errors not related to incorrect icon IDs.
723 function announceNotFound(err) {
724 var msg = angular.isString(err) ? err : (err.message || err.data || err.statusText);
727 return $q.reject(msg);
731 * Check target signature to see if it is an Icon instance.
733 function isIcon(target) {
734 return angular.isDefined(target.element) && angular.isDefined(target.config);
738 * Define the Icon class
740 function Icon(el, config) {
741 if (el.tagName != 'svg') {
742 el = angular.element('<svg xmlns="http://www.w3.org/2000/svg">').append(el)[0];
745 // Inject the namespace if not available...
746 if ( !el.getAttribute('xmlns') ) {
747 el.setAttribute('xmlns', "http://www.w3.org/2000/svg");
751 this.config = config;
756 * Prepare the DOM element that will be cached in the
757 * loaded iconCache store.
759 function prepareAndStyle() {
760 var iconSize = this.config ? this.config.iconSize : config.defaultIconSize;
765 'preserveAspectRatio': 'xMidYMid meet',
766 'viewBox' : this.element.getAttribute('viewBox') || ('0 0 ' + iconSize + ' ' + iconSize)
767 }, function(val, attr) {
768 this.element.setAttribute(attr, val);
772 'pointer-events' : 'none',
774 }, function(val, style) {
775 this.element.style[style] = val;
780 * Clone the Icon DOM element.
783 return this.element.cloneNode(true);
788 })(window, window.angular);