Skip to main content

Iconify API implementation and tools for Django projects

Project description

This re-usable app hepls integrating Iconify into Django projects. Iconify is a unified icons framework, providing access to 40,000+ icons from different icon sets.

Iconify replaces classical icon fonts, claiming that such fonts would get too large for some icon sets out there. Instead, it provides an API to add icons in SVG format from its collections.

django-iconify eases integration into Django. Iconify, to be performant, uses a server-side API to request icons from (in batches, with transformations applied, etc.). Upstream provides a CDN-served central API as well as self-hosted options written in PHP or Node.js, all of which are undesirable for Django projects. django-iconify implements the Iconify API as a re-usable Django app.

Installation

To add django-iconify to a project, first add it as dependency to your project, e.g. using poetry:

$ poetry add django-iconify

Then, add it to your INSTALLED_APPS setting to make its views available later:

INSTALLED_APPS = [
    ...
    "dj_iconify.apps.DjIconifyConfig",
    ...
]

You need to make the JSON collection available by some means. You can download it manually, or use your favourite asset management library. For instance, you could use django-yarnpkg to depend on the @iconify/json Yarn package:

YARN_INSTALLED_APPS = [
  "@iconify/json",
]
NODE_MODULES_ROOT = os.path.join(BASE_DIR, "node_modules")

No matter which way, finally, you have to configure the path to the collections in your settings:

ICONIFY_JSON_ROOT = os.path.join(NODE_MODULES_ROOT, "@iconify", "json")

If you do not use django-yarnpkg, construct the path manually, ot use whatever mechanism your asset manager provides.

You can configure which icon collections are available using two settings:

ICONIFY_COLLECTIONS_ALLOWED = [“foo”, “bar”]

This list controls which collections can be used. If it is set to a non-empty list, only the collections listed are allowed.

ICONIFY_COLLECTIONS_DISALLOWED = [“foo”, “bar”]

This list, on the other hand, controls which collections cannot be used. If this list contains values, while COLLECTIONS_ALLOWED doesn’t, all collections except the listed ones are allowed.

The allow/disallow feature can be used in cases where only a limited set of collections should be available due to design principles or for legal reasons.

Finally, include the URLs in your urlpatterns:

from django.urls import include, path

urlpatterns = [
    path("icons/", include("dj_iconify.urls")),
]

Usage

Iconify SVG Framework

To use the Iconify SVG Framework, get its JavaScript from somewhere (e.g. using django-yarnpkg again, or directly from the CDN, from your ow nstatic files, or wherever).

django-iconify provides a view that returns a small JavaScript snippet that configures the Iconify SVG Framework to use its API endpoints. In the following example, we first load this configuration snippet, then include the Iconify SVG Framework from the CDN (do not do this in production, where data protection matters):

<script type="text/javascript" src="{% url 'config.js' %}"></script>
<script type="text/javascript" src="https://code.iconify.design/1/1.0.6/iconify.min.js"></script>

Loading SVG directly (“How to use Iconify in CSS”)

django-iconify also implements the direct SVG API. For now, you have to use Django’s regular URL reverse resolver to construct an SVG URL, or craft it by hand:

<img src="{% url 'iconify_svg' 'mdi' 'account' %}?rotate=90deg %}" />

Documentation on what query parameters are supported can be found in the documentation on How to use Iconify in CSS.

In the future, a template tag will be available to simplify this.

Including SVG in template directly

Not implemented yet

In the future, a template tag will be available to render SVG icons directly into the template, which can be helpful in situations where retrieving external resources in undesirable, like HTML e-mails.

Example

The source distribution as well as the Git repository contain a full example application that serves the API under /icons/ and a test page under /test.html.

It is reduced to a minimal working example for the reader’s convenience.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_iconify-0.4.tar.gz (16.8 kB view details)

Uploaded Source

Built Distribution

django_iconify-0.4-py3-none-any.whl (19.6 kB view details)

Uploaded Python 3

File details

Details for the file django_iconify-0.4.tar.gz.

File metadata

  • Download URL: django_iconify-0.4.tar.gz
  • Upload date:
  • Size: 16.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.6.1 CPython/3.11.5 Linux/6.5.0-1-rt-amd64

File hashes

Hashes for django_iconify-0.4.tar.gz
Algorithm Hash digest
SHA256 9c14614bf4e02ecd8b94dad11e11668250be8390a663ec88ce68b0c4b4165c92
MD5 c190f3dc7d9e05779988dad7201c4174
BLAKE2b-256 b933ec379f67cab37270e07f70f043524d163d2221221127430a49f821c18b47

See more details on using hashes here.

Provenance

File details

Details for the file django_iconify-0.4-py3-none-any.whl.

File metadata

  • Download URL: django_iconify-0.4-py3-none-any.whl
  • Upload date:
  • Size: 19.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.6.1 CPython/3.11.5 Linux/6.5.0-1-rt-amd64

File hashes

Hashes for django_iconify-0.4-py3-none-any.whl
Algorithm Hash digest
SHA256 3e93b8d6361e7fb32b725593d04a7667309cff6fd732f2dd1376a2b2b55ef2d6
MD5 3528facd1df4163b86366677c1c2653a
BLAKE2b-256 2111e41512b660881aa94ae5f2b08ec59870a1588504595051c46509e4a6a575

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page