Iconify API implementation and tools for Django projects
========================================================
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.
.. _Iconify: https://iconify.design/
.. _django-iconify: https://edugit.org/AlekSIS/libs/django-iconify
.. _poetry: https://python-poetry.org/
.. _JSON collection: https://github.com/iconify/collections-json
.. _django-yarnpkg: https://edugit.org/AlekSIS/libs/django-yarnpkg
.. _Iconify SVG Framework: https://docs.iconify.design/implementations/svg-framework/
.. _How to use Iconify in CSS: https://docs.iconify.design/implementations/css.html
.. _Git repository: https://edugit.org/AlekSIS/libs/django-iconify
Raw data
{
"_id": null,
"home_page": "https://edugit.org/AlekSIS/libs/django-iconify",
"name": "django-iconify",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "iconify,icons,svg,django",
"author": "Dominik George",
"author_email": "dominik.george@teckids.org",
"download_url": "https://files.pythonhosted.org/packages/b9/33/ec379f67cab37270e07f70f043524d163d2221221127430a49f821c18b47/django_iconify-0.4.tar.gz",
"platform": null,
"description": "Iconify API implementation and tools for Django projects\n========================================================\n\nThis re-usable app hepls integrating `Iconify`_ into Django projects.\nIconify is a unified icons framework, providing access to 40,000+ icons\nfrom different icon sets.\n\nIconify replaces classical icon fonts, claiming that such fonts would\nget too large for some icon sets out there. Instead, it provides an API\nto add icons in SVG format from its collections.\n\n`django-iconify`_ eases integration into Django. Iconify, to be performant,\nuses a server-side API to request icons from (in batches, with transformations\napplied, etc.). Upstream provides a CDN-served central API as well as\nself-hosted options written in PHP or Node.js, all of which are undesirable\nfor Django projects. `django-iconify`_ implements the Iconify API as a\nre-usable Django app.\n\nInstallation\n------------\n\nTo add `django-iconify`_ to a project, first add it as dependency to your\nproject, e.g. using `poetry`_::\n\n $ poetry add django-iconify\n\nThen, add it to your `INSTALLED_APPS` setting to make its views available\nlater::\n\n INSTALLED_APPS = [\n ...\n \"dj_iconify.apps.DjIconifyConfig\",\n ...\n ]\n\nYou need to make the `JSON collection`_ available by some means. You can\ndownload it manually, or use your favourite asset management library. For\ninstance, you could use `django-yarnpkg`_ to depend on the `@iconify/json`\nYarn package::\n\n YARN_INSTALLED_APPS = [\n \"@iconify/json\",\n ]\n NODE_MODULES_ROOT = os.path.join(BASE_DIR, \"node_modules\")\n\nNo matter which way, finally, you have to configure the path to the\ncollections in your settings::\n \n ICONIFY_JSON_ROOT = os.path.join(NODE_MODULES_ROOT, \"@iconify\", \"json\")\n\nIf you do not use `django-yarnpkg`_, construct the path manually, ot use\nwhatever mechanism your asset manager provides.\n\nYou can configure which icon collections are available using two settings:\n\n ICONIFY_COLLECTIONS_ALLOWED = [\"foo\", \"bar\"]\n\nThis list controls which collections can be used. If it is set to a\nnon-empty list, only the collections listed are allowed.\n\n ICONIFY_COLLECTIONS_DISALLOWED = [\"foo\", \"bar\"]\n\nThis list, on the other hand, controls which collections cannot be used.\nIf this list contains values, while `COLLECTIONS_ALLOWED` doesn't, all\ncollections except the listed ones are allowed.\n\nThe allow/disallow feature can be used in cases where only a limited set\nof collections should be available due to design principles or for legal\nreasons.\n\nFinally, include the URLs in your `urlpatterns`::\n\n from django.urls import include, path\n\n urlpatterns = [\n path(\"icons/\", include(\"dj_iconify.urls\")),\n ]\n\nUsage\n-----\n\nIconify SVG Framework\n~~~~~~~~~~~~~~~~~~~~~\n\nTo use the `Iconify SVG Framework`_, get its JavaScript from somewhere\n(e.g. using `django-yarnpkg`_ again, or directly from the CDN, from your\now nstatic files, or wherever).\n\n`django-iconify`_ provides a view that returns a small JavaScript snippet\nthat configures the `Iconify SVG Framework`_ to use its API endpoints. In\nthe following example, we first load this configuration snippet, then\ninclude the `Iconify SVG Framework`_ from the CDN (do not do this in\nproduction, where data protection matters)::\n\n <script type=\"text/javascript\" src=\"{% url 'config.js' %}\"></script>\n <script type=\"text/javascript\" src=\"https://code.iconify.design/1/1.0.6/iconify.min.js\"></script>\n\nLoading SVG directly (\"How to use Iconify in CSS\")\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n`django-iconify`_ also implements the direct SVG API. For now, you have to use\nDjango's regular URL reverse resolver to construct an SVG URL, or craft it\nby hand::\n\n <img src=\"{% url 'iconify_svg' 'mdi' 'account' %}?rotate=90deg %}\" />\n\nDocumentation on what query parameters are supported can be found in the\ndocumentation on `How to use Iconify in CSS`_.\n\nIn the future, a template tag will be available to simplify this.\n\nIncluding SVG in template directly\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n*Not implemented yet*\n\nIn the future, a template tag will be available to render SVG icons directly\ninto the template, which can be helpful in situations where retrieving external\nresources in undesirable, like HTML e-mails.\n\nExample\n-------\n\nThe source distribution as well as the `Git repository`_ contain a full example\napplication that serves the API under `/icons/` and a test page under `/test.html`.\n\nIt is reduced to a minimal working example for the reader's convenience.\n\n.. _Iconify: https://iconify.design/\n.. _django-iconify: https://edugit.org/AlekSIS/libs/django-iconify\n.. _poetry: https://python-poetry.org/\n.. _JSON collection: https://github.com/iconify/collections-json\n.. _django-yarnpkg: https://edugit.org/AlekSIS/libs/django-yarnpkg\n.. _Iconify SVG Framework: https://docs.iconify.design/implementations/svg-framework/\n.. _How to use Iconify in CSS: https://docs.iconify.design/implementations/css.html\n.. _Git repository: https://edugit.org/AlekSIS/libs/django-iconify\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Iconify API implementation and tools for Django projects",
"version": "0.4",
"project_urls": {
"Homepage": "https://edugit.org/AlekSIS/libs/django-iconify",
"Repository": "https://edugit.org/AlekSIS/libs/django-iconify"
},
"split_keywords": [
"iconify",
"icons",
"svg",
"django"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2111e41512b660881aa94ae5f2b08ec59870a1588504595051c46509e4a6a575",
"md5": "3528facd1df4163b86366677c1c2653a",
"sha256": "3e93b8d6361e7fb32b725593d04a7667309cff6fd732f2dd1376a2b2b55ef2d6"
},
"downloads": -1,
"filename": "django_iconify-0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3528facd1df4163b86366677c1c2653a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 19573,
"upload_time": "2023-12-04T23:21:04",
"upload_time_iso_8601": "2023-12-04T23:21:04.386697Z",
"url": "https://files.pythonhosted.org/packages/21/11/e41512b660881aa94ae5f2b08ec59870a1588504595051c46509e4a6a575/django_iconify-0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b933ec379f67cab37270e07f70f043524d163d2221221127430a49f821c18b47",
"md5": "c190f3dc7d9e05779988dad7201c4174",
"sha256": "9c14614bf4e02ecd8b94dad11e11668250be8390a663ec88ce68b0c4b4165c92"
},
"downloads": -1,
"filename": "django_iconify-0.4.tar.gz",
"has_sig": false,
"md5_digest": "c190f3dc7d9e05779988dad7201c4174",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 16750,
"upload_time": "2023-12-04T23:21:05",
"upload_time_iso_8601": "2023-12-04T23:21:05.692268Z",
"url": "https://files.pythonhosted.org/packages/b9/33/ec379f67cab37270e07f70f043524d163d2221221127430a49f821c18b47/django_iconify-0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-04 23:21:05",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "django-iconify"
}
JSON