Working with Adapt's Vanilla icons

It's no secret that a set of icons comes bundled with Adapt. But try to find them displayed or depicted, and you'd have reason to believe they are TOP secret. One reason for the difficulty is that the icons are not stored as bitmaps or PNGs or SVGs. Adapt deploys the icons as an icon font. There are some real benefits to the strategy of using an icon font, but one downside is you can't see them displayed in your typical file explorer or finder. Because they are a font, they get displayed like a font. If you took the steps to install the font vanilla.woff on your computer—and if you try this, you may need first to convert WOFF to TTF—you'd be able to view the glyphs/icons in a font manager. Or you can spend an inordinate amount of time creating a reference by charting them in a web page. I know because I created  such a chart. I share it with members at the end of this article. (It's free to subscribe.)

Codepoints and class names

In an icon font, each icon glyph is mapped to a unicode codepoint—just as a letter glyph is mapped to a codepoint in an alphabetical font. This is done within the font file itself. You won't be able to type with an icon font—without special programming. The keys on your keyboard are associated with the codepoints of the letter glyphs that are etched into each key. You can change this programmatic assignment, however, if and when you change your keyboard language. Conventions have been established for key assignments in various languages and are followed in computer operating systems. But icon fonts are frequently cobbled together and use codepoints that rarely overlap with keyboard assignments. We are using the technology of digital fonts, but we are not using its data input hardware (e.g., keyboard).

While we can't see the digital icon glyphs in the vanilla.woff file, we can access them by their unicode codepoint. In our context, Adapt programming, a codepoint looks something like this: \e927. That particular codepoint represents the white object in the following image:

\e927 is a meaningless name for this icon. To make it easier to reference in CSS, Adapt has provided a file (src/core/less/_defaults/icons.less) that assigns each codepoint a class name. Here's what a portion of that code looks like:

.icon-star-hollow                 { &:before { content: "\e924"; } }
.icon-comments                    { &:before { content: "\e925"; } }
.icon-comment                     { &:before { content: "\e926"; } }
.icon-home                        { &:before { content: "\e927"; } }
.icon-popup                       { &:before { content: "\e928"; } }
.icon-search                      { &:before { content: "\e929"; } }
.icon-printer                     { &:before { content: "\e92a"; } }

We can see two things happening in this code:
1. \e927 is being associated with the class name "icon-home", and
2. the classes are set up to render the glyph as the content of the "before" pseudo-element.
The result is that when we assign one of these class names to <span>, <i>, or another appropriate HTML element—even if it is an empty tag—its assigned icon glyph will be displayed.

This is the model that Adapt prefers to use: icons are deployed by applying a class name to an element, not by direct use of the icon's codepoint. There are times, especially when customizing CSS or Less, that referencing the codepoint is reasonable. And it is in those times that icons.less functions as a human-readable list of icons. Simply scan down the class names until you find what you want, then copy the codepoint. OK, OK—I know that it is easy to anticipate what ".icon-home" looks like; but I have no idea what I'll be getting with ".icon-comment", do you? Hmm, that's when a visual chart comes in handy:

Styling icons

Because we are working with an icon font, we need to think about manipulating and styling these icons as we do fonts.  Think "fonts," not "images." Differences, for example:

To maintain visual consistency across icons, Adapt applies a variety of style rules in the "icon" class. You can find this in the same icon.less file that was mention earlier. In use it may look a bit redundant, class="icon icon-home", but it's not. All global style rules are found in .icon while the unique codepoint alone is found in .icon-home.

If you want to add some custom styles to your icons, say you want to apply different colors to different icons, I recommend that you preserve icons.less as it is and add your additional styles in new file such as src/theme/adapt-contrib-vanilla/less/project/theme-extras.less. Upgrading is easier that way because your customizations are not mixed in with repository code.

Adding icons to the Vanilla icon font

If you are satisfied with the style of the Vanilla icons but need something that is missing, you can add icons to the Vanilla icon font. A word of caution: if you act on the explanation in this section, you will be altering files in Adapt's core. This is a safe and relatively easy modification to make. But you will need to take steps to preserve your modifications whenever you upgrade your Adapt installation.

Adapt's Vanilla icon font is made from a selection of icons from https://icomoon.io. That selection is preserved in a file with this path and name: src/core/fonts/selections.json. This, logically, is the same folder that holds the icon font, vanilla.woff (and vanilla.woff2). You can use this file to inform IcoMoon which icons are already in your font set and to load additional icons into the same set—without recreating the set and the assigned codepoints. IcoMoon provides instructions.

Switching icon fonts

There are a variety of established icon fonts that are available on the internet. You can add them to your theme, so that you have other styles of icons to choose from or so that you can effect a wholesale replacement of the Vanilla icon font. Font Awesome is a popular icon font. Simon Date's Adding Font Awesome to a Adapt theme shows you how to do that.

Download the Vanilla icon font chart

My Vanilla icon font chart follows below. If you are already a member of ADAPT.tips and have subscribed to the newsletter, you can see and use the link to download the PDF. If you can't see the link, I invite you to sign-up for free.