Installation

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

$ poetry add django-cleavejs

Then, add it to your INSTALLED_APPS setting to make its static files available:

INSTALLED_APPS = [
    ...
    "dj_cleavejs.apps.DjCleaveJSConfig",
    ...
]

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 cleave.js Yarn package:

YARN_INSTALLED_APPS = [
  "cleave.js",
]
NODE_MODULES_ROOT = os.path.join(BASE_DIR, "node_modules")
STATICFILES_FINDERS += ["django_yarnpkg.finders.NodeModulesFinder"]

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:

CLEAVE_JS = "cleave.js/dist/cleave.min.js"

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

Once available, you can create a form as normal and use the widget on any CharField:

from django.forms import CharField, Form

from dj_cleavejs import CleaveWidget


class TestForm(Form):
    windows_xp_serial = CharField(widget=CleaveWidget(blocks=[5, 5, 5, 5, 5],
                            delimiter="-"))

In your template, make sure to include the form media of your form somewhere after the form.

The CleaveWidget supports all options Cleave.js supports, as described in its options documentation. In the future, django-cleavejs will also provide shortcuts.

Example

The source distribution as well as the Git repository contain a full example application that serves a test form unter /test.html.

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