Skip to content

Latest commit

 

History

History
208 lines (142 loc) · 5.36 KB

README.rst

File metadata and controls

208 lines (142 loc) · 5.36 KB
Raw

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.

Latest PyPI version

Build status

Coverage status

image

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 = 200
  • Specifically, 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 createsuperuser

Fill 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

makinacom_