Migrate UsingFontIcons

2 files changed, 189 insertions, 0 deletions

diff --git a/documentation/articles/UsingFontIcons.asciidoc b/documentation/articles/UsingFontIcons.asciidoc
new file mode 100644
index 0000000000..81bd3ea075
--- /dev/null
+++ b/documentation/articles/UsingFontIcons.asciidoc
@@ -0,0 +1,188 @@
+[[using-font-icons-in-vaadin-7.2]]
+Using font icons in Vaadin 7.2
+------------------------------
+
+A “font icon” is an icon that is a glyph (essentially a character) from
+a font. A font that is made for this purpose (containing only icons) is
+called an “icon font”. Font icons scale well (being vectors), so you do
+not have to make icons for a specific pixel size. Icon fonts are also
+typically very light-weight (in bytes), and easy to use once set up.
+
+Vaadin 7.2 comes with generic support for font icons, and has the
+popular http://fortawesome.github.io/Font-Awesome/[FontAwesome] icon font
+built-in. The support is ‘generic’, in the sense that it does not
+include some of the advanced styling options specifically available in
+FontAwesome (such as spinning icons). 
+
+FontAwesome is included in the theme by default, but the fonts are only
+loaded by the browser when used. If needed, you can also remove the CSS,
+minimize the font, or make a custom font.
+
+A demo application showing the result is
+https://github.com/Porotype/FontIconDemo[available onGitHub] 
+(https://github.com/Porotype/FontIconDemo/tree/master/src/com/example/fonticondemo[java],
+https://github.com/Porotype/FontIconDemo/blob/master/WebContent/VAADIN/themes/fonticondemo/fonticondemo.scss[scss])
+
+[[using-fontawesome]]
+Using FontAwesome
+~~~~~~~~~~~~~~~~~
+
+You can use font icons with the familiar `setIcon()` method. It looks like
+this, when using the built-in FontAwesome:
+
+[source,java]
+....
+button.setIcon(FontAwesome.BOOKMARK);
+....
+
+You can also easily embed an icon in any place that allows HTML: 
+
+[source,java]
+....
+label.setContentMode(ContentMode.HTML);
+label.setValue("Press " + FontAwesome.BOOKMARK.getHtml() + " to bookmark");
+....
+
+[[making-a-custom-set-of-icons]]
+Making a custom set of icons
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are many tools for making icons, and icon fonts. One of our
+favourite tools is http://icomoon.io/app[IcoMoon], which is an excellent
+online application where you can pick icons from a vast library of
+ready-made icon fonts, to compose your own set of icons. When you’re
+done, you can download a zip that contains your font files - just copy
+the ‘fonts’ folder to your theme.
+
+1.  Browse to http://icomoon.io/app
+2.  _Add icons from library_ (the first time, some icons sets are added
+automatically)
+3.  _Add_ the icon set(s) you fancy (notice the licenses)
+4.  Mark the icons you want in your font
+5.  _Download_ the font
+
+In IcoMoon you can also produce a customised version of FontAwesome, if
+you for instance want to remove unused icons, or swap individual icons.
+You can also re-upload your custom icon font, if you want to make
+changes or additions to it later. 
+
+1.  _Import icons_
+2.  Add/delete/swap icons
+3.  _Download_ the new font
+
+When using ready-made icons, please pay attention to the licenses the
+different icon sets have.
+
+[[using-a-custom-icon-font]]
+Using a custom icon font
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use your own icon set, you need to do four things: 
+
+1.  Make an icon font
+2.  Make it easily usable from Java and
+3.  Load the font in your theme
+4.  Use the icons in your application.
+
+(You can skip #1 if you already have an icon font you want to use.)
+
+*1. Compose an icon font* in e.g IcoMoon, download, and copy the “fonts”
+folder from the zip to your theme.
+
+*2. Add the following to your styles.scss* OUTSIDE of the `.mytheme{}` block:
+
+[source,scss]
+....
+@include font(IcoMoon, '../../fonticondemo/fonts/icomoon');
+....
+
+The first parameter, “IcoMoon”, is the font-family - i.e the name you
+want to use for your font. You can choose anything, as long as you use
+the same name in Java later. +
+The second parameter is the filename base; in this case the files are
+called icomoon.ttf, icomoon.svg, etc...
+
+*3. Make use of the icons in Java;* you can make an anonymous FontIcon
+instance, but in practice you will probably want to make an enum or some
+sort of icon factory. The FontAwesome implementation uses an enum, in
+this manner:
+
+[source,java]
+....
+  private final int codepoint;
+
+  IcoMoon(int codepoint) {
+    this.codepoint = codepoint;
+  }
+
+  @Override
+  public String getFontFamily() {
+    // This must match the name you use in your (S)CSS
+    return "IcoMoon";
+  }
+
+  @Override
+  public int getCodepoint() {
+    return codepoint;
+  }
+
+  @Override
+  public String getHtml() {
+    return "<span class=\"v-icon IcoMoon\">&#x"
+        + Integer.toHexString(codepoint) + ";</span>";
+  }
+
+  @Override
+  public String getMIMEType() {
+    throw new UnsupportedOperationException("Not supported for FontIcon");
+  }
+....
+
+(Note that you can easily generate the enum from the list of icons in
+the zip downloaded from IcoMoon.)
+
+*4. Now you can use your icon:*
+
+[source,java]
+....
+  button.setIcon(IcoMoon.RIBBON);
+....
+
+[[styling-font-icons]]
+Styling font icons
+~~~~~~~~~~~~~~~~~~
+
+You can not generally set style names on the icon itself, instead you
+apply styles to the _component_ where the icon is used, much in the same
+way you would style anything else in a component.
+
+Given a button with a font icon and a style name:
+
+[source,java]
+....
+  button.addStyleName("redicon");
+  button.setIcon(FontAwesome.SAVE);
+....
+
+…you can then style the icon by applying styles to the .v-icon element:
+
+[source,css]
+....
+  .redicon .v-icon {
+    color: red;
+    font-size: 20px;
+  }
+....
+
+Note that the icon is actually text, so you style it in much the same
+way you style text. 
+
+A font icon also gets an additional `.<font-family>` stylename, so you can
+apply styles to only font icons (not ‘regular’ image icons):
+
+[source,css]
+....
+.v-button .FontAwesome {
+  color: blue;
+}
+....
diff --git a/documentation/articles/contents.asciidoc b/documentation/articles/contents.asciidoc
index 3c4808e885..396e4dfc3b 100644
--- a/documentation/articles/contents.asciidoc
+++ b/documentation/articles/contents.asciidoc
@@ -59,4 +59,5 @@ are great, too.
 - link:UsingVaadinCDIWithJAASAuthentication.asciidoc[Using Vaadin CDI with JAAS authentication]
 - link:LoadTestingWithGatling.asciidoc[Load testing with Gatling]
 - link:VaadinScalabilityTestingWithAmazonWebServices.asciidoc[Vaadin scalability testing with Amazon Web Services]
+- link:UsingFontIcons.asciidoc[Using font icons in Vaadin 7.2]
 - link:CreatingAUIExtension.asciidoc[Creating a UI extension]