diff -r 49075f57cf2c -r aa09e20dd8c0 doc/book/en/B1020-define-views.en.txt --- a/doc/book/en/B1020-define-views.en.txt Tue May 05 17:18:49 2009 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,414 +0,0 @@ -.. -*- coding: utf-8 -*- - -.. _ViewDefinition: - -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. - -A `View` is an object applied to another object such as an entity. - -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` - - -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 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 result sets 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 to identify and select the -best view to apply in the given 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 -`````````` -[Registerers are deprecated: they will soon disappear for explicite -registration...] - -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 object registry -at the application startup whereas `selectors` control objects -when they are selected for display. - - -.. 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',) - - -Rendering methods and attributes for ``PrimaryView`` ----------------------------------------------------- - -By default, `CubicWeb` provides a primary view for each new entity type -you create. The first view you might be interested in modifying. - -Let's have a quick look at the EntityView ``PrimaryView`` as well as -its rendering method:: - - class PrimaryView(EntityView): - """the full view of an non final entity""" - id = 'primary' - title = _('primary') - show_attr_label = True - show_rel_label = True - skip_none = True - skip_attrs = ('eid', 'creation_date', 'modification_date') - skip_rels = () - main_related_section = True - - ... - - def cell_call(self, row, col): - self.row = row - self.render_entity(self.complete_entity(row, col)) - - def render_entity(self, entity): - """return html to display the given entity""" - siderelations = [] - self.render_entity_title(entity) - self.render_entity_metadata(entity) - # entity's attributes and relations, excluding meta data - # if the entity isn't meta itself - self.w(u'
') - self.w(u'
') - self.render_entity_attributes(entity, siderelations) - self.w(u'
') - self.content_navigation_components('navcontenttop') - if self.main_related_section: - self.render_entity_relations(entity, siderelations) - self.w(u'
') - # side boxes - self.w(u'
') - self.render_side_related(entity, siderelations) - self.w(u'
') - self.w(u'
') - self.content_navigation_components('navcontentbottom') - - ... - -``cell_call`` is executed for each entity of a result set and apply ``render_entity``. - -The methods you want to modify while customizing a ``PrimaryView`` are: - -*render_entity_title(self, entity)* - Renders the entity title based on the assumption that the method - ``def content_title(self)`` is implemented for the given entity type. - -*render_entity_metadata(self, entity)* - Renders the entity metadata based on the assumption that the method - ``def summary(self)`` is implemented for the given entity type. - -*render_entity_attributes(self, entity, siderelations)* - Renders all the attribute of an entity with the exception of attribute - of type `Password` and `Bytes`. - -*content_navigation_components(self, context)* - This method is applicable only for entity type implementing the interface - `IPrevNext`. This interface is for entities which can be linked to a previous - and/or next entity. This methods will render the navigation links between - entities of this type, either at the top or at the bottom of the page - given the context (navcontent{top|bottom}). - -*render_entity_relations(self, entity, siderelations)* - Renders all the relations of the entity in the main section of the page. - -*render_side_related(self, entity, siderelations)* - Renders all the relations of the entity in a side box. This is equivalent - to *render_entity_relations* in addition to render the relations - in a box. - -Also, please note that by setting the following attributes in you class, -you can already customize some of the rendering: - -*show_attr_label* - Renders the attribute label next to the attribute value if set to True. - Otherwise, does only display the attribute value. - -*show_rel_label* - Renders the relation label next to the relation value if set to True. - Otherwise, does only display the relation value. - -*skip_none* - Does not render an attribute value that is None if set to True. - -*skip_attrs* - Given a list of attributes name, does not render the value of the attributes listed. - -*skip_rels* - Given a list of relations name, does not render the relations listed. - -*main_related_section* - Renders the relations of the entity if set to True. - -A good practice is for you to identify the content of your entity type for which -the default rendering does not answer your need so that you can focus on the specific -method (from the list above) that needs to be modified. We do not recommand you to -overwrite ``render_entity`` as you might potentially loose the benefits of the side -boxes handling. - -Example of a view customization -------------------------------- - -[FIXME] XXX Example needs to be rewritten as it shows how to modify cell_call which -contredicts our advise of not modifying it. - -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'

%s

' % entity.title) - 10. self.w(u'

published on %s in category %s

' % \ - 11. (entity.publish_date.strftime('%Y-%m-%d'), entity.category)) - 12. self.w(u'

%s

' % entity.text) - -The above source code defines a new primary view (`line 03`) for -``BlogEntry`` (`line 05`). - -Since views are applied to result sets which can be tables of -data, we have to recover the entity from its (row,col)-coordinates (`line 08`). -We will get to this in more detail later. - -The view method ``self.w()`` is used to output data. Here `lines -09-12` output HTML tags and values of the entity's attributes. - -When displaying the same blog entry as before, you will notice that the -page is now looking much nicer. [FIXME: it is not clear to what this refers.] - -.. 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'

%s

' % entity.title) - 08. self.w(u'

%s

' % 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. [FIXME: defined where ?] - -At `line 09`, a simple request is made to build a result set 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 result set. At -`line 10` the view 'primary' is applied to this result set to output -HTML. - -**This is to be compared to interfaces and protocols in object-oriented -languages. Applying a given view called 'a_view' to all the entities -of a result set only requires to have for each entity of this result set, -an available view called 'a_view' which 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 result set 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 result sets 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 views that do 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 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` - -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). - -(X)HTML tricks to apply ------------------------ - -Some web browser (Firefox for example) are not happy with empty `
` -(by empty we mean that there is no content in the tag, but there -could be attributes), so we should always use `
` even if -it is empty and not use `
`. -