Add Templating section in scenario/web

diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst
index bd65373..3a81cd6 100644 (file)
--- a/docs/scenarios/web.rst
+++ b/docs/scenarios/web.rst
@@ -2,6 +2,9 @@
 Web Applications
 ================
 
+As a powerful scripting language adapted to both fast prototyping
+and bigger projects, Python is widely used in Web applications
+development.
 
 Context
 :::::::
@@ -203,6 +206,44 @@ Gondor publishes guides to deploying `Django projects
 <https://gondor.io/support/setting-up-pinax/>`_ on their platform.
 
 
+Templating
+::::::::::
+
+Most WSGI applications are responding to HTTP requests to serve
+content in HTML or other markup languages. Instead of generating directly
+textual content from Python, the concept of separation of concerns
+advise us to use templates. A template engine manage a suite of
+template files, with a system of hierarchy and inclusion to
+avoid unnecessary repetition, and is in charge of rendering
+(generating) the actual content, filling the static content
+of the templates with the dynamic content generated by the
+application.
+
+As template files are
+sometime written by designers or front-end developpers,
+it can be difficult to handle increasing complexity.
+
+Some general good pratices apply to the part of the
+application passing dynamic content to the template engine,
+and to the templates themselves.
+
+- Template files should be passed only the dynamic
+  content that is needed for rendering the template. Avoid
+  to be tempted to pass additional content "just in case":
+  it is easier to add some missing variable when needed than to remove
+  a likely unused variable later.
+
+- Many template engine allow for complex statements
+  or assignments in the template itself, and many
+  allow some Python code to be evaluated in the
+  templates. This convenience can lead to uncontrolled
+  increase in complexity, and often harder to find bugs.
+
+- It is often possible or necessary to mix javascript templates with
+  HTML templates. A sane approach to this design is to isolate
+  the parts where the HTML template passes some variable content
+  to the javascript code.
+
 .. rubric:: References
 
 .. [1] `The mod_python project is now officially dead <http://blog.dscpl.com.au/2010/06/modpython-project-is-now-officially.html>`_