Using Icon Fonts in DITA Projects

Modern Web applications use fonts with scalable vector icons that render sharply at any resolution. Similar techniques can be used in DITA projects to include icons from the user interface in output. This session presents several options for integrating icon fonts in DITA projects and includes markup examples and renderer configurations to include icon glyphs in multiple output formats.

Presented at DITA Europe in Munich November 19, 2014 http://www.infomanagementcenter.com/DITAeurope/2014/

Transcript

1. Using Icon Fonts in DITA Projects ! Scalable Vector Icons in HTML & PDF Output infotexture Information Architecture & Content Strategy Roger W. Fienhold Sheen
2. " Agenda Introduction Part I — Background & Concepts Why Use Fonts for Icons? Selecting an Icon Font Adding the Icon Resources to Your Project Part II — Markup Examples Defining & Referencing Icons in DITA Source Customizations for HTML Output Customizations for Print (PDF) Output Editor Affordances References & Resources 2
3. # $ Introduction Modern Web applications use fonts with scalable vector icons that render sharply at any resolution. Similar techniques can be used in DITA projects to include icons from the user interface in output. This session presents several options for integrating icon fonts in DITA projects and includes markup examples and renderer configurations to include icon glyphs in multiple output formats. 3
4. % Part I — Background & Concepts Why Use Fonts for Icons? At 16 pixels, an icon like this might look fine, but at 320? “Here there be jaggies…” → Icon font benefits Scale easily Change color easily Include shadows easily Can have transparent knockouts Well-supported by modern web browsers Can be designed on the fly (change on :hover, etc.) Can do anything image icons can do (change opacity, rotate, etc.) 4
5. & Selecting an Icon Font Many popular open source fonts have licenses that permit commercial use. Check glyphsearch.com to find icons you like. Font Awesome Ionicons Iconic Octicons Other factors to consider: Size & glyph coverage: how large are the files and what icons do they include? Custom icon fonts: create a custom font with only the icons you need Accessibility: what will screen readers “see” and visually impaired users hear? Acessibility-aware fonts often use the Unicode Private Use Area (PUA) and the CSS property speak:  none to ensure screen readers don’t read icons aloud. 5
6. ' Adding the Icon Resources to Your Project Decide where & how to import the icons. Are the icons likely to change during the project lifecycle? If not, just download & unpack a .zip file If yes, consider installing via a package manager Bower Component Duo Or use version control mechanisms to easily fetch upstream updates Mercurial subrepository Git submodule (or subtree) [submodule  "dita-­‐src/assets/font-­‐awesome"]    path  =  dita-­‐src/assets/font-­‐awesome    url  =  git@github.com:FortAwesome/Font-­‐Awesome.git 6
7. ( Part II — Markup Examples Defining & Referencing Icons in DITA Source Decide which element to customize: <uicontrol> seems like a logical candidate, but it isn’t allowed everywhere. The generic phrase element <ph> is more flexible (permits nesting). Defining icon keys in a key map <!-­‐-­‐  Define  keys  for  Font  Awesome  icons  -­‐-­‐>     <keydef  keys="icons"  href="common/icons.dita"  type="topic"  format="dita"/> For HTML output, add an @outputclass attribute to each key <uicontrol  id="check"  outputclass="icon-­‐check"/> For PDF output, add the character glyph to each key’s content <uicontrol  id="check"  outputclass="icon-­‐check">&#xf046;</uicontrol> But why? 7
8. What’s going on here? — Why Different Markup for HTML & PDF? For HTML output, icons are inserted via the CSS ::before pseudo-element, which inserts content before every instance of the element it is associated with. Icon fonts typically include stylesheets (CSS, LESS or SCSS files) with rules like: .icon-­‐check:before  {    /*  Insert  check  mark  */    content:  "\f046"; } For PDF output, the character glyph must be explicitly added to each key’s content, since XSL-FO does not support the ::before pseudo-element. The numeric value for each icon is typically provided in a reference document (or “cheatsheet”), which lists each icon with its CSS class & Unicode value: ) icon-check ( &#xf046; ) 8
9. Markup alternatives Conditional elements (filtered by output format) <uicontrol  otherprops="htmlonly"  outputclass="icon-­‐check"/> <uicontrol  otherprops="printonly"  outputclass="icon-­‐check">&#xf046;</uicontrol> Combine conditional <uicontrol> elements in a <menucascade> <ph  id="check">    <menucascade>        <uicontrol  otherprops="htmlonly"  outputclass="icon-­‐check"/>        <uicontrol  otherprops="printonly"  outputclass="icon-­‐check">&#xf046;</uicontrol>    </menucascade> </ph> Conditionalize key definitions by output type, use simpler (unconditional) keys <!-­‐-­‐  Conditional  keys  for  HTML  output  -­‐-­‐> <keydef  keys="icons"  otherprops="htmlonly"  href="common/html-­‐icons.dita"  type="topic"  format="dita"/> <!-­‐-­‐  Conditional  keys  for  print  (PDF)  output  -­‐-­‐> <keydef  keys="icons"  otherprops="printonly"  href="common/pdf-­‐icons.dita"  type="topic"  format="dita"/> <ph  id="check"  outputclass="icon-­‐check"/> 9
10. Referencing icon keys To include an icon in your document, include a reference to the key like this: <ph  conkeyref="icons/check"/> The icons can be combined with other elements and referenced together. The following example shows an excerpt from menus.dita , which is defined in the root map as the source for menus keys: <ph  id="dashboard">        <ph  conkeyref="icons/dashboard"/>&#xA0;<uicontrol>Dashboard</uicontrol>     </ph> Insert a key reference like <ph  conkeyref="menus/dashboard"/> to show both the icon and the text: * Dashboard. 10
11. + Customizations for HTML Output Icon fonts designed for the web are easy to integrate. Extend custom CSS Import the style sheets provided with the icon fonts to your custom CSS file (typically CSS, LESS or SCSS): @import  "../assets/icons/font-­‐awesome/less/font-­‐awesome.less"; Extend build scripts to copy fonts to output <mkdir  dir="${project.output.dir}/html/assets/icons/font-­‐awesome/font"/>     <copy  todir="${project.output.dir}/html/assets/icons/font-­‐awesome/font">        <fileset  dir="${project.dir}/assets/icons/font-­‐awesome/font">            <include  name="FontAwesome.otf"/>            <include  name="fontawesome-­‐webfont.woff"/>            <include  name="fontawesome-­‐webfont.ttf"/>            <include  name="fontawesome-­‐webfont.svg"/>            <include  name="fontawesome-­‐webfont.eot"/>        </fileset>     </copy> 11
12. , Customizations for Print (PDF) Output PDF output requires a bit more work than HTML, and the steps depend on which renderer you use to convert XSL-FO (Apache FOP, RenderX XEP, Antenna House). Customization Overview 1. Extend (or create) custom PDF plugins to use your icon font Add new character set for icons to logical fonts in font-­‐mappings.xml Extend logical fonts to associate icon character set with a new font Add a new attribute set to commons-­‐attr.xsl Create new template to apply the custom attribute set to icons 2. Configure your XSL Formatting Objects renderer to find & use your icon font Define new character set for icon code ranges (XEP) Define new font family for icon font (XEP) Add, install, and/or register font file(s) 12
13. PDF Plugins The font-­‐mappings.xml file maps logical fonts used in the XSLT stylesheets to the physical fonts used by the FO processor to generate PDF output. Add a new logical font to the <font-­‐table> in font-­‐mappings.xml <font-­‐mappings>    <font-­‐table>        <!-­‐-­‐  […]  -­‐-­‐>        <logical-­‐font  name="FontAwesome">            <physical-­‐font  char-­‐set="default">                <font-­‐face>FontAwesome</font-­‐face>            </physical-­‐font>            <!-­‐-­‐  […]  -­‐-­‐>        </logical-­‐font>    </font-­‐table> </font-­‐mappings> Extend the existing logical font entries with a new physical-­‐font element to map the icon character set to the icon font <physical-­‐font  char-­‐set="Font  Awesome">    <font-­‐face>FontAwesome</font-­‐face> </physical-­‐font> 13
14. Add a new attribute set to /cfg/fo/attrs/commons-­‐attr.xsl <xsl:attribute-­‐set  name="ph_icon">    <xsl:attribute  name="border-­‐left-­‐width">0pt</xsl:attribute>    <xsl:attribute  name="border-­‐right-­‐width">0pt</xsl:attribute>    <xsl:attribute  name="font-­‐family">FontAwesome</xsl:attribute> </xsl:attribute-­‐set> Create new template to apply the custom attribute set to all phrase elements whose @outputclass contains icon-­‐* <xsl:template  match="*[contains(@class,'  topic/ph  ')]">        <xsl:choose>            <xsl:when  test="contains(@outputclass,'icon-­‐')">                <fo:inline  xsl:use-­‐attribute-­‐sets="ph_icon">                    <xsl:call-­‐template  name="commonattributes"/>                    <xsl:apply-­‐templates/>                </fo:inline>            </xsl:when>            <xsl:otherwise>                <fo:inline  xsl:use-­‐attribute-­‐sets="ph">                    <xsl:call-­‐template  name="commonattributes"/>                    <xsl:apply-­‐templates/>                </fo:inline>            </xsl:otherwise>        </xsl:choose>     </xsl:template> 14
15. RenderX XEP Configuration Define new character set for icon code ranges in XEP/xep.xml <charset  name="Font  Awesome">        <code-­‐ranges>            <code-­‐range  from="0xf000"  to="0xf18a"/>        </code-­‐ranges>     </charset> Define new font family for icon font & add font file to XEP/fonts <font-­‐family  name="FontAwesome"  embed="true"  subset="true">        <font>            <font-­‐data  otf="FontAwesome.otf"/>        </font>     </font-­‐family> 15
16. Apache Formatting Objects Processor (FOP) Configuration Install the icon font on your operating system. For DITA-OT versions prior to 1.8, adjust the Apache FOP configuration to tell FOP to look for the icon font in the system fonts. In your custom PDF plugin, edit fop/conf/fop.xconf to allow Apache FOP to detect the system fonts: add an auto-­‐detect element to the fonts element in the renderer element with the @mime attribute set to “application/pdf ”: <renderer  mime="application/pdf">        <!-­‐-­‐  […]  -­‐-­‐>            <fonts>                <!-­‐-­‐  automatically  detect  operating  system  installed  fonts  -­‐-­‐>                <auto-­‐detect/>            </fonts>        <!-­‐-­‐  […]  -­‐-­‐>     </renderer> 16
17. - Editor Affordances Customizing your authoring environment to display the icons. <oXygen/> Example The <oXygen/> XML Editor allows you to customize the presentation of XML content shown in Author mode by creating alternate style sheets that extend the built-in (default) styles. This mechanism can be used to approximate the look-and-feel of company documents by adjusting fonts & colors to according to branding guidelines. Add @font-­‐face declaration to define the font file to use for the icons: @font-­‐face  {        font-­‐family:  'FontAwesome';        src:  url('font-­‐awesome/font/fontawesome-­‐webfont.ttf?v=3.2.1')  format('truetype');        font-­‐weight:  normal;        font-­‐style:  normal;     } 17
18. Add a rule to select elements whose @outputclass begins with or contains icon-­‐ and set them to use the new font-­‐family : [outputclass^="icon-­‐"],     [outputclass*="  icon-­‐"]  {        font-­‐family:  FontAwesome;        font-­‐weight:  normal;        font-­‐style:  normal;        text-­‐decoration:  inherit;        -­‐webkit-­‐font-­‐smoothing:  antialiased;        margin-­‐right:  .3em;     } 18
19. . References & Resources Further Reading Leigh White’s DITA for Print: A DITA Open Toolkit Workbook Eliot Kimber’s DITA for Practitioners Popular Icon Fonts Font Awesome / http://fontawesome.io Ionicons / http://ionicons.com Typicons / http://typicons.com Iconic / https://useiconic.com/open Octicons / https://octicons.github.com Foundation / http://zurb.com/playground/foundation-icon-fonts-3 19
20. Thank You! Updates For updates, comments and the latest code samples, visit http://infotexture.net/. Contact 0 E-mail roger@infotexture.net 1 GitHub @infotexture 2 Twitter @infotexture 20