Giter Site home page Giter Site logo

sin-ack / djangocms-icon Goto Github PK

View Code? Open in Web Editor NEW

This project forked from django-cms/djangocms-icon

0.0 1.0 0.0 1.52 MB

django CMS Icon adds capabilities to implement Font or SVG icons as plugins into your project.

Home Page: https://marketplace.django-cms.org/en/addons/browse/djangocms-icon/

License: Other

Python 2.33% HTML 0.27% JavaScript 96.72% SCSS 0.68%

djangocms-icon's Introduction

django CMS Icon

pypi build coverage

django CMS Icon is a plugin for django CMS that allows you to insert an icon (font or svg) into your project.

This addon is compatible with Divio Cloud and is also available on the django CMS Marketplace for easy installation.

preview.gif

Contributing

This is a an open-source project. We'll be delighted to receive your feedback in the form of issues and pull requests. Before submitting your pull request, please review our contribution guidelines.

We're grateful to all contributors who have helped create and maintain this package. Contributors are listed at the contributors section.

One of the easiest contributions you can make is helping to translate this addon on Transifex.

Documentation

See REQUIREMENTS in the setup.py file for additional dependencies:

python django djangocms

Installation

For a manual install:

  • run pip install djangocms-icon
  • add djangocms_icon to your INSTALLED_APPS
  • run python manage.py migrate djangocms_icon

A note about django CMS Text CKEditor

There 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 CKEditors contentsCss parameter. On Divio Cloud this can be done through the Addons configuration.

2. CKEditor automatically removes empty tags, you can prevent this by adding a javascript configuration file to style_set.

Configuration

This addon provides a default template for all instances. You can provide additional template choices by adding a DJANGOCMS_ICON_TEMPLATES setting:

DJANGOCMS_ICON_TEMPLATES = [
    ('svg', 'SVG template'),
]

Web Font Icons

The django CMS Icon plugin ships with Font Awesome 4 as default. This can be changed by overriding the following setting:

DJANGOCMS_ICON_SETS = [
    ('fontawesome4', 'fa', 'Font Awesome 4'),
]

To use Font Awesome 5 in the above example; see the options below form the DJANGOCMS_ICON_SETS listed.

In addition you need to load the 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 supports numerous font libraries out of the box. You can also add multiple font sets like this:

DJANGOCMS_ICON_SETS = [
    ('elusiveicon', 'el', 'Elusive Icons'),
    ('flagicon', 'flag-icon', 'Flag Icons'),
    ('fontawesome4', 'fa', 'Font Awesome 4'),
    ('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 the assets.html file. 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 Icons

You 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. ICONSET is 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",
        "..."
    ]
}

The iconClass refers 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 the DJANGOCMS_ICON_SETS setting.

djangocms-boilerplate-webpack can generate the iconset.json automatically for you through gulp 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.html into your project.

SVG Icons

django CMS Icon also supports SVG icons. Follow the instructions from Custom Web Font Icons and then adapt the JSON file a bit:

{
    "svg": true,
    "spritePath": "sprites/icons.svg",
    "iconClass": "icon",
    "icons": [
        "icon-icon1",
        "icon-icon2",
        "..."
    ]
}

svg and spritePath are 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 Tests

You can run tests by executing:

virtualenv env
source env/bin/activate
pip install -r tests/requirements.txt
python setup.py test

djangocms-icon's People

Contributors

antwertinger avatar dependabot[bot] avatar finalangel avatar sin-ack avatar vthaian avatar vxsx avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.