====================== Using Fonts with Icons ====================== 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. Configuration ------------- To enable this service in **djangocms-cascade**, in ``settings.py`` add: .. code-block:: python 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: .. code-block:: python 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')), } 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. 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. 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 :ref:`sharable-fields`. 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. .. _Font Awesome: http://fontawesome.io/ .. _Material Icons: https://design.google.com/icons/ .. _Streamline Icons: https://streamlineicons.com/ .. _Fontello: http://fontello.com/ .. _CKEditor for django-CMS: https://pypi.org/project/djangocms-text-ckeditor/