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/templating.rst | 100 +++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 docs/quick_tutorial/templating.rst (limited to 'docs/quick_tutorial/templating.rst') diff --git a/docs/quick_tutorial/templating.rst b/docs/quick_tutorial/templating.rst new file mode 100644 index 000000000..f9393ecf6 --- /dev/null +++ b/docs/quick_tutorial/templating.rst @@ -0,0 +1,100 @@ +=================================== +08: HTML Generation With Templating +=================================== + +Most web frameworks don't embed HTML in programming code. Instead, +they pass data into a templating system. In this step we look at the +basics of using HTML templates in Pyramid. + +Background +========== + +Ouch. We have been making our own ``Response`` and filling the response +body with HTML. You usually won't embed an HTML string directly in +Python, but instead, will use a templating language. + +Pyramid doesn't mandate a particular database system, form library, +etc. It encourages replaceability. This applies equally to templating, +which is fortunate: developers have strong views about template +languages. That said, Pyramid bundles Chameleon and Mako, +so in this step, let's use Chameleon as an example. + +Objectives +========== + +- Generate HTML from template files + +- Connect the templates as "renderers" for view code + +- Change the view code to simply return data + +Steps +===== + +#. Let's begin by using the previous package as a starting point for a new + distribution, then making it active: + + .. code-block:: bash + + (env27)$ cd ..; cp -r views templating; cd templating + (env27)$ python setup.py develop + +#. Our ``templating/tutorial/views.py`` no longer has HTML in it: + + .. literalinclude:: templating/tutorial/views.py + :linenos: + +#. Instead we have ``templating/tutorial/home.pt`` as a template: + + .. literalinclude:: templating/tutorial/home.pt + :language: html + +#. For convenience, change ``templating/development.ini`` to reload + templates automatically with ``pyramid.reload_templates``: + + .. literalinclude:: templating/development.ini + :language: ini + +#. Our unit tests in ``templating/tutorial/tests.py`` can focus on + data: + + .. literalinclude:: templating/tutorial/tests.py + :linenos: + +#. Now run the tests: + + .. code-block:: bash + + + (env27)$ nosetests tutorial + . + ---------------------------------------------------------------------- + Ran 4 tests in 0.141s + + OK + +#. Run your Pyramid application with: + + .. code-block:: bash + + (env27)$ pserve development.ini --reload + +#. Open ``http://localhost:6543/`` and ``http://localhost:6543/howdy`` + in your browser. + +Analysis +======== + +Ahh, that looks better. We have a view that is focused on Python code. +Our ``@view_config`` decorator specifies a +:term:`pyramid:renderer` that points +our template file. Our view then simply returns data which is then +supplied to our template. Note that we used the same template for both +views. + +Note the effect on testing. We can focus on having a data-oriented +contract with our view code. + +.. seealso:: :ref:`pyramid:templates_chapter`, + :ref:`pyramid:debugging_templates`, and + :ref:`pyramid:mako_templates` -- cgit v1.2.3 From 4042c772c8043ac96a22db439a736fec9ea2aafa Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Fri, 13 Sep 2013 17:09:35 -0400 Subject: All the references re-wired. --- docs/quick_tutorial/templating.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/quick_tutorial/templating.rst') diff --git a/docs/quick_tutorial/templating.rst b/docs/quick_tutorial/templating.rst index f9393ecf6..ee4542485 100644 --- a/docs/quick_tutorial/templating.rst +++ b/docs/quick_tutorial/templating.rst @@ -87,7 +87,7 @@ Analysis Ahh, that looks better. We have a view that is focused on Python code. Our ``@view_config`` decorator specifies a -:term:`pyramid:renderer` that points +:term:`renderer` that points our template file. Our view then simply returns data which is then supplied to our template. Note that we used the same template for both views. @@ -95,6 +95,6 @@ views. Note the effect on testing. We can focus on having a data-oriented contract with our view code. -.. seealso:: :ref:`pyramid:templates_chapter`, - :ref:`pyramid:debugging_templates`, and - :ref:`pyramid:mako_templates` +.. seealso:: :ref:`templates_chapter`, + :ref:`debugging_templates`, and + :ref:`mako_templates` -- 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/templating.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/quick_tutorial/templating.rst') diff --git a/docs/quick_tutorial/templating.rst b/docs/quick_tutorial/templating.rst index ee4542485..5f3fb8975 100644 --- a/docs/quick_tutorial/templating.rst +++ b/docs/quick_tutorial/templating.rst @@ -36,8 +36,8 @@ Steps .. code-block:: bash - (env27)$ cd ..; cp -r views templating; cd templating - (env27)$ python setup.py develop + (env)$ cd ..; cp -r views templating; cd templating + (env)$ python setup.py develop #. Our ``templating/tutorial/views.py`` no longer has HTML in it: @@ -66,7 +66,7 @@ Steps .. code-block:: bash - (env27)$ nosetests tutorial + (env)$ nosetests tutorial . ---------------------------------------------------------------------- Ran 4 tests in 0.141s @@ -77,7 +77,7 @@ Steps .. code-block:: bash - (env27)$ pserve development.ini --reload + (env)$ pserve development.ini --reload #. Open ``http://localhost:6543/`` and ``http://localhost:6543/howdy`` in your browser. -- cgit v1.2.3 From 6625ddd9d78b1307aaff6b9c212c2fbbe926c9c0 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 14 Sep 2013 05:47:38 -0700 Subject: rename ref mako_templates to available_template_system_bindings --- docs/quick_tutorial/templating.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'docs/quick_tutorial/templating.rst') diff --git a/docs/quick_tutorial/templating.rst b/docs/quick_tutorial/templating.rst index 5f3fb8975..7210a7f8b 100644 --- a/docs/quick_tutorial/templating.rst +++ b/docs/quick_tutorial/templating.rst @@ -95,6 +95,5 @@ views. Note the effect on testing. We can focus on having a data-oriented contract with our view code. -.. seealso:: :ref:`templates_chapter`, - :ref:`debugging_templates`, and - :ref:`mako_templates` +.. seealso:: :ref:`templates_chapter`, :ref:`debugging_templates`, and + :ref:`available_template_system_bindings`. -- 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/templating.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/quick_tutorial/templating.rst') diff --git a/docs/quick_tutorial/templating.rst b/docs/quick_tutorial/templating.rst index 7210a7f8b..225c54eb3 100644 --- a/docs/quick_tutorial/templating.rst +++ b/docs/quick_tutorial/templating.rst @@ -36,8 +36,8 @@ Steps .. code-block:: bash - (env)$ cd ..; cp -r views templating; cd templating - (env)$ python setup.py develop + (venv)$ cd ..; cp -r views templating; cd templating + (venv)$ python setup.py develop #. Our ``templating/tutorial/views.py`` no longer has HTML in it: @@ -66,7 +66,7 @@ Steps .. code-block:: bash - (env)$ nosetests tutorial + (venv)$ nosetests tutorial . ---------------------------------------------------------------------- Ran 4 tests in 0.141s @@ -77,7 +77,7 @@ Steps .. code-block:: bash - (env)$ pserve development.ini --reload + (venv)$ pserve development.ini --reload #. Open ``http://localhost:6543/`` and ``http://localhost:6543/howdy`` in your 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/templating.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/quick_tutorial/templating.rst') diff --git a/docs/quick_tutorial/templating.rst b/docs/quick_tutorial/templating.rst index 225c54eb3..254629e57 100644 --- a/docs/quick_tutorial/templating.rst +++ b/docs/quick_tutorial/templating.rst @@ -79,7 +79,7 @@ Steps (venv)$ pserve development.ini --reload -#. Open ``http://localhost:6543/`` and ``http://localhost:6543/howdy`` +#. Open http://localhost:6543/ and http://localhost:6543/howdy in your 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/templating.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/quick_tutorial/templating.rst') diff --git a/docs/quick_tutorial/templating.rst b/docs/quick_tutorial/templating.rst index 254629e57..ba236d9da 100644 --- a/docs/quick_tutorial/templating.rst +++ b/docs/quick_tutorial/templating.rst @@ -36,8 +36,8 @@ Steps .. code-block:: bash - (venv)$ cd ..; cp -r views templating; cd templating - (venv)$ python setup.py develop + $ cd ..; cp -r views templating; cd templating + $ $VENV/bin/python setup.py develop #. Our ``templating/tutorial/views.py`` no longer has HTML in it: @@ -66,7 +66,7 @@ Steps .. code-block:: bash - (venv)$ nosetests tutorial + $ $VENV/bin/nosetests tutorial . ---------------------------------------------------------------------- Ran 4 tests in 0.141s @@ -77,7 +77,7 @@ Steps .. code-block:: bash - (venv)$ pserve development.ini --reload + $ $VENV/bin/pserve development.ini --reload #. Open http://localhost:6543/ and http://localhost:6543/howdy in your browser. -- cgit v1.2.3 From 34e974e360184baef873da55f31379697e367f32 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Wed, 25 Sep 2013 12:08:33 -0400 Subject: Get pyramid_chameleon added to the quick tutorial, plus some other fixes for Python 3. --- docs/quick_tutorial/templating.rst | 34 ++++++++++++++++++++++++++++------ 1 file changed, 28 insertions(+), 6 deletions(-) (limited to 'docs/quick_tutorial/templating.rst') diff --git a/docs/quick_tutorial/templating.rst b/docs/quick_tutorial/templating.rst index ba236d9da..136a494a0 100644 --- a/docs/quick_tutorial/templating.rst +++ b/docs/quick_tutorial/templating.rst @@ -16,12 +16,18 @@ Python, but instead, will use a templating language. Pyramid doesn't mandate a particular database system, form library, etc. It encourages replaceability. This applies equally to templating, which is fortunate: developers have strong views about template -languages. That said, Pyramid bundles Chameleon and Mako, -so in this step, let's use Chameleon as an example. +languages. As of Pyramid 1.5a2, Pyramid doesn't even bundle a template +language! + +It does, however, have strong ties to Jinja2, Mako, and Chameleon. In +this step we see how to add ``pyramid_chameleon`` to your project, +then change your views to use templating. Objectives ========== +- Enable the ``pyramid_chameleon`` Pyramid add-on + - Generate HTML from template files - Connect the templates as "renderers" for view code @@ -31,14 +37,31 @@ Objectives Steps ===== -#. Let's begin by using the previous package as a starting point for a new - distribution, then making it active: +#. Let's begin by using the previous package as a starting point for a + new project: .. code-block:: bash $ cd ..; cp -r views templating; cd templating + +#. This step depends on ``pyramid_chameleon``, so add it as a dependency + in ``templating/setup.py``: + + .. literalinclude:: templating/setup.py + :linenos: + +#. Now we can activate the development-mode distribution: + + .. code-block:: bash + $ $VENV/bin/python setup.py develop +#. We need to connect ``pyramid_chameleon`` as a renderer by making a + call in the setup of ``templating/tutorial/__init__.py``: + + .. literalinclude:: templating/tutorial/__init__.py + :linenos: + #. Our ``templating/tutorial/views.py`` no longer has HTML in it: .. literalinclude:: templating/tutorial/views.py @@ -86,8 +109,7 @@ Analysis ======== Ahh, that looks better. We have a view that is focused on Python code. -Our ``@view_config`` decorator specifies a -:term:`renderer` that points +Our ``@view_config`` decorator specifies a :term:`renderer` that points our template file. Our view then simply returns data which is then supplied to our template. Note that we used the same template for both views. -- 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/templating.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/quick_tutorial/templating.rst') diff --git a/docs/quick_tutorial/templating.rst b/docs/quick_tutorial/templating.rst index 136a494a0..d73067f48 100644 --- a/docs/quick_tutorial/templating.rst +++ b/docs/quick_tutorial/templating.rst @@ -1,3 +1,5 @@ +.. _qtut_templating: + =================================== 08: HTML Generation With Templating =================================== -- cgit v1.2.3