6. Using Fonts with Icons

6.1. Introduction

Sometimes 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, Streamline 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 packaging. In the future, this service might be integrated into djangocms-cascade itself.

This submodule, if enabled adds three additional plugins: Icon with frame, Simple icon and Icon in text. Additionally it allows to decorate buttons with an icon on the left or right side of its main content.

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_texteditor_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 zip-file to a local folder on your computer.

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.

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. Therefore each uploaded font requires a unique CSS prefix, otherwise it wouldn’t be possible to use more than one icon font per page. This prefix must be set under Fontello’s settings, located left of the Download webfont button.

Attempting to upload an icon fonts with a CSS prefix, which is already used, will be rejected.

Warning

Depending on your settings, Safari auto-unzips that file and hence makes it unusable for re-upload. Either change your settings in Safari (Preferences > General > Open “safe” files), or use another browser.

Note

During the 0.17-series of djangocms-cascade, an icon font had to be selected per page, rather than per element. This feature turned out to be impractical and has been reverted to the pre-0.17 behaviour.

6.3. Using the Icon Plugin

In djangocms-cascade, currently four plugins make use of the icon font sublibrary. These are the Simple Icon, the Icon with frame, the Button and the Icon in Text plugin. The latter is available only as subplugin of the Text Editor plugin.

In their respective editors, the user may select one of the uploaded icon fonts. Each time one of them is selected, the table of symbols is rerendered. Use the search field on the top of the table to restrict the list of icons, in case there are too many.

Choose the desired symbol, its size and color. Optionally choose a background color, a border with width, color and style, and the relative position in respect of its wrapping element. 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 CKEditor for django-CMS, 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.