[book - #1251259] reorganize plan for basetemplate, talk about class attributes stable
authorStephanie Marcu <stephanie.marcu@logilab.fr>
Wed, 22 Sep 2010 13:33:17 +0200
branchstable
changeset 6302 ca5d09ff0379
parent 6301 d9d6bdd814ba
child 6303 1aad5389c013
[book - #1251259] reorganize plan for basetemplate, talk about class attributes
doc/book/en/devweb/views/basetemplates.rst
web/views/basecontrollers.py
--- a/doc/book/en/devweb/views/basetemplates.rst	Wed Sep 22 13:15:14 2010 +0200
+++ b/doc/book/en/devweb/views/basetemplates.rst	Wed Sep 22 13:33:17 2010 +0200
@@ -11,17 +11,33 @@
 in :ref:`views_base_class`, there are two kinds of views: the
 templatable and non-templatable.
 
-Non-templatable views are standalone. They are responsible for all the
-details such as setting a proper content type (or mime type), the
-proper document headers, namespaces, etc. Examples are pure xml views
-such as RSS or Semantic Web views (`SIOC`_, `DOAP`_, `FOAF`_, `Linked
-Data`_, etc.).
+
+Non-templatable views
+---------------------
+
+Non-templatable views are standalone. They are responsible for all the details
+such as setting a proper content type (or mime type), the proper document
+headers, namespaces, etc. Examples are pure xml views such as RSS or Semantic Web
+views (`SIOC`_, `DOAP`_, `FOAF`_, `Linked Data`_, etc.), and views which generate
+binary files (pdf, excel files, etc.)
 
 .. _`SIOC`: http://sioc-project.org/
 .. _`DOAP`: http://trac.usefulinc.com/doap
 .. _`FOAF`: http://www.foaf-project.org/
 .. _`Linked Data`: http://linkeddata.org/
 
+
+To notice that a view is not templatable, you just have to set the
+view's class attribute `templatable` to `False`. In this case, it
+should set the `content_type` class attribute to the correct MIME
+type. By default, it is text/xhtml. Additionally, if your view
+generate a binary file, you have to set the view's class attribute
+`binary` to `True` too.
+
+
+Templatable views
+-----------------
+
 Templatable views are not concerned with such pesky details. They
 leave it to the template. Conversely, the template's main job is to:
 
@@ -30,14 +46,14 @@
 * invoke adequate views in the various sections of the document
 
 
-Look at :mod:`cubicweb.web.views.basetemplates` and you will find the
-base templates used to generate (X)HTML for your application. The most
-important template there is `TheMainTemplate`.
+Look at :mod:`cubicweb.web.views.basetemplates` and you will find the base
+templates used to generate (X)HTML for your application. The most important
+template there is :class:`~cubicweb.web.views.basetemplates.TheMainTemplate`.
 
 .. _the_main_template_layout:
 
 TheMainTemplate
----------------
+~~~~~~~~~~~~~~~
 
 .. _the_main_template_sections:
 
@@ -88,28 +104,60 @@
   How and why a view object is given to the main template is explained
   in the :ref:`publisher` chapter.
 
-Class attributes
-````````````````
+Configure the main template
+```````````````````````````
+
+You can overload some methods of the
+:class:`~cubicweb.web.views.basetemplates.TheMainTemplate`, in order to fulfil
+your needs. There are also some attributes and methods which can be defined on a
+view to modify the base template behaviour:
+
+* `paginable`: if the result set is bigger than a configurable size, your result
+  page will be paginated by default. You can set this attribute to `False` to
+  avoid this.
+
+* `binary`: boolean flag telling if the view generates some text or a binary
+  stream.  Default to False. When view generates text argument given to `self.w`
+  **must be an unicode string**, encoded string otherwise.
 
-We can also control certain aspects of the main template thanks to the following
-forms parameters:
+* `content_type`, view's content type, default to 'text/xhtml'
+
+* `templatable`, boolean flag telling if the view's content should be returned
+  directly (when `False`) or included in the main template layout (including
+  header, boxes and so on).
+
+* `page_title()`, method that should return a title that will be set as page
+  title in the html headers.
+
+* `html_headers()`, method that should return a list of HTML headers to be
+  included the html headers.
+
+
+You can also modify certain aspects of the main template of a page
+when building an url or setting these parameters in the req.form:
 
 * `__notemplate`, if present (whatever the value assigned), only the content view
   is returned
-* `__force_display`, if present and its value is not null, no navigation
-  whatever the number of entities to display
+
+* `__force_display`, if present and its value is not null, no pagination whatever
+  the number of entities to display (e.g. similar effect as view's `paginable`
+  attribute described above.
+
 * `__method`, if the result set to render contains only one entity and this
-  parameter is set, it refers to a method to call on the entity by passing it
-  the dictionary of the forms parameters, before going the classic way (through
-  step 1 and 2 described juste above)
+  parameter is set, it refers to a method to call on the entity by passing it the
+  dictionary of the forms parameters, before going the classic way (through step
+  1 and 2 described juste above)
+
+* `vtitle`, a title to be set as <h1> of the content
 
 Other templates
----------------
+~~~~~~~~~~~~~~~
 
-Other standard templates include:
+There are also the following other standard templates:
 
-* `login` and `logout`
-
-* `error-template` specializes TheMainTemplate to do proper end-user
-  output if an error occurs during the computation of TheMainTemplate
-  (it is a fallback view).
+* :class:`cubicweb.web.views.basetemplates.LogInTemplate`
+* :class:`cubicweb.web.views.basetemplates.LogOutTemplate`
+* :class:`cubicweb.web.views.basetemplates.ErrorTemplate` specializes
+  :class:`~cubicweb.web.views.basetemplates.TheMainTemplate` to do
+  proper end-user output if an error occurs during the computation of
+  TheMainTemplate (it is a fallback view).
--- a/web/views/basecontrollers.py	Wed Sep 22 13:15:14 2010 +0200
+++ b/web/views/basecontrollers.py	Wed Sep 22 13:33:17 2010 +0200
@@ -160,7 +160,7 @@
         return view, rset
 
     def add_to_breadcrumbs(self, view):
-        # update breadcrumps **before** validating cache, unless the view
+        # update breadcrumbs **before** validating cache, unless the view
         # specifies explicitly it should not be added to breadcrumb or the
         # view is a binary view
         if view.add_to_breadcrumbs and not view.binary: