Use jSignature jQuery plugin in your django projects
Project description
A simple way to use jSignature jQuery plugin in your Django projects.
It provides:
A form field and a form widget to handle jquery plugin through a Django form;
A model field to store a captured signature;
A mixin adding two fields (signature / signature_date) in any of your Django models.
A template filter to render signatures as base64 image urls.
Installation
pip install django-jsignature
Usage
Add jsignature to your INSTALLED_APPS:
# settings.py
INSTALLED_APPS = (
...
'jsignature',
)Use provided model field (for easy storage):
# models.py
from django.db import models
from jsignature.fields import JSignatureField
class SignatureModel(models.Model):
signature = JSignatureField()In your form template
{{ form.media }}
<form action="" method="post">
{{ form }}
<input type="submit" value="Save" />
{% csrf_token %}
</form>Render image from db value in your display template:
{# yourtemplate.html #}
{% load jsignature_filters %}
<img src="{{ obj.signature|signature_base64 }}" alt="{{ obj }}" />By default, jSignature is made to work outside of admin, requiring that you include the jQuery library in your <head>.
If you want to use jSignature in the Django admin site, set the JSIGNATURE_JQUERY setting to admin. Otherwise if set to any url pointing to jQuery, it will be automatically included.
It is strongly suggested to take example from example_project, which is located in this repo
Customization
JSignature plugin options are available in python:
Globally, in your settings:
# settings.py
JSIGNATURE_WIDTH = 500
JSIGNATURE_HEIGHT = 200Specifically, in your form:
# forms.py
from jsignature.forms import JSignatureField
from jsignature.widgets import JSignatureWidget
JSignatureField(widget=JSignatureWidget(jsignature_attrs={'color': '#CCC'}))Available settings are:
JSIGNATURE_WIDTH (width)
JSIGNATURE_HEIGHT (height)
JSIGNATURE_COLOR (color)
JSIGNATURE_BACKGROUND_COLOR (background-color)
JSIGNATURE_DECOR_COLOR (decor-color)
JSIGNATURE_LINE_WIDTH (lineWidth)
JSIGNATURE_UNDO_BUTTON (UndoButton)
JSIGNATURE_RESET_BUTTON (ResetButton)
In your models
If you want to store signatures easily, a provided mixin gives a signature and a signature_date that update themselves:
from django.db import models
from jsignature.mixins import JSignatureFieldsMixin
class JSignatureModel(JSignatureFieldsMixin):
name = models.CharField()In your forms
If you need more precise handling of the form field, you can use it directly:
# forms.py
from django import forms
from jsignature.forms import JSignatureField
class SignatureForm(forms.Form):
signature = JSignatureField()And upon saving, have direct access to the image with draw_signature()
# views.py
from jsignature.utils import draw_signature
from myapp.forms import SignatureForm
def my_view(request):
form = SignatureForm(request.POST or None)
if form.is_valid():
signature = form.cleaned_data.get('signature')
if signature:
# as an image
signature_picture = draw_signature(signature)
# or as a file
signature_file_path = draw_signature(signature, as_file=True)Example project
If you want to have a demo of this package, just use the example project:
git clone https://github.com/fle/django-jsignature.git
cd django-jsignature
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -e .
cd example_project
./manage.py migrate
./manage.py createsuperuserFill the user info, launch django with ./manage.py runserver and head over to http://127.0.0.1:8000/, you can also login to the admin with the credentials your provided.
Authors
Florent Lebreton <florent.lebreton@makina-corpus.com> (original author)
Sébastien Corbin <sebastien.corbin@makina-corpus.com> (maintainer)
CHANGELOG
0.12 (2024-01-27)
** Bug fixed **
Draw single points
** New **
Updated Github Actions.
Dropped support for python < 3.8
Dropped support for Django < 4.2
Add support for pillow >= 10
Updated jSignature to latest version
0.11 (2022-01-17)
** New **
Django 4.0 compatibility.
Moved to Github Actions for testing.
Added flake8 in CI.
Dropped support for python < 3.6
Dropped support for Django 1.11, 2.0, 2.1, 3.0, 3.1.
0.10 (2020-07-26)
** New **
Add template filter to easily render a signature structure as base64 url.
Add a full example of front-office usage.
0.9 (2020-04-18)
** New **
Add support for Django 2+
Drop support for Django<1.11
Add a JSIGNATURE_JQUERY settings to handle usage in admin in Django 2.1+
0.8 (2014-12-04)
** New **
Add support for Python 3 (@Gagaro)
Add support for Django 1.7 (@Gagaro)
0.7.6 (2014-11-26)
** New features **
A setting to display (or not) the reset button has been added (@jsayles)
** Internal changes **
Rendering is now based on a template (@andybak)
Javascript is properly initialized (@andybak)
