diff -r 76ab3c71aff2 -r c67bcee93248 doc/book/en/devweb/views/basetemplates.rst --- a/doc/book/en/devweb/views/basetemplates.rst Mon Jul 06 17:39:35 2015 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,161 +0,0 @@ -.. -*- coding: utf-8 -*- - -.. _templates: - -Templates -========= - -Templates are the entry point for the |cubicweb| view system. As seen -in :ref:`views_base_class`, there are two kinds of views: the -templatable and non-templatable. - - -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: - -* set up the proper document header and content type -* define the general layout of a document -* 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 :class:`~cubicweb.web.views.basetemplates.TheMainTemplate`. - -.. _the_main_template_layout: - -TheMainTemplate -~~~~~~~~~~~~~~~ - -.. _the_main_template_sections: - -Layout and sections -``````````````````` - -A page is composed as indicated on the schema below : - -.. image:: ../../images/main_template.png - -The sections dispatches specific views: - -* `header`: the rendering of the header is delegated to the - `htmlheader` view, whose default implementation can be found in - ``basetemplates.py`` and which does the following things: - - * inject the favicon if there is one - * inject the global style sheets and javascript resources - * call and display a link to an rss component if there is one available - - it also sets up the page title, and fills the actual - `header` section with top-level components, using the `header` view, which: - - * tries to display a logo, the name of the application and the `breadcrumbs` - * provides a login status area - * provides a login box (hiden by default) - -* `left column`: this is filled with all selectable boxes matching the - `left` context (there is also a right column but nowadays it is - seldom used due to bad usability) - -* `contentcol`: this is the central column; it is filled with: - - * the `rqlinput` view (hidden by default) - * the `applmessages` component - * the `contentheader` view which in turns dispatches all available - content navigation components having the `navtop` context (this - is used to navigate through entities implementing the IPrevNext - interface) - * the view that was given as input to the template's `call` - method, also dealing with pagination concerns - * the `contentfooter` - -* `footer`: adds all footer actions - -.. note:: - - How and why a view object is given to the main template is explained - in the :ref:`publisher` chapter. - -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 a unicode string**, encoded string otherwise. - -* `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 a 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 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) - -* `vtitle`, a title to be set as

of the content - -Other templates -~~~~~~~~~~~~~~~ - -There are also the following other standard templates: - -* :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).