Package: djangocms-icon
django CMS Iconis a plugin fordjango CMSthat allows you to insert an icon (font or svg) into your project.NoteThis project is endorsed by thedjango CMS Association.
That means that it is officially accepted by the dCA as being in line with our roadmap vision and development/plugin policy.
Join us onSlack.Contribute to this project and win rewardsBecause this is a an open-source project, we welcome everyone toget involved in the projectandreceive a rewardfor their contribution.
Become part of a fantastic community and help us make django CMS the best CMS in the world.We’ll be delighted to receive your
feedback in the form of issues and pull requests. Before submitting your
pull request, please review ourcontribution guidelines.We’re grateful to all contributors who have helped create and maintain this package.
Contributors are listed at thecontributorssection.InstallationFor a manual install:runpip installdjangocms-iconadddjangocms_iconto yourINSTALLED_APPSrunpython manage.py migrate djangocms_iconA note about django CMS Text CKEditorThere are additional steps required for the icon plugin to display correctly
inside CKEditor.1. You need to make sure your icon CSS is passed via CKEditorscontentsCssparameter.
On Divio Cloud this can be done through the Addons configuration.2. CKEditor automatically removes empty tags, you can prevent this by adding
ajavascript configuration filetostyle_set.django CMS Icon does not add the styles or javascript files to your frontend, these need to be added at your discretion.ConfigurationThis addon provides adefaulttemplate for all instances. You can provide
additional template choices by adding aDJANGOCMS_ICON_TEMPLATESsetting:DJANGOCMS_ICON_TEMPLATES = [
    ('svg', 'SVG template'),
]Web Font IconsThe django CMS Icon plugin ships withFont Awesome 5 as default. This can
be changed by overriding the following setting:DJANGOCMS_ICON_SETS = [
    ('fontawesome5regular', 'far', 'Font Awesome 5 Regular', 'lastest'),
    ('fontawesome5solid', 'fas', 'Font Awesome 5 Solid', 'lastest'),
    ('fontawesome5brands', 'fab', 'Font Awesome 5 Brands', 'lastest'),
]In additionyou need to loadthe resources for your fonts in/admin/djangocms_icon/includes/assets.html. Add this file to your project
in order for the icon picker to pick up your custom icons in the admin.The icon picker supportsnumerous font librariesout of the box. You can also add multiple font sets like this:DJANGOCMS_ICON_SETS = [
    ('elusiveicon', 'el', 'Elusive Icons'),
    ('flagicon', 'flag-icon', 'Flag Icons'),
    ('fontawesome5regular', 'far', 'Font Awesome 5 Regular'),
    ('fontawesome5solid', 'fas', 'Font Awesome 5 Solid'),
    ('fontawesome5brands', 'fab', 'Font Awesome 5 Brands'),
    ('fontawesome5light', 'fal', 'Font Awesome 5 Light', '5.3.1_pro'),
    ('glyphicon', 'glyphicon', 'Glyphicons'),
    ('ionicon', 'ion', 'Ionicons Icons'),
    ('mapicon', 'map-icon', 'Map Icons'),
    ('materialdesign', 'zmdi', 'Material Design'),
    ('octicon', 'octicon', 'Octicons'),
    ('typicon', 'typcn', 'Typicons'),
    ('weathericon', 'wi', 'Weather Icons'),
]You can also add the version number as a fourth parameter.
If no parameter is given the latest version of the bootstrap-iconpicker icon set is used.:DJANGOCMS_ICON_SETS = [
    ('fontawesome4', 'fa', 'Font Awesome 4', '4.0.0'),
    ('fontawesome5light', 'fal', 'Font Awesome 5 Light', '5.3.1_pro'),
]Just don’t forget to include both libraries in theassets.htmlfile.
This is only necessary for the plugin rendering while selecting the icon.
You still need to implement the font libraries into your frontend stack.Custom Web Font IconsYou can also add your own custom web fonts, for this you need to tell the
icon picker where to find the necessary files:DJANGOCMS_ICON_SETS = [
    (ICONSET, 'icon', 'Custom web font'),
]In this example, we add our own font icon set on top of it. Please mind
that the second parameter needs to be the icon prefix.ICONSETis an
external reference to a JSON file at the root of your project setting up
your custom font icons, add this before:with open('iconset.json') as fh:
    ICONSET = fh.read()Here an example of its content:{
    "iconClass": "icon",
    "icons": [
        "icon-icon1",
        "icon-icon2",
        "..."
    ]
}TheiconClassrefers to the second parameter in the settings file for the
icon prefix. Make sure both of them are the same. Instead of using an external
file you can also write the settings directly to theDJANGOCMS_ICON_SETSsetting.djangocms-boilerplate-webpackcan generate theiconset.jsonautomatically for you throughgulp icons.Make sure the icons names contain the iconset prefix as shown in the example,
the widget will determine the iconset based on that. They can be omitted if only
one iconset is used.Don’t forget to also add your custom fonts to/admin/djangocms_icon/includes/assets.htmlinto your project.SVG Iconsdjango CMS Icon also supports SVG icons. Follow the instructions fromCustom Web Font Iconsand then adapt the JSON file a bit:{
    "svg": true,
    "spritePath": "sprites/icons.svg",
    "iconClass": "icon",
    "icons": [
        "icon-icon1",
        "icon-icon2",
        "..."
    ]
}svgandspritePathare the only required additional properties. You
also need to add an icon template to your project to render it correctly,
for example:<span class="{{ instance.icon }} {{ instance.attributes.class }}">
    <svg role="presentation">
        <use xlink:href="{% static 'sprites/icons.svg' %}#{{ instance.icon }}"></use>
    </svg>
</span>Running TestsYou can run tests by executing:virtualenv env
source env/bin/activate
pip install -r tests/requirements.txt
python setup.py test