1 .. -*- coding: utf-8 -*-

     2 

     3 .. |cubicweb| replace:: *CubicWeb*

     4 

     5 .. _templates:

     6 

     7 Templates

     8 =========

     9 

    10 Templates are the entry point for the |cubicweb| view system. As seen

    11 in :ref:`views_base_class`, there are two kinds of views: the

    12 templatable and non-templatable.

    13 

    14 Non-templatable views are standalone. They are responsible for all the

    15 details such as setting a proper content type (or mime type), the

    16 proper document headers, namespaces, etc. Examples are pure xml views

    17 such as RSS or Semantic Web views (`SIOC`_, `DOAP`_, `FOAF`_, `Linked

    18 Data`_, etc.).

    19 

    20 .. _`SIOC`: http://sioc-project.org/

    21 .. _`DOAP`: http://trac.usefulinc.com/doap

    22 .. _`FOAF`: http://www.foaf-project.org/

    23 .. _`Linked Data`: http://linkeddata.org/

    24 

    25 Templatable views are not concerned with such pesky details. They

    26 leave it to the template. Conversely, the template's main job is to:

    27 

    28 * set up the proper document header and content type

    29 * define the general layout of a document

    30 * invoke adequate views in the various sections of the document

    31 

    32 

    33 Look at :mod:`cubicweb.web.views.basetemplates` and you will find the

    34 base templates used to generate (X)HTML for your application. The most

    35 important template there is `TheMainTemplate`.

    36 

    37 .. _the_main_template_layout:

    38 

    39 TheMainTemplate

    40 ---------------

    41 

    42 .. _the_main_template_sections:

    43 

    44 Layout and sections

    45 ```````````````````

    46 

    47 A page is composed as indicated on the schema below :

    48 

    49 .. image:: ../../../images/main_template.png

    50 

    51 The sections dispatches specific views:

    52 

    53 * `header`: the rendering of the header is delegated to the

    54   `htmlheader` view, whose default implementation can be found in

    55   ``basetemplates.py`` and which does the following things:

    56 

    57     * inject the favicon if there is one

    58     * inject the global style sheets and javascript resources

    59     * call and display a link to an rss component if there is one available

    60 

    61   it also sets up the page title, and fills the actual

    62   `header` section with top-level components, using the `header` view, which:

    63 

    64     * tries to display a logo, the name of the application and the `breadcrumbs`

    65     * provides a login status area

    66     * provides a login box (hiden by default)

    67 

    68 * `left column`: this is filled with all selectable boxes matching the

    69   `left` context (there is also a right column but nowadays it is

    70   seldom used due to bad usability)

    71 

    72 * `contentcol`: this is the central column; it is filled with:

    73 

    74     * the `rqlinput` view (hidden by default)

    75     * the `applmessages` component

    76     * the `contentheader` view which in turns dispatches all available

    77       content navigation components having the `navtop` context (this

    78       is used to navigate through entities implementing the IPrevNext

    79       interface)

    80     * the view that was given as input to the template's `call`

    81       method, also dealing with pagination concerns

    82     * the `contentfooter`

    83 

    84 * `footer`: adds all footer actions

    85 

    86 .. note::

    87 

    88   How and why a view object is given to the main template is explained

    89   in the :ref:`publisher` chapter.

    90 

    91 Class attributes

    92 ````````````````

    93 

    94 We can also control certain aspects of the main template thanks to the following

    95 forms parameters:

    96 

    97 * `__notemplate`, if present (whatever the value assigned), only the content view

    98   is returned

    99 * `__force_display`, if present and its value is not null, no navigation

   100   whatever the number of entities to display

   101 * `__method`, if the result set to render contains only one entity and this

   102   parameter is set, it refers to a method to call on the entity by passing it

   103   the dictionary of the forms parameters, before going the classic way (through

   104   step 1 and 2 described juste above)

   105 

   106 Other templates

   107 ---------------

   108 

   109 Other standard templates include:

   110 

   111 * `login` and `logout`

   112 

   113 * `error-template` specializes TheMainTemplate to do proper end-user

   114   output if an error occurs during the computation of TheMainTemplate

   115   (it is a fallback view).