Warning

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.

Principles#

We’ll start with a description of the interface providing a basic understanding of the available classes and methods, then detail the view selection principle.

A View is an object responsible for the rendering of data from the model into an end-user consummable form. They typically churn out an XHTML stream, but there are views concerned with email other non-html outputs.

Discovering possible views#

It is possible to configure the web user interface to have a left box showing all the views than can be applied to the current result set.

To enable this, click on your login at the top right corner. Chose “user preferences”, then “boxes”, then “possible views box” and check “visible = yes” before validating your changes.

The views listed there we either not selected because of a lower score, or they were deliberately excluded by the main template logic.

Basic class for views#

Class View#

class cubicweb_web.view.View(req=None, rset=None, **kwargs)[source]#

This class is an abstraction of a view class, used as a base class for every renderable object such as views, templates and other user interface components.

A View is instantiated to render a result set or part of a result set. View subclasses may be parametrized using the following class attributes:

templatable indicates if the view may be embedded in a main

template or if it has to be rendered standalone (i.e. pure XML views must not be embedded in the main template of HTML pages)

content_type if the view is not templatable, it should set the

content_type class attribute to the correct MIME type (text/xhtml being the default)

category this attribute may be used in the interface to regroup

related objects (view kinds) together

paginable

binary

A view writes to its output stream thanks to its attribute w (the append method of an UStreamIO, except for binary views).

At instantiation time, the standard _cw, and cw_rset attributes are added and the w attribute will be set at rendering time to a write function to use.

The basic interface for views is as follows (remember that the result set has a tabular structure with rows and columns, hence cells):

  • render(**context), render the view by calling call or cell_call depending on the context

  • call(**kwargs), call the view for a complete result set or null (the default implementation calls cell_call() on each cell of the result set)

  • cell_call(row, col, **kwargs), call the view for a given cell of a result set (row and col being integers used to access the cell)

  • url(), returns the URL enabling us to get the view with the current result set

  • wview(__vid, rset, __fallback_vid=None, **kwargs), call the view of identifier __vid on the given result set. It is possible to give a fallback view identifier that will be used if the requested view is not applicable to the result set.

  • html_headers(), returns a list of HTML headers to be set by the main template

  • page_title(), returns the title to use in the HTML header title

Other basic view classes#

Here are some of the subclasses of View defined in cubicweb_web.view that are more concrete as they relate to data rendering within the application:

class cubicweb_web.view.EntityView(req=None, rset=None, **kwargs)[source]#

base class for views applying on an entity (i.e. uniform result set)

class cubicweb_web.view.StartupView(req=None, rset=None, **kwargs)[source]#

base class for views which doesn’t need a particular result set to be displayed (so they can always be displayed!)

class cubicweb_web.view.EntityStartupView(req, rset=None, **kwargs)[source]#

base class for entity views which may also be applied to None result set (usually a default rql is provided by the view class)

class cubicweb_web.view.AnyRsetView(req=None, rset=None, **kwargs)[source]#

base class for views applying on any non empty result sets

Examples of views class#

  • Using templatable, content_type and HTTP cache configuration

class RSSView(XMLView):
    __regid__ = 'rss'
    title = _('rss')
    templatable = False
    content_type = 'text/xml'
    http_cache_manager = MaxAgeHTTPCacheManager
    cache_max_age = 60*60*2 # stay in http cache for 2 hours by default
  • Using a custom selector

class SearchForAssociationView(EntityView):
    """view called by the edition view when the user asks
    to search for something to link to the edited eid
    """
    __regid__ = 'search-associate'
    title = _('search for association')
    __select__ = one_line_rset() & match_search_state('linksearch') & is_instance('Any')

XML views, binaries views…#

For views generating other formats than HTML (an image generated dynamically for example), and which can not simply be included in the HTML page generated by the main template (see above), you have to:

  • set the attribute templatable of the class to False

  • set, through the attribute content_type of the class, the MIME type generated by the view to application/octet-stream or any relevant and more specialised mime type

For views dedicated to binary content creation (like dynamically generated images), we have to set the attribute binary of the class to True (which implies that templatable == False, so that the attribute w of the view could be replaced by a binary flow instead of unicode).