{
"info": {
"author": "Uros Trstenjak",
"author_email": "uros.trstenjak@gmail.com",
"bugtrack_url": null,
"classifiers": [
"Development Status :: 5 - Production/Stable",
"Framework :: Django",
"Intended Audience :: Developers",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
"Programming Language :: Python",
"Programming Language :: Python :: 2",
"Programming Language :: Python :: 2.7",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.3",
"Programming Language :: Python :: 3.4",
"Programming Language :: Python :: 3.5",
"Programming Language :: Python :: 3.6",
"Programming Language :: Python :: 3.7",
"Topic :: Software Development :: Libraries :: Python Modules"
],
"description": "============================\nDjango Bootstrap Modal Forms\n============================\n\nA Django plugin for creating AJAX driven forms in Bootstrap modal.\n\nLive Demo\n=========\n\nDemo_\n\n.. _Demo: https://trco.si/dbmf/\n\nInstallation\n============\n\n1. Install ``django-bootstrap-modal-forms``::\n\n $ pip install django-bootstrap-modal-forms\n\n2. Add ``bootstrap_modal_forms`` to your INSTALLED_APPS in settings.py::\n\n INSTALLED_APPS = [\n ...\n 'bootstrap_modal_forms',\n ...\n ]\n\n3. Include Bootstrap, jQuery and ``jquery.bootstrap.modal.forms.js`` on every page where you would like to set up the AJAX driven Django forms in Bootstrap modal.\n\nIMPORTANT: Adjust Bootstrap and jQuery file paths to match yours, but include ``jquery.bootstrap.modal.forms.js`` exactly as in code bellow.\n\n.. code-block:: html+django\n\n \n \n \n\n \n \n \n \n \n \n \n\nHow it works?\n=============\n.. code-block:: html\n\n index.html\n\n \n\n1. Click event on html element instantiated with ``modalForm`` opens modal\n2. Form at ``formURL`` is appended to the modal\n3. On submit the form is POSTed via AJAX request to ``formURL``\n4. **Unsuccessful POST request** returns errors, which are shown in modal\n5. **Successful POST request** submits the form and redirects to ``success_url`` and shows ``success_message``, which are both defined in related Django view\n\nUsage\n=====\n\n1. Form\n*******\n\nDefine ModelForm and inherit built-in form ``BSModalForm``.\n\n.. code-block:: python\n\n forms.py\n\n from .models import Book\n from bootstrap_modal_forms.forms import BSModalForm\n\n class BookForm(BSModalForm):\n class Meta:\n model = Book\n fields = ['title', 'author', 'price']\n\n2. Form's html\n**************\n\nDefine form's html and save it as Django template.\n\n- Bootstrap 4 modal elements are used in this example.\n- Button triggering the submission should have type attribute set to ``\"button\"`` and not ``\"submit\"``.\n- Add ``class=\"submit-btn\"`` or custom ``submitBtn`` class (see paragraph **Options**) to this button.\n- Form will POST to ``formURL`` defined in #6.\n- Add ``class=\"invalid\"`` or custom ``errorClass`` (see paragraph **Options**) to the elements that wrap the fields.\n- ``class=\"invalid\"`` acts as a flag for the fields having errors after the form has been POSTed.\n\n.. code-block:: html\n\n book/create_book.html\n\n \n\n3. Class-based view\n*******************\n\nDefine a class-based view BookCreateView and inherit from built-in generic view ``BSModalCreateView``. BookCreateView processes the form defined in #1, uses the template defined in #2 and redirects to ``success_url`` showing ``success_message``.\n\n.. code-block:: python\n\n views.py\n\n from django.urls import reverse_lazy\n from .forms import BookForm\n from .models import Book\n from bootstrap_modal_forms.generic import BSModalCreateView\n\n class BookCreateView(BSModalCreateView):\n template_name = 'examples/create_book.html'\n form_class = BookForm\n success_message = 'Success: Book was created.'\n success_url = reverse_lazy('index')\n\n4. URL for the view\n*******************\n\nDefine URL for the view in #3.\n\n.. code-block:: python\n\n from django.urls import path\n from books import views\n\n urlpatterns = [\n path('', views.Index.as_view(), name='index'),\n path('create/', views.BookCreateView.as_view(), name='create_book'),\n ]\n\n5. Bootstrap modal and trigger element\n**************************************\n\nDefine the Bootstrap modal window and html element triggering modal opening.\n\n- Same modal window can be used for multiple ``modalForms`` in single template (see #6).\n- Trigger element (in this example button with ``create-book`` class) is used for instantiation of ``modalForm`` in #6.\n- Any element can be trigger element as long as ``modalForm`` is bound to it.\n- Click event on trigger element loads form's html from #2 within ```` and sets action attribute of the form to ``formURL`` set in #6.\n\n.. code-block:: html+django\n\n index.html\n\n
\n
\n
\n\n
\n
\n
\n\n \n \n\n6. modalForm\n************\n\nAdd script to the template from #5 and bind the ``modalForm`` to the trigger element. Set BookCreateView URL defined in #4 as ``formURL`` property of ``modalForm``.\n\n- If you want to create **more modalForms in single template using the same modal window** from #5, repeat steps #1 to #4, create new trigger element as in #5 and bind the new ``modalForm`` with unique URL to it.\n- Default values for ``modalID``, ``modalContent``, ``modalForm`` and ``errorClass`` are used in this example, while ``formURL`` is customized. If you customize any other option adjust the code of the above examples accordingly.\n\n.. code-block:: html\n\n index.html\n\n \n\nmodalForm options\n=================\n\nmodalID\n Sets the custom id of the modal. ``Default: \"#modal\"``\n\nmodalContent\n Sets the custom class of the element to which the form's html is appended. If you change ``modalContent`` to the custom class, you should also change ``modalForm`` accordingly. To keep Bootstrap's modal style you should than copy Bootstrap's style for ``modal-content`` and set it to your new modalContent class. ``Default: \".modal-content\"``\n\nmodalForm\n Sets the custom form selector. ``Default: \".modal-content form\"``\n\nformURL\n Sets the url of the form's view and html. ``Default: null``\n\nerrorClass\n Sets the custom class for the form fields having errors. ``Default: \".invalid\"``\n\nsubmitBtn\n Sets the custom class for the button triggering form submission in modal. ``Default: \".submit-btn\"``\n\nGeneric views\n=============\n\nImport generic views with ``from bootstrap_modal_forms.generic import BSModalCreateView``.\n\nBSModalCreateView\n Inherits PassRequestMixin and Django's SuccessMessageMixin and generic.CreateView.\n\nBSModalUpdateView\n Inherits PassRequestMixin and Django's SuccessMessageMixin and generic.UpdateView.\n\nBSModalReadView\n Inherits Django's generic.DetailView.\n\nBSModalDeleteView\n Inherits DeleteMessageMixin and Django's generic.DeleteView.\n\nForms\n=====\n\nImport forms with ``from bootstrap_modal_forms.forms import BSModalForm``.\n\nBSModalForm\n Inherits PopRequestMixin, CreateUpdateAjaxMixin and Django's forms.ModelForm.\n\nMixins\n======\n\nImport mixins with ``from bootstrap_modal_forms.mixins import PassRequestMixin``.\n\nPassRequestMixin\n Puts the request into the form's kwargs.\n\nPopRequestMixin\n Pops request out of the kwargs and attaches it to the form's instance.\n\nCreateUpdateAjaxMixin\n Saves or doesn't save the object based on the request type.\n\nDeleteMessageMixin\n Deletes object if request is not ajax request.\n\nLoginAjaxMixin\n Authenticates user if request is not ajax request.\n\nExamples\n========\n\nTo see ``django-bootstrap-modal-forms`` in action clone the repository and run the examples locally::\n\n $ git clone https://github.com/trco/django-bootstrap-modal-forms.git\n $ cd django-bootstrap-modal-forms\n $ pip install -r requirements.txt\n $ python manage.py migrate\n $ python manage.py runserver\n\nTests\n=====\n\nRun unit and functional tests inside of project folder::\n\n $ python manage.py test\n\nExample 1: Signup form in Bootstrap modal\n*****************************************\n\nFor explanation how all the parts of the code work together see paragraph **Usage**. To test the working solution presented here clone and run **Examples**.\n\n.. code-block:: python\n\n forms.py\n\n from django.contrib.auth.forms import UserCreationForm\n from django.contrib.auth.models import User\n from bootstrap_modal_forms.mixins import PopRequestMixin, CreateUpdateAjaxMixin\n\n\n class CustomUserCreationForm(PopRequestMixin, CreateUpdateAjaxMixin,\n UserCreationForm):\n class Meta:\n model = User\n fields = ['username', 'password1', 'password2']\n\n.. code-block:: html\n\n signup.html\n\n {% load widget_tweaks %}\n\n \n\n.. code-block:: python\n\n views.py\n\n from django.urls import reverse_lazy\n from bootstrap_modal_forms.generic import BSModalCreateView\n from .forms import CustomUserCreationForm\n\n class SignUpView(BSModalCreateView):\n form_class = CustomUserCreationForm\n template_name = 'examples/signup.html'\n success_message = 'Success: Sign up succeeded. You can now Log in.'\n success_url = reverse_lazy('index')\n\n.. code-block:: python\n\n urls.py\n\n from django.urls import path\n from . import views\n\n app_name = 'accounts'\n urlpatterns = [\n path('signup/', views.SignUpView.as_view(), name='signup')\n ]\n\n\n.. code-block:: html\n\n .html file containing modal, trigger element and script instantiating modalForm\n\n
\n
\n \n
\n
\n\n \n\n \n\nExample 2: Login form in Bootstrap modal\n****************************************\n\nFor explanation how all the parts of the code work together see paragraph **Usage**. To test the working solution presented here clone and run **Examples**.\n\nYou can set the login redirection by setting the ``LOGIN_REDIRECT_URL`` in ``settings.py``.\n\nYou can also set the custom login redirection by:\n\n1. Adding ``success_url`` to the ``extra_context`` of ``CustomLoginView``\n2. Setting this ``success_url`` variable as a value of the ``hidden input field`` with ``name=\"next\"`` within the Login form html\n\n.. code-block:: python\n\n forms.py\n\n from django.contrib.auth.forms import AuthenticationForm\n from django.contrib.auth.models import User\n\n class CustomAuthenticationForm(AuthenticationForm):\n class Meta:\n model = User\n fields = ['username', 'password']\n\n.. code-block:: html\n\n login.html\n\n {% load widget_tweaks %}\n\n \n\n.. code-block:: python\n\n views.py\n\n from django.urls import reverse_lazy\n from bootstrap_modal_forms.generic import BSModalLoginView\n from .forms import CustomAuthenticationForm\n\n class CustomLoginView(BSModalLoginView):\n authentication_form = CustomAuthenticationForm\n template_name = 'examples/login.html'\n success_message = 'Success: You were successfully logged in.'\n extra_context = dict(success_url=reverse_lazy('index'))\n\n.. code-block:: python\n\n urls.py\n\n from django.urls import path\n from . import views\n\n app_name = 'accounts'\n urlpatterns = [\n path('login/', views.CustomLoginView.as_view(), name='login')\n ]\n\n.. code-block:: html\n\n .html file containing modal, trigger element and script instantiating modalForm\n\n
\n
\n \n
\n
\n\n \n\n \n\nExample 3: CRUD forms in Bootstrap modal\n****************************************\n\nFor explanation how all the parts of the code work together see paragraph **Usage**. To test the working solution presented here clone and run **Examples**.\n\n.. code-block:: python\n\n forms.py\n\n from .models import Book\n from bootstrap_modal_forms.forms import BSModalForm\n\n\n class BookForm(BSModalForm):\n class Meta:\n model = Book\n exclude = ['timestamp']\n\n.. code-block:: html\n\n create_book.html\n\n {% load widget_tweaks %}\n\n \n\n.. code-block:: html\n\n update_book.html\n\n {% load widget_tweaks %}\n\n \n\n.. code-block:: html\n\n read_book.html\n\n {% load widget_tweaks %}\n\n
\n
Book details
\n \n
\n\n
\n\n
\n Title:\n {{ book.title }}\n
\n
\n Author:\n {{ book.author }}\n
\n
\n Price:\n {{ book.price }}\n \u20ac\n
\n\n
\n\n \n\n.. code-block:: html\n\n {% load widget_tweaks %}\n\n \n\n.. code-block:: python\n\n views.py\n\n from django.urls import reverse_lazy\n from django.views import generic\n from .forms import BookForm\n from .models import Book\n from bootstrap_modal_forms.generic import (BSModalCreateView,\n BSModalUpdateView,\n BSModalReadView,\n BSModalDeleteView)\n\n class Index(generic.ListView):\n model = Book\n context_object_name = 'books'\n template_name = 'index.html'\n\n # Create\n class BookCreateView(BSModalCreateView):\n template_name = 'examples/create_book.html'\n form_class = BookForm\n success_message = 'Success: Book was created.'\n success_url = reverse_lazy('index')\n\n # Update\n class BookUpdateView(BSModalUpdateView):\n model = Book\n template_name = 'examples/update_book.html'\n form_class = BookForm\n success_message = 'Success: Book was updated.'\n success_url = reverse_lazy('index')\n\n # Read\n class BookReadView(BSModalReadView):\n model = Book\n template_name = 'examples/read_book.html'\n\n # Delete\n class BookDeleteView(BSModalDeleteView):\n model = Book\n template_name = 'examples/delete_book.html'\n success_message = 'Success: Book was deleted.'\n success_url = reverse_lazy('index')\n\n.. code-block:: python\n\n urls.py\n\n from django.urls import path\n from books import views\n\n urlpatterns = [\n path('', views.Index.as_view(), name='index'),\n path('create/', views.BookCreateView.as_view(), name='create_book'),\n path('update/', views.BookUpdateView.as_view(), name='update_book'),\n path('read/', views.BookReadView.as_view(), name='read_book'),\n path('delete/', views.BookDeleteView.as_view(), name='delete_book')\n ]\n\n.. code-block:: html\n\n .html file containing modal, trigger elements and script instantiating modalForms\n\n