From b1b92284f496800a4dfd2cea72cb9be07ba8661c Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Fri, 13 Sep 2013 16:52:14 -0400 Subject: First cut at import of quick tutorial. --- docs/quick_tutorial/forms.rst | 146 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 docs/quick_tutorial/forms.rst (limited to 'docs/quick_tutorial/forms.rst') diff --git a/docs/quick_tutorial/forms.rst b/docs/quick_tutorial/forms.rst new file mode 100644 index 000000000..bb7cab3f7 --- /dev/null +++ b/docs/quick_tutorial/forms.rst @@ -0,0 +1,146 @@ +==================================== +18: Forms and Validation With Deform +==================================== + +Schema-driven, autogenerated forms with validation. + +Background +========== + +Modern web applications deal extensively with forms. Developers, +though, have a wide range of philosophies about how frameworks should +help them with their forms. As such, Pyramid doesn't directly bundle +one particular form library. Instead, there are a variety of form +libraries that are easy to use in Pyramid. + +:ref:`Deform ` +is one such library. In this step, we introduce Deform for our +forms and validation. This also gives us the +:ref:`Colander ` for schemas and validation. + +Deform is getting a facelift, with styling from Twitter Bootstrap and +advanced widgets from popular JavaScript projects. The work began in +``deform_bootstrap`` and is being merged into an update to Deform. + +Objectives +========== + +- Make a schema using Colander, the companion to Deform + +- Create a form with Deform and change our views to handle validation + +Steps +===== + +#. First we copy the results of the ``view_classes`` step: + + .. code-block:: bash + + (env27)$ cd ..; cp -r view_classes forms; cd forms + +#. Let's edit ``forms/setup.py`` to declare a dependency on Deform + (which then pulls in Colander as a dependency: + + .. literalinclude:: forms/setup.py + :linenos: + +#. We can now install our project in development mode: + + .. code-block:: bash + + (env27)$ python setup.py develop + +#. Register a static view in ``forms/tutorial/__init__.py`` for + Deform's CSS/JS etc. as well as our demo wikipage scenario's + views: + + .. literalinclude:: forms/tutorial/__init__.py + :linenos: + +#. Implement the new views, as well as the form schemas and some + dummy data, in ``forms/tutorial/views.py``: + + .. literalinclude:: forms/tutorial/views.py + :linenos: + +#. A template for the top of the "wiki" in + ``forms/tutorial/wiki_view.pt``: + + .. literalinclude:: forms/tutorial/wiki_view.pt + :language: html + :linenos: + +#. Another template for adding/editing in + ``forms/tutorial/wikipage_addedit.pt``: + + .. literalinclude:: forms/tutorial/wikipage_addedit.pt + :language: html + :linenos: + +#. Finally, a template at ``forms/tutorial/wikipage_view.pt`` + for viewing a wiki page: + + .. literalinclude:: forms/tutorial/wikipage_view.pt + :language: html + :linenos: + +#. Run your Pyramid application with: + + .. code-block:: bash + + (env27)$ pserve development.ini --reload + +#. Open ``http://localhost:6543/`` in a browser. + + +Analysis +======== + +This step helps illustrate the utility of asset specifications for +static assets. We have an outside package called Deform with static +assets which need to be published. We don't have to know where on disk +it is located. We point at the package, then the path inside the package. + +We just need to include a call to ``add_static_view`` to make that +directory available at a URL. For Pyramid-specific pages, +Pyramid provides a facility (``config.include()``) which even makes +that unnecessary for consumers of a package. (Deform is not specific to +Pyramid.) + +Our forms have rich widgets which need the static CSS and JS just +mentioned. Deform has a :term:`resource registry` which allows widgets +to specify which JS and CSS are needed. Our ``wikipage_addedit.pt`` +template shows how we iterated over that data to generate markup that +includes the needed resources. + +Our add and edit views use a pattern called *self-posting forms*. +Meaning, the same URL is used to ``GET`` the form as is used to +``POST`` the form. The route, the view, and the template are the same +whether you are walking up to it the first time or you clicked a button. + +Inside the view we do ``if 'submit' in self.request.params:`` to see if +this form was a ``POST`` where the user clicked on a particular button +````. + +The form controller then follows a typical pattern: + +- If you are doing a GET, skip over and just return the form + +- If you are doing a POST, validate the form contents + +- If the form is invalid, bail out by re-rendering the form with the + supplied ``POST`` data + +- If the validation succeeded, perform some action and issue a + redirect via ``HTTPFound``. + +We are, in essence, writing our own form controller. Other +Pyramid-based systems, including ``pyramid_deform``, provide a +form-centric view class which automates much of this branching and +routing. + +Extra Credit +============ + +#. Give a try at a button that goes to a delete view for a + particular wiki page. -- cgit v1.2.3 From 0a784868bdbc3a0eb226ed00e8d89cda9d181ec5 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Fri, 13 Sep 2013 17:11:42 -0400 Subject: Fix naming of virtualenv prefix. --- docs/quick_tutorial/forms.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/quick_tutorial/forms.rst') diff --git a/docs/quick_tutorial/forms.rst b/docs/quick_tutorial/forms.rst index bb7cab3f7..21692832f 100644 --- a/docs/quick_tutorial/forms.rst +++ b/docs/quick_tutorial/forms.rst @@ -36,7 +36,7 @@ Steps .. code-block:: bash - (env27)$ cd ..; cp -r view_classes forms; cd forms + (env)$ cd ..; cp -r view_classes forms; cd forms #. Let's edit ``forms/setup.py`` to declare a dependency on Deform (which then pulls in Colander as a dependency: @@ -48,7 +48,7 @@ Steps .. code-block:: bash - (env27)$ python setup.py develop + (env)$ python setup.py develop #. Register a static view in ``forms/tutorial/__init__.py`` for Deform's CSS/JS etc. as well as our demo wikipage scenario's @@ -88,7 +88,7 @@ Steps .. code-block:: bash - (env27)$ pserve development.ini --reload + (env)$ pserve development.ini --reload #. Open ``http://localhost:6543/`` in a browser. -- cgit v1.2.3 From b0b28ede912c817a62a84b97c332e39eda02d166 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 16 Sep 2013 02:14:53 +0200 Subject: s/env/venv just for sake of consistency --- docs/quick_tutorial/forms.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/quick_tutorial/forms.rst') diff --git a/docs/quick_tutorial/forms.rst b/docs/quick_tutorial/forms.rst index 21692832f..43ae84240 100644 --- a/docs/quick_tutorial/forms.rst +++ b/docs/quick_tutorial/forms.rst @@ -36,7 +36,7 @@ Steps .. code-block:: bash - (env)$ cd ..; cp -r view_classes forms; cd forms + (venv)$ cd ..; cp -r view_classes forms; cd forms #. Let's edit ``forms/setup.py`` to declare a dependency on Deform (which then pulls in Colander as a dependency: @@ -48,7 +48,7 @@ Steps .. code-block:: bash - (env)$ python setup.py develop + (venv)$ python setup.py develop #. Register a static view in ``forms/tutorial/__init__.py`` for Deform's CSS/JS etc. as well as our demo wikipage scenario's @@ -88,7 +88,7 @@ Steps .. code-block:: bash - (env)$ pserve development.ini --reload + (venv)$ pserve development.ini --reload #. Open ``http://localhost:6543/`` in a browser. -- cgit v1.2.3 From d749bf4c987c4ab90bd5f89326e7d4059e4f47b3 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 16 Sep 2013 02:18:11 +0200 Subject: make example links clickable, for convenience --- docs/quick_tutorial/forms.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/quick_tutorial/forms.rst') diff --git a/docs/quick_tutorial/forms.rst b/docs/quick_tutorial/forms.rst index 43ae84240..fdf052b39 100644 --- a/docs/quick_tutorial/forms.rst +++ b/docs/quick_tutorial/forms.rst @@ -90,7 +90,7 @@ Steps (venv)$ pserve development.ini --reload -#. Open ``http://localhost:6543/`` in a browser. +#. Open http://localhost:6543/ in a browser. Analysis -- cgit v1.2.3 From 187104fd81418beeb51592913041d9751bafe08d Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Wed, 25 Sep 2013 09:27:43 -0400 Subject: Quick Tutorial: Improve the setup instructions (adapted from Steve Piercy's work), particularly for Windows. Change all the steps to use $VENV/bin prefixes on commands (don't presume that they have done source env/bin/activate). --- docs/quick_tutorial/forms.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/quick_tutorial/forms.rst') diff --git a/docs/quick_tutorial/forms.rst b/docs/quick_tutorial/forms.rst index fdf052b39..0328ef528 100644 --- a/docs/quick_tutorial/forms.rst +++ b/docs/quick_tutorial/forms.rst @@ -36,7 +36,7 @@ Steps .. code-block:: bash - (venv)$ cd ..; cp -r view_classes forms; cd forms + $ cd ..; cp -r view_classes forms; cd forms #. Let's edit ``forms/setup.py`` to declare a dependency on Deform (which then pulls in Colander as a dependency: @@ -48,7 +48,7 @@ Steps .. code-block:: bash - (venv)$ python setup.py develop + $ $VENV/bin/python setup.py develop #. Register a static view in ``forms/tutorial/__init__.py`` for Deform's CSS/JS etc. as well as our demo wikipage scenario's @@ -88,7 +88,7 @@ Steps .. code-block:: bash - (venv)$ pserve development.ini --reload + $ $VENV/bin/pserve development.ini --reload #. Open http://localhost:6543/ in a browser. -- cgit v1.2.3 From b731b5fca253d9d95b3307490aa585e194676c01 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Thu, 26 Sep 2013 17:41:44 -0400 Subject: Quick Tour: shorten the setup part and point to Quick Tutorial Requirements for more explanation. Cross link each Quick Tour section with its Quick Tutorial match. --- docs/quick_tutorial/forms.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/quick_tutorial/forms.rst') diff --git a/docs/quick_tutorial/forms.rst b/docs/quick_tutorial/forms.rst index 0328ef528..e8bc0c8b4 100644 --- a/docs/quick_tutorial/forms.rst +++ b/docs/quick_tutorial/forms.rst @@ -1,3 +1,5 @@ +.. _qtut_forms: + ==================================== 18: Forms and Validation With Deform ==================================== -- cgit v1.2.3