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

Views definition

================

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

We'll start with a description of the interface providing you with a basic

understanding of the classes and methods available, then detail the view

selection principle which makes `CubicWeb` web interface very flexible.

Basic class for views

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

Class `View` (`cubicweb.common.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.

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 embeded in a main

      template or if it has to be rendered standalone (i.e. XML views

      must not be embeded in the main template for HTML pages)

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

      attribute to the correct MIME type (text/xhtml by default)

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

      objects together

At instantiation time, the standard `req`, `rset`, and `cursor`

attributes are added and the `w` attribute will be set at rendering

time.

A view writes to its output stream thanks to its attribute `w` (`UStreamIO`).

The basic interface for views is as follows (remember that the result set has a

tabular structure with rows and columns, hence cells):

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

  `cell_call` depending on the given parameters

* `call(**kwargs)`, call the view for a complete result set or null (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

* `url()`, returns the URL enabling us to get the view with the current

  result set 

* `view(__vid, rset, __fallback_vid=None, **kwargs)`, call the view of identifier 

  `__vid` on the given result set. It is possible to give a view identifier

  of fallback that will be used if the view requested is not applicable to the

  result set

* `wview(__vid, rset, __fallback_vid=None, **kwargs)`, similar to `view` except

  the flow is automatically passed in the parameters

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

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

* `creator(eid)`, returns the eid and the login of the entity creator of the entity

  having the eid given in the parameter 

Other basic views classes

`````````````````````````

Here are some of the subclasses of `View` defined in `cubicweb.common.view`

that are more concrete as they relates 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 applied to any result set 

* `EmptyRsetView`, view applied to an empty result set

The selection view principle

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

A view is essentially defined by:

- an identifier (all objects in `CubicWeb` are entered in a registry

  and this identifier will be used as a key). This is defined in the class

  attribute ``id``.

- a filter to select the resulsets it can be applied to. This is defined in

  the class attribute ``__selectors__``, which expects a tuple of selectors

  as its value.

For a given identifier, multiple views can be defined. `CubicWeb` uses

a selector which computes scores so that it can identify and select the

best view to apply in context. The selectors library is in 

``cubicweb.common.selector`` and a library of the methods used to

compute scores is in ``cubicweb.vregistry.vreq``.

.. include:: B1021-views-selectors.en.txt

Registerer

``````````

A view is also customizable through its attribute ``__registerer__``.

This is used at the time the application is launched to manage how

objects (views, graphic components, actions, etc.) 

are registered in the `cubicWeb` registry.

A `registerer` can, for example, identify when we register an 

object that is equivalent to an already registered object, which

could happen when we define two `primary` views for an entity type.

The purpose of a `registerer` is to control objects registry

at the application startup whereas `selectors` controls objects

when they are selected for display.

`CubicWeb` provides a lot of standard views for the default class

`EntityType`. You can find them in ``cubicweb/web/views/``.

.. include:: B1022-views-stdlib.en.txt

Examples of views class 

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

- Using the attribute `templatable`

  ::

    class RssView(XmlView):

        id = '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 the attribute `__selectors__`

  ::

    class SearchForAssociationView(EntityView):

        """view called by the edition view when the user asks

        to search for something to link to the edited eid

        """

        id = 'search-associate'

        title = _('search for association')

        __selectors__ = (one_line_rset, match_search_state, accept_selector)

        accepts = ('Any',)

        search_states = ('linksearch',)

Example of a view customization

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

We'll show you now an example of a ``primary`` view and how to customize it.

If you want to change the way a ``BlogEntry`` is displayed, just override 

the method ``cell_call()`` of the view ``primary`` in ``BlogDemo/views.py`` ::

  01. from cubicweb.web.views import baseviews

  02.

  03. class BlogEntryPrimaryView(baseviews.PrimaryView):

  04.

  05.     accepts = ('BlogEntry',)

  06.

  07.     def cell_call(self, row, col):

  08.         entity = self.entity(row, col)

  09.         self.w(u'<h1>%s</h1>' % entity.title)

  10.         self.w(u'<p>published on %s in category %s</p>' % \

  11.                (entity.publish_date.strftime('%Y-%m-%d'), entity.category))

  12.         self.w(u'<p>%s</p>' % entity.text)

The above source code defines a new primary view (`line 03`) for

``BlogEntry`` (`line 05`). 

Since views are applied to resultsets and resulsets can be tables of

data, it is needed to recover the entity from its (row,col)

coordinates (`line 08`). We will get to this in more detail later.

The view has a ``self.w()`` method that is used to output data. Here `lines

09-12` output HTML tags and values of the entity's attributes.

When displaying same blog entry as before, you will notice that the

page is now looking much nicer.

.. image:: images/lax-book.09-new-view-blogentry.en.png

   :alt: blog entries now look much nicer

Let us now improve the primary view of a blog ::

  01. class BlogPrimaryView(baseviews.PrimaryView):

  02. 

  03.     accepts = ('Blog',)

  04.

  05.     def cell_call(self, row, col):

  06.         entity = self.entity(row, col)

  07.         self.w(u'<h1>%s</h1>' % entity.title)

  08.         self.w(u'<p>%s</p>' % entity.description)

  09.         rset = self.req.execute('Any E WHERE E entry_of B, B eid "%s"' % entity.eid)

  10.         self.wview('primary', rset)

In the above source code, `lines 01-08` are similar to the previous

view we defined.

At `line 09`, a simple request in made to build a resultset with all

the entities linked to the current ``Blog`` entity by the relationship

``entry_of``. The part of the framework handling the request knows

about the schema and infer that such entities have to be of the

``BlogEntry`` kind and retrieves them.

The request returns a selection of data called a resultset. At 

`line 10` the view 'primary' is applied to this resultset to output

HTML. 

**This is to be compared to interfaces and protocols in object-oriented

languages. Applying a given view to all the entities of a resultset only

requires the availability, for each entity of this resultset, of a

view with that name that can accepts the entity.**

Assuming we added entries to the blog titled `MyLife`, displaying it

now allows to read its description and all its entries.

.. image:: images/lax-book.10-blog-with-two-entries.en.png

   :alt: a blog and all its entries

**Before we move forward, remember that the selection/view principle is

at the core of `CubicWeb`. Everywhere in the engine, data is requested

using the RQL language, then HTML/XML/text/PNG is output by applying a

view to the resultset returned by the query. That is where most of the

flexibility comes from.**

[WRITE ME]

* implementing interfaces, calendar for blog entries

* show that a calendar view can export data to ical

We will implement the `cubicweb.interfaces.ICalendarable` interfaces on

entities.BlogEntry and apply the OneMonthCalendar and iCalendar views

to resultsets like "Any E WHERE E is BlogEntry"

* create view "blogentry table" with title, publish_date, category

We will show that by default the view that displays 

"Any E,D,C WHERE E publish_date D, E category C" is the table view.

Of course, the same can be obtained by calling

self.wview('table',rset)

* in view blog, select blogentries and apply view "blogentry table"

* demo ajax by filtering blogentry table on category

we did the same with 'primary', but with tables we can turn on filters

and show that ajax comes for free.

[FILLME]

Templates

---------

*Templates* are specific view that does not depend on a result set. The basic

class `Template` (`cubicweb.common.view`) is derived from the class `View`.

To build a HTML page, a *main template* is used. In general, the template of

identifier `main` is the one to use (it is not used in case an error is raised or for

the login form for example). This template uses other templates in addition

to the views which depends on the content to generate the HTML page to return.

A *template* is responsible for:

1. executing RQL query of data to render if necessary

2. identifying the view to use to render data if it is not specified

3. composing the HTML page to return

You will find out more about templates in :ref:`templates`. 

XML views, binaries...

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

For the views generating other formats that HTML (an image generated dynamically

for example), and which can not usually be included in the HTML page generated

by the main template (see above), you have to:

* set the atribute `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`

For the views dedicated to binary content creation (an image dynamically generated

for example), 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).

(X)HTML tricks to apply

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

Some web browser (Firefox for example) are not happy with empty `<div>`

(by empty we mean that there is no content in the tag, but there

could be attributes), so we should always use `<div></div>` even if

it is empty and not use `<div/>`.