# HG changeset patch # User Stephanie Marcu # Date 1285155197 -7200 # Node ID ca5d09ff0379845ca40925eed5039c9a374dc3db # Parent d9d6bdd814baf6b8fcc60456f1fc32a5246fe408 [book - #1251259] reorganize plan for basetemplate, talk about class attributes diff -r d9d6bdd814ba -r ca5d09ff0379 doc/book/en/devweb/views/basetemplates.rst --- 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

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). diff -r d9d6bdd814ba -r ca5d09ff0379 web/views/basecontrollers.py --- 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: