Skip to content
GitLab
Explore
Sign in
Primary navigation
Search or go to…
Project
D
django-cleavejs
Manage
Activity
Members
Labels
Plan
Issues
Issue boards
Milestones
Wiki
Code
Merge requests
Repository
Branches
Commits
Tags
Repository graph
Compare revisions
Deploy
Releases
Package Registry
Model registry
Operate
Terraform modules
Monitor
Incidents
Service Desk
Analyze
Value stream analytics
Contributor analytics
Repository analytics
Model experiments
Help
Help
Support
GitLab documentation
Compare GitLab plans
Community forum
Contribute to GitLab
Provide feedback
Terms and privacy
Keyboard shortcuts
?
Snippets
Groups
Projects
Show more breadcrumbs
AlekSIS®
Libraries
django-cleavejs
Commits
eae93c0e
Verified
Commit
eae93c0e
authored
4 years ago
by
Nik | Klampfradler
Browse files
Options
Downloads
Patches
Plain Diff
Update README forgotten on fork
parent
d253948a
No related branches found
Branches containing commit
No related tags found
Tags containing commit
No related merge requests found
Changes
1
Hide whitespace changes
Inline
Side-by-side
Showing
1 changed file
README.rst
+41
-74
41 additions, 74 deletions
README.rst
with
41 additions
and
74 deletions
README.rst
+
41
−
74
View file @
eae93c0e
Iconify API implementation and tools
for Django
project
s
======================================
==================
Cleave.js integration
for Django
form
s
======================================
This re-usable app he
p
ls 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 hel
p
s 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.DjIconify
Config",
"dj_
cleavejs.apps.DjCleaveJS
Config",
...
]
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
re
sources in undesirable, like HTML e-mail
s.
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
p
re
-configured widgets for certain type
s.
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
un
d
er `/test.html`.
application that serves a test
form
un
t
er `/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
This diff is collapsed.
Click to expand it.
Preview
0%
Loading
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Save comment
Cancel
Please
register
or
sign in
to comment