Starting from CubicWeb version 4.0 all code related to generating html views has been moved to the Cube cubicweb_web.

If you want to migrate a project from 3.38 to 4.* while still using all the html views you need to both install the cubicweb_web cube AND add it to your dependencies and run add_cube('web').

cubicweb_web can be installed from pypi this way:

pip install cubicweb_web

We don’t plan to maintain the features in cubicweb_web in the long run; we are moving to a full javascript frontend using both cubicweb_api (which exposes a HTTP API) and @cubicweb/client as a frontend javascript toolkit.

In the long run cubicweb_api will be merged inside of CubicWeb.


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#

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#

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 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.


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.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


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

Other templates#

There are also the following other standard templates:

  • cubicweb_web.views.basetemplates.LogInTemplate

  • cubicweb_web.views.basetemplates.LogOutTemplate

  • cubicweb_web.views.basetemplates.ErrorTemplate specializes TheMainTemplate to do proper end-user output if an error occurs during the computation of TheMainTemplate (it is a fallback view).