Added documetation & credential property

.gitignore

@@ -2,4 +2,4 @@ database/db.sqlite3
 geckodriver.log
 __pycache__
 *.pyc
-.env/
+.env/

CHANGELOG.rst

@@ -2,6 +2,38 @@
 Changelog
 =========
 
+3.0.4 (2023-06-18)
+==================
+
+- fix broken examples by bumping django-widget-tweaks dependency version
+
+3.0.3 (2023-06-04)
+==================
+
+- add get_success_message method in FormValidationMixin
+
+
+3.0.2 (2023-05-02)
+==================
+
+- fix call to get_success_url method in FormValidationMixin
+
+3.0.1 (2023-05-02)
+==================
+
+- fix redirect in FormValidationMixin
+
+3.0.0 (2023-05-02)
+==================
+
+- deprecate support for python < 3.8
+- deprecate support for Django < 3.2
+- deprecate SuccessMessageMixin
+- add FormValidationMixin
+- add support for Chrome, Firefox, Edge and Safari drivers when running funtional tests
+- update examples to Django=4.2
+- update README.rst
+
 2.2.1 (2023-03-05)
 ==================
 

README.rst

@@ -4,23 +4,43 @@ Django Bootstrap Modal Forms
 
 A Django plugin for creating AJAX driven forms in Bootstrap modal.
 
-Live Demo
-=========
-
-Demo_
-
-.. _Demo: http://trco.silkym.com/dbmf/
+.. contents:: **Table of Contents**
+   :depth: 2
+   :local:
+   :backlinks: none
 
 Test and experiment on your machine
 ===================================
 
-This repository includes ``Dockerfile`` and ``docker-compose.yml`` files so you can easily setup and start to experiment with ``django-bootstrap-modal-forms`` running inside of a container on your local machine. Any changes you make in ``bootstrap_modal_forms``, ``examples`` and ``test`` folders are reflected in the container (see docker-compose.yml) and the data stored in sqlite3 database are persistent even if you remove stopped container. Follow the steps below to run the app::
+This repository includes ``Dockerfile`` and ``docker-compose.yml`` files so you can easily setup and start to experiment with ``django-bootstrap-modal-forms`` running inside of a container on your local machine. Any changes you make in ``bootstrap_modal_forms``, ``examples`` and ``test`` folders are reflected in the container (see docker-compose.yml) and the data stored in sqlite3 database are persistent even if you remove stopped container.
+
+Note that ``master branch`` contains Bootstrap 4 examples, while ``bootstrap5-examples branch`` contains Bootstrap 5 examples. To experiment with Bootstrap 5 examples simply switch the branch.
+
+Follow the steps below to run the app::
 
     $ clone repository
     $ cd django-bootstrap-modal-forms
     $ docker compose up (use -d flag to run app in detached mode in the background)
     $ visit 0.0.0.0:8000
 
+General information
+===================
+
+Opening an issue
+****************
+When reporting an issue for ``django-bootstrap-modal-forms`` package, please prepare a publicly available repository having the issue you are reporting. The clear reproduce is the optimal way towards resolution.
+
+Contribute
+**********
+This is an Open Source project and any contribution is highly appreciated.
+
+Tests
+=====
+
+Run unit and functional tests inside of project folder::
+
+    $ python manage.py test
+
 Installation
 ============
 
@@ -36,9 +56,7 @@ Installation
         ...
     ]
 
-3. 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.
-
-IMPORTANT: Adjust Bootstrap and jQuery file paths to match yours, but include ``jquery.bootstrap.modal.forms.js`` exactly as in code bellow.
+3. Include Bootstrap, jQuery and ``jquery.bootstrap(5).modal.forms.js`` on every page where you would like to set up the AJAX driven Django forms in Bootstrap modal. **IMPORTANT:** Adjust Bootstrap and jQuery file paths to match yours, but include ``jquery.bootstrap.modal.forms.js`` exactly as in code bellow.
 
 .. code-block:: html+django
 
@@ -50,12 +68,14 @@ IMPORTANT: Adjust Bootstrap and jQuery file paths to match yours, but include ``
         <script src="{% static 'assets/js/bootstrap.js' %}"></script>
 
         <!-- Bootstrap 4 -->
-        <script src="{% static 'assets/js/jquery.js' %}"></script>
-        <script src="{% static 'js/jquery.bootstrap.modal.forms.js' %}"></script>
+        <script src="{% static 'assets/js/jquery-3.2.1.min.js' %}"></script>
+        <script src="{% static 'assets/js/popper.min.js' %}"></script>
+        <script src="{% static 'assets/js/bootstrap.min.js' %}"></script>
         <!-- You can alternatively load the minified version -->
-        <script src="{% static 'js/jquery.bootstrap.modal.forms.min.js' %}"></script>
+        <script src="{% static 'js/jquery.bootstrap.modal.forms.js' %}"></script>
 
         <!-- Bootstrap 5 -->
+        <script src="{% static 'assets/js/bootstrap.bundle.min.js' %}"></script>
         <script src="{% static 'js/bootstrap5.modal.forms.js' %}"></script>
         <!-- You can alternatively load the minified version -->
         <script src="{% static 'js/bootstrap5.modal.forms.min.js' %}"></script>
@@ -129,10 +149,10 @@ Define BookModelForm and inherit built-in form ``BSModalModelForm``.
 
 Define form's html and save it as Django template.
 
-- Bootstrap 4 modal elements are used in this example.
 - Form will POST to ``formURL`` defined in #6.
-- Add ``class="invalid"`` or custom ``errorClass`` (see paragraph **Options**) to the elements that wrap the fields.
+- Add ``class="invalid"`` or custom ``errorClass`` (see paragraph **Options**) to the elements that wrap the fields
 - ``class="invalid"`` acts as a flag for the fields having errors after the form has been POSTed.
+- **IMPORTANT NOTE:** Bootstrap 4 modal elements are used in this example. ``class="invalid"`` is the default for Bootstrap 4. ``class="is-invalid"`` is the default for Bootstrap 5.
 
 .. code-block:: html
 
@@ -381,7 +401,7 @@ isDeleteForm
   Defines if form is used for deletion. Should be set to ``true`` for deletion forms.  ``Default: false``
 
 errorClass
-  Sets the custom class for the form fields having errors. ``Default: ".invalid"``
+  Sets the custom class for the form fields having errors. ``Default: ".invalid" for Boostrap 4 and ".is-invalid" for Bootstrap 5.``
 
 asyncUpdate
   Sets asynchronous content update after form submission. ``Default: false``
@@ -404,6 +424,40 @@ asyncSettings.dataKey
 asyncSettings.addModalFormFunction
   Sets the method needed for reinstantiation of event listeners on buttons (single or all CRUD buttons) after asynchronous update. ``Default: null``
 
+Fetch API parameters
+********************
+
+(@see `MDN Web DOCs - Using the Fetch API <https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch>`_).
+
+credentials:
+  Choices: omit, include, same-origin
+
+  ``Default: same-origin``
+method:
+  Choices: GET, POST, PUT, DELETE
+
+  ``Default: POST``
+mode:
+  Choices: no-cors, cors, same-origin
+
+  ``Default: cors``
+cache:
+  Choices: default, no-cache, reload, force-cache, only-if-cached
+
+  ``Default: no-cache``
+headers:
+  Choices: @see `MDN Web DOCs - HTTP headers <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers>`_
+
+  ``Default: { "Content-Type": "application/json" }``
+redirect:
+  Choices: manual, follow, error
+
+  ``Default: follow``
+referrerPolicy:
+  Choices: no-referrer, no-referrer-when-downgrade, origin, origin-when-cross-origin, same-origin, strict-origin, strict-origin-when-cross-origin, unsafe-url
+
+  ``Default: no-referrer``
+
 modalForm default settings object and it's structure
 ****************************************************
 
@@ -415,6 +469,7 @@ modalForm default settings object and it's structure
         modalForm: ".modal-content form",
         formURL: null,
         isDeleteForm: false,
+        // ".invalid" is the default for Bootstrap 4. ".is-invalid" is the default for Bootstrap 5.
         errorClass: ".invalid",
         asyncUpdate: false,
         asyncSettings: {
@@ -424,7 +479,17 @@ modalForm default settings object and it's structure
             dataElementId: null,
             dataKey: null,
             addModalFormFunction: null
-        }
+        },
+        // At this point Fetch API parameters
+        credentials: 'same-origin',
+        method: 'POST',
+        mode: 'cors',
+        cache: 'no-cache',
+        headers: {
+            'Content-Type': 'application/json'
+        },
+        redirect: 'follow',
+        referrerPolicy: 'no-referrer'
     });
 
 Forms
@@ -444,33 +509,39 @@ Mixins
 Import mixins with ``from bootstrap_modal_forms.mixins import PassRequestMixin``.
 
 PassRequestMixin
-    Puts the request into the form's kwargs.
+    Form Mixin which puts the request into the form's kwargs. Note: Using this mixin requires you to pop the `request` kwarg out of the dict in the super of your form's `__init__`. See PopRequestMixin.
 
 PopRequestMixin
-    Pops request out of the kwargs and attaches it to the form's instance.
+    Form Mixin which pops request out of the kwargs and attaches it to the form's instance. Note: This mixin must precede forms.ModelForm/forms.Form. The form is not expecting these kwargs to be passed in, so they must be popped off before anything else is done.
 
 CreateUpdateAjaxMixin
-    Saves or doesn't save the object based on the request type.
+    ModelForm Mixin which passes or saves object based on request type.
 
 DeleteMessageMixin
-    Deletes object if request is not ajax request.
+    Generic View Mixin which adds message to BSModalDeleteView and only calls the post method if request is not ajax request. In case request is ajax post method calls delete method, which redirects to success url.
+
+FormValidationMixin
+    Generic View Mixin which saves object and redirects to success_url if request is not ajax request. Otherwise response 204 No content is returned.
 
 LoginAjaxMixin
-    Authenticates user if request is not ajax request.
+    Generic View Mixin which authenticates user if request is not ajax request.
 
 Generic views
 =============
 
 Import generic views with ``from bootstrap_modal_forms.generic import BSModalFormView``.
 
+BSModalLoginView
+    Inhertis LoginAjaxMixin and Django's LoginView.
+
 BSModalFormView
     Inherits PassRequestMixin and Django's generic.FormView.
 
 BSModalCreateView
-    Inherits PassRequestMixin and Django's SuccessMessageMixin and generic.CreateView.
+    Inherits PassRequestMixin, FormValidationMixin and generic.CreateView.
 
 BSModalUpdateView
-    Inherits PassRequestMixin and Django's SuccessMessageMixin and generic.UpdateView.
+    Inherits PassRequestMixin, FormValidationMixin and generic.UpdateView.
 
 BSModalReadView
     Inherits Django's generic.DetailView.
@@ -489,13 +560,6 @@ To see ``django-bootstrap-modal-forms`` in action clone the repository and run t
     $ python manage.py migrate
     $ python manage.py runserver
 
-Tests
-=====
-
-Run unit and functional tests inside of project folder::
-
-    $ python manage.py test
-
 Example 1: Signup form in Bootstrap modal
 *****************************************
 
@@ -1115,11 +1179,6 @@ For explanation how all the parts of the code work together see paragraph **Usag
         });
       </script>
 
-Contribute
-==========
-
-This is an Open Source project and any contribution is appreciated.
-
 License
 =======