Templates are the entry point for the CubicWeb view system. As seen in Discovering possible views, 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.), and views which generate binary files (pdf, excel files, etc.)
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 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
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
Layout and sections¶
A page is composed as indicated on the schema below :
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.pyand which does the following things:
inject the favicon if there is one
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
footer: adds all footer actions
How and why a view object is given to the main template is explained in the Publisher chapter.
Configure the main template¶
You can overload some methods of the
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 <h1> of the content
There are also the following other standard templates:
TheMainTemplateto do proper end-user output if an error occurs during the computation of TheMainTemplate (it is a fallback view).