+
−.. -*- coding: utf-8 -*-
+
−
+
−.. |cubicweb| replace:: *CubicWeb*
+
−
+
−.. _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 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.).
+
−
+
−.. _`SIOC`: http://sioc-project.org/
+
−.. _`DOAP`: http://trac.usefulinc.com/doap
+
−.. _`FOAF`: http://www.foaf-project.org/
+
−.. _`Linked Data`: http://linkeddata.org/
+
−
+
−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 `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.
+
−
+
−Class attributes
+
−````````````````
+
−
+
−We can also control certain aspects of the main template thanks to the following
+
−forms parameters:
+
−
+
−* `__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
+
−* `__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)
+
−
+
−Other templates
+
−---------------
+
−
+
−Other standard templates include:
+
−
+
−* `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).