# HG changeset patch # User Emile Anclin # Date 1239033337 -7200 # Node ID 9716a9f7798042da4aa555adb1ef1deb42067e3d # Parent af40e615dc8981d1d10461494a9e8a0c1ffb7834 [doc] some improvements on Views diff -r af40e615dc89 -r 9716a9f77980 doc/book/en/A02a-create-cube.en.txt --- a/doc/book/en/A02a-create-cube.en.txt Mon Apr 06 16:18:46 2009 +0200 +++ b/doc/book/en/A02a-create-cube.en.txt Mon Apr 06 17:55:37 2009 +0200 @@ -204,8 +204,7 @@ It is possible to define multiple views for the same identifier and to associate selectors and filters to allow the application -to find the best way to render the data. We will see more details -on this in :ref:`ViewDefinition`. +to find the best way to render the data. For example, the view named ``primary`` is the one used to display a single entity. We will now show you how to customize this view. @@ -266,8 +265,9 @@ Since views are applied to result sets and result sets can be tables of data, we have to recover the entity from its (row,col)-coordinates. -We will get to this in more detail later. +The view has a ``self.w()`` method that is used to output data, in our +example HTML output. -The view has a ``self.w()`` method that is used to output data. In our -example we use it to output HTML tags and values of the entity's attributes. +You can find more details about views and selectors in :ref:`ViewDefinition`. + diff -r af40e615dc89 -r 9716a9f77980 doc/book/en/B1020-define-views.en.txt --- a/doc/book/en/B1020-define-views.en.txt Mon Apr 06 16:18:46 2009 +0200 +++ b/doc/book/en/B1020-define-views.en.txt Mon Apr 06 17:55:37 2009 +0200 @@ -61,13 +61,11 @@ * `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 -````````````````````````` +Other basic view 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: +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 @@ -83,14 +81,14 @@ 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 +- 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 so that it can identify and select the -best view to apply in context. The selectors library is in +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``. @@ -107,8 +105,8 @@ 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 +The purpose of a `registerer` is to control object registry +at the application startup whereas `selectors` control objects when they are selected for display. @@ -179,15 +177,15 @@ 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. +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 has a ``self.w()`` method that is used to output data. Here `lines +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 same blog entry as before, you will notice that the -page is now looking much nicer. +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 @@ -206,22 +204,22 @@ 10. self.wview('primary', rset) In the above source code, `lines 01-08` are similar to the previous -view we defined. +view we defined. [FIXME: defined where ?] -At `line 09`, a simple request in made to build a resultset with all +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 resultset. At -`line 10` the view 'primary' is applied to this resultset to output +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 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.** +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. @@ -232,7 +230,7 @@ **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 +view to the result set returned by the query. That is where most of the flexibility comes from.** [WRITE ME] @@ -242,7 +240,7 @@ 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" +to result sets like "Any E WHERE E is BlogEntry" * create view "blogentry table" with title, publish_date, category @@ -262,7 +260,7 @@ Templates --------- -*Templates* are specific view that does not depend on a result set. The basic +*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 @@ -280,16 +278,16 @@ 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 +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 atribute `templatable` of the class to `False` +* 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 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 +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). diff -r af40e615dc89 -r 9716a9f77980 doc/book/en/B1021-views-selectors.en.txt --- a/doc/book/en/B1021-views-selectors.en.txt Mon Apr 06 16:18:46 2009 +0200 +++ b/doc/book/en/B1021-views-selectors.en.txt Mon Apr 06 17:55:37 2009 +0200 @@ -5,7 +5,7 @@ Selectors are scoring functions that are called by the view dispatcher to tell whenever a view can be applied to a given result -set and request. Selector sets are the glue that tie views to the data +set of a request. Selector sets are the glue that tie views to the data model. Using them appropriately is an essential part of the construction of well behaved cubes.