1 

     2 .. _Views:

     3 

     4 Views

     5 -----

     6 

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

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

     9 in *CubicWeb*.

    10 

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

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

    13 selection principle which makes *CubicWeb* web interface very flexible.

    14 

    15 A `View` is an object applied to another object such as an entity.

    16 

    17 Basic class for views

    18 ~~~~~~~~~~~~~~~~~~~~~

    19 

    20 Class `View` (`cubicweb.view`)

    21 `````````````````````````````````````

    22 

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

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

    25 

    26 A `View` is instantiated to render a result set or part of a result set. `View`

    27 subclasses may be parametrized using the following class attributes:

    28 

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

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

    31   not be embedded in the main template for HTML pages)

    32 

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

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

    35 

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

    37   related objects together

    38 

    39 A view writes to its output stream thanks to its attribute `w` (an

    40 `UStreamIO`, except for binary views).

    41 

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

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

    44 

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

    46 tabular structure with rows and columns, hence cells):

    47 

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

    49   `cell_call` depending on the given parameters

    50 

    51 * `call(**kwargs)`, call the view for a complete result set or null

    52   (the default implementation calls `cell_call()` on each cell of the

    53   result set)

    54 

    55 * `cell_call(row, col, **kwargs)`, call the view for a given cell of a

    56   result set (`row` and `col` being integers used to access the cell)

    57 

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

    59   result set

    60 

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

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

    63   fallback view identifier that will be used if the requested view is

    64   not applicable to the result set.

    65 

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

    67   main template

    68 

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

    70 

    71 Other basic view classes

    72 ````````````````````````

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

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

    75 

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

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

    78 * `AnyRsetView`, view applicable to any result set

    79 

    80 Examples of views class

    81 -----------------------

    82 

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

    84 

    85 .. sourcecode:: python

    86 

    87     class RSSView(XMLView):

    88         __regid__ = 'rss'

    89         title = _('rss')

    90         templatable = False

    91         content_type = 'text/xml'

    92         http_cache_manager = MaxAgeHTTPCacheManager

    93         cache_max_age = 60*60*2 # stay in http cache for 2 hours by default

    94 

    95 

    96 - Using custom selector

    97 

    98 .. sourcecode:: python

    99 

   100     class SearchForAssociationView(EntityView):

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

   102         to search for something to link to the edited eid

   103         """

   104         __regid__ = 'search-associate'

   105         title = _('search for association')

   106         __select__ = one_line_rset() & match_search_state('linksearch') & implements('Any')

   107 

   108 

   109 

   110 Example of view customization and creation

   111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   112 

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

   114 

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

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

   117 

   118 .. sourcecode:: python

   119 

   120   from cubicweb.selectors import implements

   121   from cubicweb.web.views.primary improt Primaryview

   122 

   123   class BlogEntryPrimaryView(PrimaryView):

   124     __select__ = PrimaryView.__select__ & implements('BlogEntry')

   125 

   126       def render_entity_attributes(self, entity):

   127           self.w(u'<p>published on %s</p>' %

   128                  entity.publish_date.strftime('%Y-%m-%d'))

   129           super(BlogEntryPrimaryView, self).render_entity_attributes(entity)

   130 

   131 The above source code defines a new primary view for

   132 ``BlogEntry``. The `id` class attribute is not repeated there since it

   133 is inherited through the `primary.PrimaryView` class.

   134 

   135 The selector for this view chains the selector of the inherited class

   136 with its own specific criterion.

   137 

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

   139 08-09` output HTML for the publication date of the entry.

   140 

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

   142    :alt: blog entries now look much nicer

   143 

   144 Let us now improve the primary view of a blog

   145 

   146 .. sourcecode:: python

   147 

   148  from logilab.mtconverter import xml_escape

   149  from cubicweb.selectors import implements, one_line_rset

   150  from cubicweb.web.views.primary import Primaryview

   151 

   152  class BlogPrimaryView(PrimaryView):

   153      __regid__ = 'primary'

   154      __select__ = PrimaryView.__select__ & implements('Blog')

   155      rql = 'Any BE ORDERBY D DESC WHERE BE entry_of B, BE publish_date D, B eid %(b)s'

   156 

   157      def render_entity_relations(self, entity):

   158          rset = self._cw.execute(self.rql, {'b' : entity.eid})

   159          for entry in rset.entities():

   160              self.w(u'<p>%s</p>' % entry.view('inblogcontext'))

   161 

   162  class BlogEntryInBlogView(EntityView):

   163      __regid__ = 'inblogcontext'

   164      __select__ = implements('BlogEntry')

   165 

   166      def cell_call(self, row, col):

   167          entity = self.cw_rset.get_entity(row, col)

   168          self.w(u'<a href="%s" title="%s">%s</a>' %

   169                 entity.absolute_url(),

   170                 xml_escape(entity.content[:50]),

   171                 xml_escape(entity.description))

   172 

   173 This happens in two places. First we override the

   174 render_entity_relations method of a Blog's primary view. Here we want

   175 to display our blog entries in a custom way.

   176 

   177 At `line 10`, a simple request is made to build a result set with all

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

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

   180 about the schema and infers that such entities have to be of the

   181 ``BlogEntry`` kind and retrieves them (in the prescribed publish_date

   182 order).

   183 

   184 The request returns a selection of data called a result set. Result

   185 set objects have an .entities() method returning a generator on

   186 requested entities (going transparently through the `ORM` layer).

   187 

   188 At `line 13` the view 'inblogcontext' is applied to each blog entry to

   189 output HTML. (Note that the 'inblogcontext' view is not defined

   190 whatsoever in *CubicWeb*. You are absolutely free to define whole view

   191 families.) We juste arrange to wrap each blogentry output in a 'p'

   192 html element.

   193 

   194 Next, we define the 'inblogcontext' view. This is NOT a primary view,

   195 with its well-defined sections (title, metadata, attribtues,

   196 relations/boxes). All a basic view has to define is cell_call.

   197 

   198 Since views are applied to result sets which can be tables of data, we

   199 have to recover the entity from its (row,col)-coordinates (`line

   200 20`). Then we can spit some HTML.

   201 

   202 But careful: all strings manipulated in *CubicWeb* are actually

   203 unicode strings. While web browsers are usually tolerant to incoherent

   204 encodings they are being served, we should not abuse it. Hence we have

   205 to properly escape our data. The xml_escape() function has to be used

   206 to safely fill (X)HTML elements from Python unicode strings.

   207 

   208 

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

   210 languages. Applying a given view called 'a_view' to all the entities

   211 of a result set only requires to have for each entity of this result set,

   212 an available view called 'a_view' which accepts the entity.**

   213 

   214 **Instead of merely using type based dispatch, we do predicate dispatch

   215 which is quite more powerful.**

   216 

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

   218 now allows to read its description and all its entries.

   219 

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

   221    :alt: a blog and all its entries

   222 

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

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

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

   226 view to the result set returned by the query. That is where most of the

   227 flexibility comes from.**

   228 

   229 [WRITE ME]

   230 

   231 * implementing interfaces, calendar for blog entries

   232 * show that a calendar view can export data to ical

   233 

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

   235 entities.BlogEntry and apply the OneMonthCalendar and iCalendar views

   236 to result sets like "Any E WHERE E is BlogEntry"

   237 

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

   239 

   240 We will show that by default the view that displays

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

   242 Of course, the same can be obtained by calling

   243 self.wview('table',rset)

   244 

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

   246 * demo ajax by filtering blogentry table on category

   247 

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

   249 and show that ajax comes for free.

   250 [FILLME]

   251 

   252 

   253 XML views, binaries views...

   254 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   255 

   256 For views generating other formats than HTML (an image generated dynamically

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

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

   259 

   260 * set the attribute `templatable` of the class to `False`

   261 * set, through the attribute `content_type` of the class, the MIME type generated

   262   by the view to `application/octet-stream`

   263 

   264 For views dedicated to binary content creation (like dynamically generated

   265 images), we have to set the attribute `binary` of the class to `True` (which

   266 implies that `templatable == False`, so that the attribute `w` of the view could be

   267 replaced by a binary flow instead of unicode).