.. _Views:

Views

-----

This chapter aims to describe the concept of a `view` used all along

the development of a web application and how it has been implemented

in *CubicWeb*.

Basic class for views

~~~~~~~~~~~~~~~~~~~~~

Class `View` (`cubicweb.view`)

This class is an abstraction of a view class, used as a base class for every

renderable object such as views, templates, graphic components, etc.

* `templatable` indicates if the view may be embedded in a main

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

* the `category` attribute may be used in the interface to regroup

At instantiation time, the standard `_cw` and `cw_rset` attributes are

added and the `w` attribute will be set at rendering time.

* `render(**context)`, render the view by calling `call` or

* `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.common.view`

that are more concrete as they relate to data rendering within the application:

* `EntityView`, view applying to lines or cell containing an entity (e.g. an eid)

* `StartupView`, start view that does not require a result set to apply to

* `AnyRsetView`, view applicable to any result set

Examples of views class

-----------------------

- Using `templatable`, `content_type` and HTTP cache configuration

.. sourcecode:: python

    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

.. sourcecode:: python

    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') & implements('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`

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