Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Using Icon Fonts in DITA Projects

Roger Sheen
November 19, 2014

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/

Roger Sheen

November 19, 2014
Tweet

More Decks by Roger Sheen

Other Decks in Programming

Transcript

  1. Using Icon Fonts in DITA Projects
    ! Scalable Vector Icons in HTML & PDF Output
    infotexture
    Information Architecture & Content Strategy
    Roger W. Fienhold Sheen

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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  =  [email protected]:FortAwesome/Font-­‐Awesome.git
    6

    View full-size slide

  7. (
    Part II — Markup Examples
    Defining & Referencing Icons in DITA Source
    Decide which element to customize: seems like a
    logical candidate, but it isn’t allowed everywhere. The generic
    phrase element is more flexible (permits nesting).
    Defining icon keys in a key map
       

    For HTML output, add an @outputclass attribute to each key

    For PDF output, add the character glyph to each key’s content

    But why?
    7

    View full-size slide

  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 (  )
    8

    View full-size slide

  9. Markup alternatives
    Conditional elements (filtered by output format)


    Combine conditional elements in a

       
           
           
       

    Conditionalize key definitions by output type, use simpler (unconditional) keys





    9

    View full-size slide

  10. Referencing icon keys
    To include an icon in your document, include a reference to the key like this:

    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:
       
        Dashboard    

    Insert a key reference like
    to show both the icon and the text: * Dashboard.
    10

    View full-size slide

  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
       
       
           
               
               
               
               
               
           

    11

    View full-size slide

  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

    View full-size slide

  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 in font-­‐mappings.xml

       
           
           
               
                   FontAwesome
               
               
           
       

    Extend the existing logical font entries with a new physical-­‐font element to
    map the icon character set to the icon font

       FontAwesome

    13

    View full-size slide

  14. Add a new attribute set to /cfg/fo/attrs/commons-­‐attr.xsl

       0pt
       0pt
       FontAwesome

    Create new template to apply the custom attribute set to all phrase elements
    whose @outputclass contains icon-­‐*
       
           
               
                   
                       
                       
                   
               
               
                   
                       
                       
                   
               
           

    14

    View full-size slide

  15. RenderX XEP Configuration
    Define new character set for icon code ranges in XEP/xep.xml
       
           
               
           

    Define new font family for icon font & add font file to XEP/fonts
       
           
               
           

    15

    View full-size slide

  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 ”:
       
           
               
                   
                   
               
           

    16

    View full-size slide

  17. -
    Editor Affordances
    Customizing your authoring environment to display the icons.
    Example
    The 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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  20. Thank You!
    Updates
    For updates, comments and the latest code samples, visit http://infotexture.net/.
    Contact
    0 E-mail [email protected]
    1 GitHub @infotexture
    2 Twitter @infotexture
    20

    View full-size slide