Good use of icons on a website can really lift its overall design. Of course, you can’t just slap them on and expect a site to look brilliant. It’s all about choosing the right type of icons to match the design.
Once your designer has chosen a font library like Font Awesome, or made their own, what is the best way of displaying them in Drupal? The quick and simple way is to get the designer to style them using CSS but this is not flexible.
What if an editor wants to choose which icon is displayed in a menu? If you’ve added them to the menu manually via CSS then the editor won’t have the ability to change the icon in the future.
The Icon API module integrates common icon bundles like Font Awesome, Bootstrap and more within Drupal. The module offers integration with a suite of sub-modules. For example, if you want to add icons to menus then install the icon_menu module.
In this tutorial, we’ll configure Icon API to allow an editor to add icons to menus and directly into content. We’ll do this using the Font Awesome icon bundle.
Getting Started
Icon API doesn’t ship actual icons, as the name suggests, it just an API.
To display icons we’ll need to install an icon bundle so before we jump in, let’s install the Font Awesome module.
Installing Font Awesome
Go download Font Awesome and Libraries API and install both modules.
Drush command:
drush dl fontawesome libraries drush en fontawesome
Download Library
The module attempts to download the Font Awesome library when you enable it. However, this didn’t work for me so I had to manually download the library and add it to the libraries directory. The module has a Drush command to download Font Awesome, unfortunately this didn’t work.
Download v4.2.0 and extract the zip into your libraries directory. Make sure the path to the CSS directory is /sites/all/libraries/fontawesome/css.
Installing Icon API
Now that we have Font Awesome installed, go download Icon API, then enable “Icon API: Menu” and “Icon API: Filter” sub-module.
Drush command:
drush dl icon drush en icon_menu icon_filter
To test and make sure the module has been setup. Login as the administrator and go to Configuration and click on the Icons link in the Media section.
From this page you can see all the available icon bundles and you can enable or disable them. Here we have two bundles available: “Font Awesome” and “Lullacons: Pack 1”.
Menu Icons
Now that we’ve got Icon API and “Font Awesome” setup, let’s display some actual icons in Drupal. The most common place for icons is in a menu so let’s add some to the main menu.
1. Go to Structure, Menus and click on “list links” in the “Main menu” row.
2. Edit the Home menu item and scroll to the bottom. You should see an Icon field-set.
From here you select and configure the icon.
3. Seeing that we’re editing the Home link, let’s add a home icon. Search for home in the drop-down.
When you select an icon, extra options will appear below. All of them are self-explanatory, leave them in their default state and click on Save.
If you go to the homepage you should see a home icon next to the Home link.
Inline Icons
In the last section we added icons to the main menu. Let’s now learn how to add them directly into content.
For this you’ll need the “Icon API: Filter” sub-module, make sure it’s enabled.
The sub-module renders icons via a filter on a text format. All you need to do is setup the “Convert [icon:%bundle:%icon] tags” filter and add an icon tag like [icon:%bundle:%icon], the filter will then render the icon. Let’s now configure the filter.
1. Go to Configuration, “Text formats” and click on configure the “Filtered HTML” row.
2. Check the “Convert [icon:%bundle:%icon] tags” filter.
3. Icons are rendered using an <i> tag and because we’re using the “Limit allowed HTML tags” filter, these tags will get filtered out. To workaround this issue, you have two options: reorder the filters or add <i> into the “Allowed HTML tags” text field.
The easiest thing to do is just move “Convert [icon:%bundle:%icon] tags” so it’s after “Limit allowed HTML tags”.
Once configured click on “Save configuration”.
4. Go create a test article and add [icon:fontawesome:home] as the icon. If everything has been configured correctly you should see an icon.
Summary
The thing that I like about this module is that it’s editor friendly, with little training an editor can manage icons throughout a Drupal site themselves. This not only makes them happy but saves you, as a site builder, time because you won’t have to push out a code release just to change a basic icon in the menu.
