# HG changeset patch # User Sandrine Ribeau # Date 1230601620 28800 # Node ID 73a3525265774d4fcda0d8cdf588ef27c833c5b1 # Parent 6231a61dabfa52ab45d24674be8e0450101cf3f9 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter. diff -r 6231a61dabfa -r 73a352526577 doc/book/en/B1010-request.en.txt --- a/doc/book/en/B1010-request.en.txt Mon Dec 29 15:37:12 2008 -0800 +++ b/doc/book/en/B1010-request.en.txt Mon Dec 29 17:47:00 2008 -0800 @@ -1,6 +1,6 @@ .. -*- coding: utf-8 -*- -request +Request ======= [WRITE ME] diff -r 6231a61dabfa -r 73a352526577 doc/book/en/B1020-define-views.en.txt --- a/doc/book/en/B1020-define-views.en.txt Mon Dec 29 15:37:12 2008 -0800 +++ b/doc/book/en/B1020-define-views.en.txt Mon Dec 29 17:47:00 2008 -0800 @@ -5,19 +5,47 @@ 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 a basic +understanding of the classes and methods available. We'll also +take time to develop the view selection principle we implemented +which is very unique to `CubicWeb` and makes it powerfull. + Basic class for views --------------------- Class `View` (`cubicweb.common.view`) ````````````````````````````````````` +This class is an abstraction of a view class, used as a base for every +renderable object such as views, templates, graphic components... web. + +A `View` is instantiated to render a 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 for + instance) + * 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 to a write function to use. + A view writes in its output exit thanks to its attribute `w` (`UStreamIO`). The basic interface for views is as follows: * `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 +* `call(**kwargs)`, call the view for a complete result set or null and call + the method `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 @@ -36,12 +64,15 @@ * `creator(eid)`, returns the eid and the login of the entity creator of the entity having the eid given in the parameter -Other basic classes: +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 ---------------------------- @@ -49,9 +80,11 @@ A view includes : - an identifier (all objects in `CubicWeb` are entered in a registry - and this identifier will be used as a key) + 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 +- a filter to select the resulsets it can be applied to. This is defined in + the class attribute ``__selectors__`` For a given identifier, multiple views can be defined. `CubicWeb` uses @@ -61,26 +94,19 @@ compute scores is in ``cubicweb.vregistry.vreq``. -`CubicWeb` provides a lot of standard views, for a complete list, you -will have to read the code in directory ``cubicweb/web/views/`` (XXX -improve doc). - `CubicWeb` provides a lot of standard views for the default class `EntityType`. You can find them in ``cubicweb/web/views/``. -The basic views defined are : - -*null* - - +.. include:: B1021-views-stdlib.en.txt +Example of a view customization +------------------------------- -For example, the view named ``primary`` is the one used to display -a single entity. +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 view ``primary`` in ``BlogDemo/views.py`` :: +override the method ``cell_call()`` of the view ``primary`` in ``BlogDemo/views.py`` :: 01. from ginco.web.views import baseviews 02. @@ -159,8 +185,8 @@ * implementing interfaces, calendar for blog entries * show that a calendar view can export data to ical -We will implement the cubicwweb.interfaces.ICalendarable interfaces on -entities.BloEntry and apply the OneMonthCalendar and iCalendar views +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 @@ -185,7 +211,7 @@ 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 (it is not used in case an error is raised or for +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. @@ -195,34 +221,7 @@ 2. identifying the view to use to render data if it is not specified 3. composing the HTML page to return - -The default main template (`cubicweb.web.views.basetemplates.TheMainTemplate`) ------------------------------------------------------------------------------- - -The default main template build the page based on the following pattern: - -.. image:: images/main_template_layout.png - -The rectangle containing `view.dispathc()` represents the area where the content -view has to be displayed. The others represents sub-templates called to complete -the page. A default implementation of those is provided in -`cubicweb.views.basetemplates`. You can, of course, overload those sub-templates -to implement your own customization of the HTML page. - -We can also control certain aspects of the main template thanks to the following -forms parameters: - -* `__notemplate`, if present (whatever the value assigned), only the content view - is returned -* `__force_display`, if present and its value is not null, no navigation - whatever the number of entities to display -* `__method`, if the result set to render contains only one entity and this - parameter is set, it refers to a method to call on the entity by passing it - the dictionnary of the forms parameters, before going the classic way (through - step 1 and 2 described juste above) - -.. include:: B1021-views-stdlib.en.txt - +You will find out more about templates in :ref:`templates`. XML views, binaries... ---------------------- @@ -236,7 +235,7 @@ 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 `templateable == False`, so that the attribute `w` of the view could be +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 diff -r 6231a61dabfa -r 73a352526577 doc/book/en/B1021-views-stdlib.en.txt --- a/doc/book/en/B1021-views-stdlib.en.txt Mon Dec 29 15:37:12 2008 -0800 +++ b/doc/book/en/B1021-views-stdlib.en.txt Mon Dec 29 17:47:00 2008 -0800 @@ -7,59 +7,83 @@ to one or more entities. Their identifier is what distinguish them from each others and the main ones are: -:primary: - primary view of an entity, this is the view called by default when a single - entity is in the result set and needs to be displayed. This view is supposed - to render a maximum of informations about the entity. -:secondary: - secondary view of an entity. By default it renders the two first attributes - of the entity as a clickable link redirecting to the primary view. -:oneline: - similar to the `secondary` view, but called when we want the view to stand - on a single line, or just get a brief view. By default this view uses the +*primary* + Primary view of an entity, this is the view called by default when a single + non final entity is in the result set and needs to be displayed. + This view is supposed to render a maximum of informations about the entity. + +*text* + This is the simplest text view for an entity. It displays the + title of an entity. It should not contain HTML. + +*oneline* + This is a hyper linked *text* view. Similar to the `secondary` view, + but called when we want the view to stand on a single line, or just + get a brief view. By default this view uses the parameter `MAX_LINE_CHAR` to control the result size. -:text: - similar to the `oneline` view, but should not contain HTML. -:incontext, outofcontext: - similar to the `secondary` view, but called when an entity is considered + +*secondary* + This is a combinaison of an icon and a *oneline* view. + By default it renders the two first attributes of the entity as a + clickable link redirecting to the primary view. + +*incontext, outofcontext* + Similar to the `secondary` view, but called when an entity is considered as in or out of context. By default it respectively returns the result of `textincontext` and `textoutofcontext` wrapped in a link leading to the primary view of the entity. -:textincontext, textoutofcontext: - similar to the `text` view, but called is an entity is considered out or + +*textincontext, textoutofcontext* + Similar to the `text` view, but called when an entity is considered out or in context. By default it returns respectively the result of the methods `.dc_title` and `.dc_long_title` of the entity. -:list: - creates a HTML list (`