From ea249473f19d9b0a74c056d7baa87a4bb288c05f Mon Sep 17 00:00:00 2001 From: Sebastien Corbin Date: Sun, 26 Jul 2020 15:58:12 +0200 Subject: [PATCH] Add full example of front-office usage --- README.rst | 103 +++++++++++------- example_project/templates/base.html | 39 +++++++ .../example_project/examplemodel_form.html | 14 +++ .../example_project/examplemodel_list.html | 24 ++++ example_project/urls.py | 7 +- example_project/views.py | 20 ++++ 6 files changed, 168 insertions(+), 39 deletions(-) create mode 100644 example_project/templates/base.html create mode 100644 example_project/templates/example_project/examplemodel_form.html create mode 100644 example_project/templates/example_project/examplemodel_list.html create mode 100644 example_project/views.py diff --git a/README.rst b/README.rst index bc85cca..e4fcf96 100644 --- a/README.rst +++ b/README.rst @@ -22,17 +22,15 @@ It provides: .. image:: https://github.com/fle/django-jsignature/blob/master/screen.png ================== -INSTALL +Installation ================== -For now: - :: pip install django-jsignature ================== -USAGE +Usage ================== * Add ``jsignature`` to your ``INSTALLED_APPS``: @@ -45,48 +43,37 @@ USAGE 'jsignature', ) -* Use provided form field and widget: +* Use provided model field (for easy storage): :: - # forms.py - from django import forms - from jsignature.forms import JSignatureField + # models.py + from django.db import models + from jsignature.fields import JSignatureField - class SignatureForm(forms.Form): + class SignatureModel(models.Model): signature = JSignatureField() -* In your template +* In your form template :: {{ form.media }} -
- {% for field in form %} - {{ field.label_tag }} - {{ field }} - {% endfor %} - + + {{ form }} + {% csrf_token %}
-* Render image after form validation: +* Render image from db value in your display template: :: - # views.py - from jsignature.utils import draw_signature - from myapp.forms import SignatureForm + {# yourtemplate.html #} + {% load jsignature_filters %} + + {{ obj }} - 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) * By default, jSignature is made to work outside of admin, requiring that you include the jQuery library in your ````. @@ -95,8 +82,11 @@ USAGE ``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 +Customization ================== JSignature plugin options are available in python: @@ -131,10 +121,11 @@ Available settings are: * ``JSIGNATURE_RESET_BUTTON`` (ResetButton) ================== -IN YOUR MODELS +In your models ================== -If you want to store signatures, provided mixin gives a ``signature`` and a ``signature_date`` that update themselves: +If you want to store signatures easily, a provided mixin gives a ``signature`` +and a ``signature_date`` that update themselves: :: @@ -145,6 +136,41 @@ If you want to store signatures, provided mixin gives a ``signature`` and a ``si 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 ================== @@ -163,16 +189,17 @@ If you want to have a demo of this package, just use the 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/ `_ and login with the -credentials your provided. +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 +Authors ================== - * Florent Lebreton - * Sébastien Corbin + * Florent Lebreton (original author) + * Sébastien Corbin (maintainer) |makinacom|_ diff --git a/example_project/templates/base.html b/example_project/templates/base.html new file mode 100644 index 0000000..092a8eb --- /dev/null +++ b/example_project/templates/base.html @@ -0,0 +1,39 @@ + + + + + + + + + + + Example project + + + + +
+ {% block content %}{% endblock %} +
+ + + + + {% block extra_media %}{% endblock %} + + diff --git a/example_project/templates/example_project/examplemodel_form.html b/example_project/templates/example_project/examplemodel_form.html new file mode 100644 index 0000000..b9cc13a --- /dev/null +++ b/example_project/templates/example_project/examplemodel_form.html @@ -0,0 +1,14 @@ +{% extends "base.html" %} + +{% block extra_media %} + {{ form.media }} +{% endblock %} + +{% block content %} +
+ {{ form }} + + Cancel + {% csrf_token %} +
+{% endblock %} diff --git a/example_project/templates/example_project/examplemodel_list.html b/example_project/templates/example_project/examplemodel_list.html new file mode 100644 index 0000000..c468059 --- /dev/null +++ b/example_project/templates/example_project/examplemodel_list.html @@ -0,0 +1,24 @@ +{% extends "base.html" %}{% load jsignature_filters %} + +{% block content %} +

List

+ +
    + {% for obj in object_list %} +
  • +
    +
    Raw data (from db)
    +
    {{ obj.signature }}
    +
    As image
    +
    + {{ obj }} + + Update + +
    +
    +
    • + {% endfor %} +
+ Create +{% endblock %} diff --git a/example_project/urls.py b/example_project/urls.py index 48e8c24..c2d0918 100644 --- a/example_project/urls.py +++ b/example_project/urls.py @@ -3,6 +3,11 @@ from __future__ import unicode_literals from django.contrib import admin from django.urls import path +from example_project import views + urlpatterns = [ - path('', admin.site.urls), + path('', views.ExampleListView.as_view(), name='list'), + path('create', views.ExampleCreateView.as_view(), name='create'), + path('update/', views.ExampleUpdateView.as_view(), name='update'), + path('admin', admin.site.urls), ] diff --git a/example_project/views.py b/example_project/views.py new file mode 100644 index 0000000..b164424 --- /dev/null +++ b/example_project/views.py @@ -0,0 +1,20 @@ +from django.urls import reverse_lazy +from django.views import generic + +from example_project.models import ExampleModel + + +class ExampleCreateView(generic.CreateView): + model = ExampleModel + fields = '__all__' + success_url = reverse_lazy('list') + + +class ExampleUpdateView(generic.UpdateView): + model = ExampleModel + fields = '__all__' + success_url = reverse_lazy('list') + + +class ExampleListView(generic.ListView): + model = ExampleModel