1 

     2 .. _Views:

     3 

     4 Principles

     5 ----------

     6 

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

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

     9 view selection principle.

    10 

    11 A `View` is an object responsible for the rendering of data from the

    12 model into an end-user consummable form. They typically churn out an

    13 XHTML stream, but there are views concerned with email other non-html

    14 outputs.

    15 

    16 .. _views_base_class:

    17 

    18 Discovering possible views

    19 ~~~~~~~~~~~~~~~~~~~~~~~~~~

    20 

    21 It is possible to configure the web user interface to have a left box

    22 showing all the views than can be applied to the current result set.

    23 

    24 To enable this, click on your login at the top right corner. Chose

    25 "user preferences", then "boxes", then "possible views box" and check

    26 "visible = yes" before validating your changes.

    27 

    28 The views listed there we either not selected because of a lower

    29 score, or they were deliberately excluded by the main template logic.

    30 

    31 

    32 Basic class for views

    33 ~~~~~~~~~~~~~~~~~~~~~

    34 

    35 Class :class:`~cubicweb.view.View`

    36 ``````````````````````````````````

    37 

    38 .. autoclass:: cubicweb.view.View

    39 

    40 The basic interface for views is as follows (remember that the result

    41 set has a tabular structure with rows and columns, hence cells):

    42 

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

    44   `cell_call` depending on the context

    45 

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

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

    48   result set)

    49 

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

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

    52 

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

    54   result set

    55 

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

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

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

    59   not applicable to the result set.

    60 

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

    62   main template

    63 

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

    65 

    66 Other basic view classes

    67 ````````````````````````

    68 Here are some of the subclasses of :class:`~cubicweb.view.View` defined in :mod:`cubicweb.view`

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

    70 

    71 .. autoclass:: cubicweb.view.EntityView

    72 .. autoclass:: cubicweb.view.StartupView

    73 .. autoclass:: cubicweb.view.EntityStartupView

    74 .. autoclass:: cubicweb.view.AnyRsetView

    75 

    76 Examples of views class

    77 ```````````````````````

    78 

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

    80 

    81 .. sourcecode:: python

    82 

    83     class RSSView(XMLView):

    84         __regid__ = 'rss'

    85         title = _('rss')

    86         templatable = False

    87         content_type = 'text/xml'

    88         http_cache_manager = MaxAgeHTTPCacheManager

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

    90 

    91 

    92 - Using a custom selector

    93 

    94 .. sourcecode:: python

    95 

    96     class SearchForAssociationView(EntityView):

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

    98         to search for something to link to the edited eid

    99         """

   100         __regid__ = 'search-associate'

   101         title = _('search for association')

   102         __select__ = one_line_rset() & match_search_state('linksearch') & is_instance('Any')

   103 

   104 

   105 XML views, binaries views...

   106 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   107 

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

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

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

   111 

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

   113 * set, through the attribute `content_type` of the class, the MIME

   114   type generated by the view to `application/octet-stream` or any

   115   relevant and more specialised mime type

   116 

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

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

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

   120 replaced by a binary flow instead of unicode).