From 643efeb092aaaf7520a99e50bdcbce4449089a13 Mon Sep 17 00:00:00 2001 From: Stuart George Date: Wed, 25 Oct 2017 20:18:24 +0100 Subject: [PATCH] check docs to make sure all is sensible --- docs/forms.rst | 7 +++---- docs/submission.rst | 12 ++++++------ docs/templates.rst | 4 ++-- docs/usage.rst | 6 +++--- 4 files changed, 14 insertions(+), 15 deletions(-) diff --git a/docs/forms.rst b/docs/forms.rst index 07c72a6a..b96d8011 100644 --- a/docs/forms.rst +++ b/docs/forms.rst @@ -83,13 +83,12 @@ Example: return form_data .. note:: Its important to note here that the ``form.page`` and ``form.user`` seen above are passed in via the - ``wagtailstreamforms.models.StreamFormPageMixin`` which is for forms that post to their own page. + ``before_serve_page`` hook ``wagtailstreamforms.wagtail_hooks.process_form``. If you want to use a different method of saving the form and you require these you will need to pass - them in yourself. + them in yourself when adding ``request.POST`` to the form. - Example usage cam be seen in the mixins serve method - `here `_. + Example usage can be seen in :ref:`rst_provide_own_submission` Reference --------- diff --git a/docs/submission.rst b/docs/submission.rst index c282b802..f1d978dd 100644 --- a/docs/submission.rst +++ b/docs/submission.rst @@ -3,13 +3,17 @@ Form Submission Form submissions are handled by the means of a wagtail ``before_serve_page`` hook. The built in hook at ``wagtailstreamforms.wagtail_hooks.process_form`` looks for a form in the post request, -and either processes it redirecting back to the current page or just renders the page with -any validation errors if there are any. +and either: + +* processes it redirecting back to the current page or defined page in the form setup. +* or renders the current page with any validation error. If no form was posted then the page serves in the usual manner. .. note:: Currently the hook expects the form to be posting to the same page it exists on. +.. _rst_provide_own_submission: + Providing your own submission method ------------------------------------ @@ -22,10 +26,6 @@ If you do not want the current hook to be used you need to disable it by setting With this set no forms will be processed of any kind and you are free to process them how you feel fit. -* Your own hook -* A page mixin -* A view in django - An example of a hook: .. code-block:: python diff --git a/docs/templates.rst b/docs/templates.rst index 9d03f0db..f3046873 100644 --- a/docs/templates.rst +++ b/docs/templates.rst @@ -4,7 +4,7 @@ Form Templates You can create your own form templates to use against any form in the system, providing a vast array of ways to create, style and submit your forms. -The default `template `_ used can be seen below: +The default template located at ``streamforms/form_block.html`` can be seen below: .. code-block:: html @@ -18,7 +18,7 @@ The default `template -.. note:: It is important here to keep the hidden fields the form will create an additional field for the form id. +.. note:: It is important here to keep the hidden fields as the form will have some in order to process correctly. Once you have created you own you will need to add it to the list of available templates. diff --git a/docs/usage.rst b/docs/usage.rst index 77164e4a..2b65d4f9 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -16,7 +16,7 @@ And you are ready to go. Using the template tag ---------------------- -There is also a template tag you can use outside of a streamfield (but within a page served by wagtail). +There is also a template tag you can use outside of a streamfield, within a page. All this is doing is rendering the form using the same block as in the streamfield. @@ -26,12 +26,12 @@ The tag takes three parameters: * **reference**: This should be a unique string and needs to be persistent on refresh/reload. See note below. * **action**: The form action url. -.. note:: The reference is used when the form is being validated. +.. warning:: The reference is used when the form is being validated. Because you can have any number of the same form on a page there needs to be a way of uniquely identifying the form beyond its ``PK``. This is so that when the form has validation errors and it is passed back through the pages context, We know what form it is. - This reference MUST be persistent on page refresh or you will never see the errors. + This reference **MUST** be persistent on page refresh or you will never see the errors. Usage: