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 From ee2313a6842d12ae0db91c14da3855e3f7dd0632 Mon Sep 17 00:00:00 2001 From: Jay Martin Date: Tue, 14 Oct 2014 09:09:36 -0400 Subject: typo fix --- 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 e8bc0c8b4..b08167edc 100644 --- a/docs/quick_tutorial/forms.rst +++ b/docs/quick_tutorial/forms.rst @@ -104,7 +104,7 @@ 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, +directory available at a URL. For Pyramid-specific packages, Pyramid provides a facility (``config.include()``) which even makes that unnecessary for consumers of a package. (Deform is not specific to Pyramid.) -- cgit v1.2.3 From 003b9aaef924ba3934a8e23854be5b7a6e6ae7e0 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 22 May 2015 17:37:58 -0700 Subject: - add jQuery to the template - punctuation, grammar --- 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 b08167edc..f81b88fc2 100644 --- a/docs/quick_tutorial/forms.rst +++ b/docs/quick_tutorial/forms.rst @@ -12,13 +12,13 @@ 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 +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. +forms and validation. This also gives us :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 -- cgit v1.2.3 From 9845f718ccd609b6ecf514b165a4fd2f9dfb8d8c Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 7 Apr 2016 03:30:26 -0700 Subject: - update forms.rst --- 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 f81b88fc2..023e7127f 100644 --- a/docs/quick_tutorial/forms.rst +++ b/docs/quick_tutorial/forms.rst @@ -50,7 +50,7 @@ Steps .. code-block:: bash - $ $VENV/bin/python setup.py develop + $ $VENV/bin/pip install -e . #. Register a static view in ``forms/tutorial/__init__.py`` for Deform's CSS/JS etc. as well as our demo wikipage scenario's -- cgit v1.2.3 From 59c8fc7919730c3f3100ad84250a788e2d0a3bb0 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 16 Apr 2016 12:55:28 -0700 Subject: quick_tutorial cleanup - replace nose with pytest - cleanup forms.rst --- docs/quick_tutorial/forms.rst | 127 ++++++++++++++++++++++-------------------- 1 file changed, 66 insertions(+), 61 deletions(-) (limited to 'docs/quick_tutorial/forms.rst') diff --git a/docs/quick_tutorial/forms.rst b/docs/quick_tutorial/forms.rst index 023e7127f..6b29833bd 100644 --- a/docs/quick_tutorial/forms.rst +++ b/docs/quick_tutorial/forms.rst @@ -6,30 +6,30 @@ 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. +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 :ref:`Colander ` +:ref:`Deform ` is one such library. In this step, we introduce +Deform for our forms. This also gives us :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. +Deform uses styling from Twitter Bootstrap and advanced widgets from popular +JavaScript projects. + Objectives ========== -- Make a schema using Colander, the companion to Deform +- Make a schema using Colander, the companion to Deform. + +- Create a form with Deform and change our views to handle validation. -- Create a form with Deform and change our views to handle validation Steps ===== @@ -40,8 +40,8 @@ Steps $ 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: +#. 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: @@ -52,21 +52,19 @@ Steps $ $VENV/bin/pip install -e . -#. Register a static view in ``forms/tutorial/__init__.py`` for - Deform's CSS/JS etc. as well as our demo wikipage scenario's - views: +#. Register a static view in ``forms/tutorial/__init__.py`` for Deform's CSS, + JavaScript, etc., as well as our demo wiki page'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``: +#. 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``: +#. A template for the top of the "wiki" in ``forms/tutorial/wiki_view.pt``: .. literalinclude:: forms/tutorial/wiki_view.pt :language: html @@ -79,13 +77,21 @@ Steps :language: html :linenos: -#. Finally, a template at ``forms/tutorial/wikipage_view.pt`` - for viewing a wiki page: +#. Finally, a template at ``forms/tutorial/wikipage_view.pt`` for viewing a + wiki page: .. literalinclude:: forms/tutorial/wikipage_view.pt :language: html :linenos: +#. Run the tests: + + .. code-block:: bash + + $ $VENV/bin/py.test tutorial/tests.py -q + .. + 2 passed in 0.45 seconds + #. Run your Pyramid application with: .. code-block:: bash @@ -98,51 +104,50 @@ Steps 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 packages, -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 +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 packages, 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 JavaScript just +mentioned. Deform has a :term:`resource registry` which allows widgets to +specify which JavaScript 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 URL whether you are walking up +to it for 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 ``GET``, skip over and just return the form. + +- If you are doing a ``POST``, validate the form contents. -- 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 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``. -- 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. -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 +Extra credit ============ -#. Give a try at a button that goes to a delete view for a - particular wiki page. +#. Give a try at a button that goes to a delete view for a particular wiki + page. -- cgit v1.2.3