Components: md-icon docs should showcase how to use material icons easily

[andrewseguin]

Most users will likely go to the md-icon docs because they are just starting out with them. The easiest way to do this is to include the material icons fontset in their index.html. While the information to do so is in the docs, it does not stand out. Right now it looks like they'll need to integrate with the MdIconRegistry to get md-icon to work.

[v1d3rm3]

Can i separate the icons in two 'divisions'? When i was reading the docs, in my mental map, i separate in md-icon in two: native, when i'm using the Material Icons ( then we just need to load the fontset), and in custom, when i want to use external icons with md-icon, using MdIconRegistry, what do you think? So i was thinking in refactor the docs in these two modes.

[jelbourn]

As I see it, the split is between font icons and svg icons

[v1d3rm3]

Yes, but i was thinking in highlight the native support to material icons, because most of the users, i think, will just to use the native support in start, just to test. If we give highlight how to fast set up the md-icons, it'll be more effective.

Initially, we'll talk about the fast option (material icons), and after, we give details how to use "custom icons" ( font icons and svg icons ).

I'll soon open a pr.

[jelbourn]

@victorschinaider I don't follow what you mean in using the word "native". Using the material icons w/ md-icon is the same as using any other font icon set except for the fact that we set the default icon css class based on the material one. "Native" implies that it's something inherent to the browser platform.

[v1d3rm3]

@jelbourn I got it, thanks. I'm going to rephrase my thoughts based on that.

[M-a-c]

@victorschinaider are you going to open a pr for this?

[v1d3rm3]

@M-a-c, If you have something, feel free to open.
I've a material fork in my account with some modifications (https://github.com/victorschinaider/material2/blob/icon-docs/src/lib/icon/icon-temp.md), it's just a draft,
if you fell comfortable, we can discuss.

[M-a-c]

@victorschinaider Sure!
If there are parts you're not sure of let me know, we can discuss on your branch.
Also If you'd rather not do a part I can lookup/fillout the info for that section.
Let me know!

[alisaduncan]

I created 2 PRs to provide a couple of different ways to point users to the correct docs and examples. Please let me know if this is not the direction you were expecting and I can update.

[cpboyd]

Out of curiosity, is there a reason that the default method for Angular's Material icons is to use the icon font?

I only ask because there are certain instances where security policies (regardless of whether or not they make sense) completely block any web font.

Polymer's iron-icon element uses SVG:
https://github.com/PolymerElements/iron-icons/blob/master/iron-icons.html

It may make sense to split mat-icon and have a font version and an SVG version. (With separate modules that would each include the default Material icon font or SVG icon set respectively.)

[jelbourn]

I wouldn't say icon fonts are the default; when you do <mat-icon>home</mat-icon>, "home" is the text content because ligature icons _are_ text content. SVGs aren't equivalent, so they're set via property.

[cpboyd]

@jelbourn I was specifically referring to the Material Design icons related to https://material.io/icons/

I've just recently had a customer whose network specifically blocks web fonts.

I know that mat-icon can import an SVG icon set (like the ones that Polymer uses) using addSvgIconSet for the same icons that including the web font gives, so I was just wondering about the different rationales between Polymer and Angular.

Maybe it would be useful providing optional modules that include and register the SVG versions of the Material Design icons?

[jelbourn]

Our philosophy is to support both; the Material Design team is a separate entity that puts out the icons themselves.

[Stephane-Peyroutet]

I thought this issue was perfect to let you know that current links explaining how to use the Material icons font are broken :

• on the Overview tab, in the Font icons with ligatures paragraph
• on the API tab, in the Directives paragraph

The text from the API tab is good (http://google.github.io/material-design-icons/#icon-font-for-the-web) but the link is not (https://material.angular.io/components/icon/api#icon-font-for-the-web).
This is the same link that is used on the Overview tab.

[jelbourn]

@Stephane-Peyroutet can you file a separate issue for this? Looks like a bug with the API doc generation

[Stephane-Peyroutet]

@jelbourn Thanks for the quick answer.
I've just filed a separate issue : #8994, so you just can add the "docs" labels.