6. Using Fonts with Icons

6.1. Introduction

Sometime we want to enrich our web pages with vectorized symbols. A lot of them can be found in various font libraries, such as Font Awesome, Material Icons and many more. A typical approach would be to upload the chosen SVG symbol, and use it as image. This process however is time consuming and error-prone to organize. Therefore, djangocms-cascade offers an optional submodule, so that we can work with externally packed icon fonts.

In order to use such a font, currently we must use Fontello, an external service for icon font generation. In the future, this service might be integrated into djangocms-cascade itself.

6.1.1. Configuration

To enable this service in djangocms-cascade, in settings.py add:

INSTALLED_APPS = [
    …
    'cmsplugin_cascade',
    'cmsplugin_cascade.icon',
    …
]

CMSPLUGIN_CASCADE_PLUGINS = [
    …
    'cmsplugin_cascade.icon',
    …
]

This submodule, can of course be combined with all other submodules available for the Cascade ecosystem.

If CMS_PLACEHOLDER_CONF is used to configure available plugins for each placeholder, assure that the TextIconPlugin is added to the list of text_only_plugins.

Since the CKEditor widget must load the font stylesheets for it’s own WYSIWIG mode, we have to add this special setting to our configuration:

from django.core.urlresolvers import reverse_lazy
from django.utils.text import format_lazy

CKEDITOR_SETTINGS = {
    …
    'stylesSet': format_lazy(reverse_lazy('admin:cascade_texticon_wysiwig_config')),
}

6.2. Uploading the Font

In order to start with an external font icon, choose one or more icons and/or whole font families from the Fontello website and download the generated webfont file to a local folder.

In Django’s admin backend, change into Start › django CMS Cascade › Uploaded Icon Fonts and add an Icon Font object. Choose an appropriate name and upload the just downloaded webfont file, without unzipping it. After the upload completed, all the imported icons appear grouped by their font family name. They now are ready for being used by the Icon plugin.

6.3. Using the Icon Plugin

Attention

The icon fonts generated by Fontello, offer a generated ….css file containing a mapping of private UTF-8 characters onto their font symbol. This means that the genarated font files may have an overlapping encoding. It thus is not possible to use more than one icon font per page. If you forgot a symbol, recreate your icon font. Then replace that icon font by uploading it.

On the django-CMS toolbar, navigate to Page › Choose Icon Font…. In the popped up dialog window, select one of the previously uploaded icon fonts.

A font symbol can be used everywhere plain text can be added. Inside a django-CMS placeholder field add a plugin of type Icon. Here a table of possible icons appears. Choose the desired symbol, its size and color. Optionally choose a background color, the relative position in respect of its wrapping element and a border width with style and color. After saving the form, that element should appear inside the chosen container.

6.3.1. Shared Settings

By default, the IconPlugin is configured to allow to share the following styling attributes:

  • Icon size
  • Icon color
  • Background color, or without background
  • Text alignment
  • Border width, color and style
  • Border radius

By storing these attributes under a common name, one can reuse them across various icons, without having to set them for each one, separately. Additionally, each of the shared styling attributes can be changed globally in Django’s admin backend at Start › django CMS Cascade › Shared between Plugins. For details please refer to the section about Working with sharable fields.

6.4. Using the Icon Plugin in plain text

If django-CMS is configured to use the djangocms-ckeditor-widget, then you may use the Icon Plugin inside plain text. Place the cursor at the desired location in text and select Icon from the pull down menu CMS Plugins. This opens a popup where you may select the font family and the symbol. All other attributes described above, are not available with this type of plugin.