Skip to content
Snippets Groups Projects
Verified Commit eae93c0e authored by Nik | Klampfradler's avatar Nik | Klampfradler
Browse files

Update README forgotten on fork

parent d253948a
No related branches found
No related tags found
No related merge requests found
Iconify API implementation and tools for Django projects
========================================================
Cleave.js integration for Django forms
======================================
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.
This re-usable app helps integrating `Cleave.js`_ into Django projects.
Cleave.js is a JavaScript library that can "help you format input text
content automatically".
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-cleavejs`_ eases integration into Django. It wraps `Cleave.js`_'s
options object into a form widget class, which takes care of transporting
the options to JavaScript and initialising `Cleave.js`_ for each such
input field.
`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
To add `django-cleavejs`_ to a project, first add it as dependency to your
project, e.g. using `poetry`_::
$ poetry add django-iconify
$ poetry add django-cleavejs
Then, add it to your `INSTALLED_APPS` setting to make its views available
later::
Then, add it to your `INSTALLED_APPS` setting to make its static files
available::
INSTALLED_APPS = [
...
"dj_iconify.apps.DjIconifyConfig",
"dj_cleavejs.apps.DjCleaveJSConfig",
...
]
You need to make the `JSON collection`_ available by some means. You can
You need to make `Cleave.js`_ itself 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`
instance, you could use `django-yarnpkg`_ to depend on the `cleave.js`
Yarn package::
YARN_INSTALLED_APPS = [
"@iconify/json",
"cleave.js",
]
NODE_MODULES_ROOT = os.path.join(BASE_DIR, "node_modules")
STATICFILES_FINDERS += ["django_yarnpkg.finders.NodeModulesFinder"]
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")
You can then either include it in your template yourself, or make
`django-cleavejs`_ add it to its form media by configuring the URL or
path in your settings::
If you do not use `django-yarnpkg`_, construct the path manually, ot use
whatever mechanism your asset manager provides.
CLEAVE_JS = "cleave.js/dist/cleave.min.js"
Finally, include the URLs in your `urlpatterns`::
from django.urls import include, path
urlpatterns = [
path("icons/", include("dj_iconify.urls")),
]
The above example uses the path below `STATIC_ROOT` where `django-yarnpkg`_
would put the package, but you can of course use any URL or path you want
depending on how you want to make `Cleave.js`_ available to the browser.
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::
Once available, you can create a form as normal and use the widget
on any `CharField`::
<img src="{% url 'iconify_svg' 'mdi' 'account' %}?rotate=90deg %}" />
from django.forms import CharField, Form
Documentation on what query parameters are supported can be found in the
documentation on `How to use Iconify in CSS`_.
from dj_cleavejs import CleaveWidget
In the future, a template tag will be available to simplify this.
Including SVG in template directly
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
class TestForm(Form):
windows_xp_serial = CharField(widget=CleaveWidget(blocks=[5, 5, 5, 5, 5],
delimiter="-"))
*Not implemented yet*
In your template, make sure to include the form media of your form somewhere
**after** the form.
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.
Right now, only simple fields with blocks and delimiters are supported. In the
future, `django-cleavejs`_ will support all `Cleave.js`_ options and also provide
pre-configured widgets for certain types.
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`.
application that serves a test form unter `/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
.. _django-cleavejs: https://edugit.org/AlekSIS/libs/django-cleavejs
.. _poetry: https://python-poetry.org/
.. _JSON collection: https://github.com/iconify/collections-json
.. _Cleave.js: https://nosir.github.io/cleave.js/
.. _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
.. _Git repository: https://edugit.org/AlekSIS/libs/django-cleavejs
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment