Warning
Starting from CubicWeb version 4.0 all code related to generating html views has been moved to the Cube cubicweb_web.
If you want to migrate a project from 3.38 to 4.* while still using all the
html views you need to both install the cubicweb_web cube AND add it to
your dependencies and run add_cube('web')
.
cubicweb_web can be installed from pypi this way:
pip install cubicweb_web
We don’t plan to maintain the features in cubicweb_web in the long run; we are moving to a full javascript frontend using both cubicweb_api (which exposes a HTTP API) and @cubicweb/client as a frontend javascript toolkit.
In the long run cubicweb_api will be merged inside of CubicWeb.
Base views#
CubicWeb provides a lot of standard views, that can be found in
cubicweb_web.views
sub-modules.
A certain number of views are used to build the web interface, which apply to one
or more entities. As other appobjects, their identifier is what distinguish them
from each others. The most generic ones, found in
cubicweb_web.views.baseviews
, are described below.
You’ll probably want to customize one or more of the described views which are default, generic, implementations.
HTML views#
Special views#
- class cubicweb_web.views.baseviews.NullView(req=None, rset=None, **kwargs)[source]#
- __regid__
null
This view is the default view used when nothing needs to be rendered. It is always applicable and is usually used as fallback view when calling
_cw.view()
to display nothing if the result set is empty.
- class cubicweb_web.views.baseviews.NoResultView(req=None, rset=None, **kwargs)[source]#
- __regid__
noresult
This view is the default view to be used when no result has been found (i.e. empty result set).
It’s usually used as fallback view when calling
_cw.view()
to display “no results” if the result set is empty.
- class cubicweb_web.views.baseviews.FinalView(req=None, rset=None, **kwargs)[source]#
- __regid__
final
Display the value of a result set cell with minimal transformations (i.e. you’ll get a number for entities). It is applicable on any result set, though usually dedicated for cells containing an attribute’s value.
Base entity views#
- class cubicweb_web.views.baseviews.InContextView(req=None, rset=None, **kwargs)[source]#
- __regid__
incontext
This view is used when the entity should be considered as displayed in its context. By default it produces the result of
entity.dc_title()
wrapped in a link leading to the primary view of the entity.
- class cubicweb_web.views.baseviews.OutOfContextView(req=None, rset=None, **kwargs)[source]#
- __regid__
outofcontext
This view is used when the entity should be considered as displayed out of its context. By default it produces the result of
entity.dc_long_title()
wrapped in a link leading to the primary view of the entity.
- class cubicweb_web.views.baseviews.OneLineView(req=None, rset=None, **kwargs)[source]#
- __regid__
oneline
This view is used when we can’t tell if the entity should be considered as displayed in or out of context. By default it produces the result of the text view in a link leading to the primary view of the entity.
Those are used to display a link to an entity, whose label depends on the entity having to be displayed in or out of context (of another entity): some entities make sense in the context of another entity. For instance, the Version of a Project in forge. So one may expect that ‘incontext’ will be called when display a version from within the context of a project, while ‘outofcontext”’ will be called in other cases. In our example, the ‘incontext’ view of the version would be something like ‘0.1.2’, while the ‘outofcontext’ view would include the project name, e.g. ‘baz 0.1.2’ (since only a version number without the associated project doesn’t make sense if you don’t know yet that you’re talking about the famous ‘baz’ project. CubicWeb tries to make guess and call ‘incontext’/’outofcontext’ nicely. When it can’t know, the ‘oneline’ view should be used.
List entity views#
- class cubicweb_web.views.baseviews.ListView(req=None, rset=None, **kwargs)[source]#
- __regid__
list
This view displays a list of entities by creating a HTML list (<ul>) and call the view listitem for each entity of the result set. The ‘list’ view will generate HTML like:
<ul class="section"> <li>"result of 'subvid' view for a row</li> ... </ul>
If you wish to use a different view for each entity, either subclass and change the
item_vid
class attribute or specify a subvid argument when calling this view.
- class cubicweb_web.views.baseviews.SimpleListView(req=None, rset=None, **kwargs)[source]#
- __regid__
simplelist
Similar to :class:~cubicweb_web.views.baseviews.ListView but using ‘<div>’ instead of ‘<ul>’. It rely on ‘<div>’ behaviour to separate items. HTML will look like
<div class="section">"result of 'subvid' view for a row</div> ...
It relies on base
View
class implementation of thecall()
method to insert those <div>.
- class cubicweb_web.views.baseviews.SameETypeListView(req=None, rset=None, **kwargs)[source]#
- __regid__
sameetypelist
This view displays a list of entities of the same type, in HTML section (‘<div>’) and call the view sameetypelistitem for each entity of the result set. It’s designed to get a more adapted global list when displayed entities are all of the same type (for instance, display gallery if there are only images entities).
- class cubicweb_web.views.baseviews.CSVView(req=None, rset=None, **kwargs)[source]#
- __regid__
csv
This view displays each entity in a coma separated list. It is NOT related to the well-known text file format.
Those list views can be given a ‘subvid’ arguments, telling the view to use of
each item in the list. When not specified, the value of the ‘redirect_vid’
attribute of ListItemView
(for ‘listview’) or of
SimpleListView
will be used. This default to ‘outofcontext’ for ‘list’
/ ‘incontext’ for ‘simplelist’
Text entity views#
Basic HTML view have some variants to be used when generating raw text, not HTML (for notifications for instance). Also, as explained above, some of the HTML views use those text views as a basis.
- class cubicweb_web.views.baseviews.TextView(req=None, rset=None, **kwargs)[source]#
- __regid__
text
This is the simplest text view for an entity. By default it returns the result of the entity’s dc_title() method, which is cut to fit the navigation.short-line-size property if necessary.
- class cubicweb_web.views.baseviews.InContextTextView(req=None, rset=None, **kwargs)[source]#
- __regid__
textincontext
Similar to the text view, but called when an entity is considered in context (see description of incontext HTML view for more information on this). By default it displays what’s returned by the dc_title() method of the entity.
- class cubicweb_web.views.baseviews.OutOfContextView(req=None, rset=None, **kwargs)[source]#
- __regid__
outofcontext
This view is used when the entity should be considered as displayed out of its context. By default it produces the result of
entity.dc_long_title()
wrapped in a link leading to the primary view of the entity.
You will also find modules providing some specific services:
This module provides some generic components to navigate in the web application.
Pagination#
Several implementations for large result set pagination are provided:
The default pagination component: display link to pages where each pages is identified by the item number of its first and last elements.
This pagination component displays a result-set by page as
PageNavigation
but in a <select>, which is better when there are a lot of results.By default it will be selected when there are more than 4 pages to be displayed.
This pagination component will be selected by default if there are less than 4 pages and if the result set is sorted.
Displayed links to navigate accross pages of a result set are done according to the first variable on which the sort is done, and looks like:
[ana - cro] | [cro - ghe] | … | [tim - zou]
You may want to override this component to customize display in some cases.
Return entity column number / attr name to use for nice display by inspecting the rset’syntax tree.
Return a function that will be called with a row number as argument and should return a string to use as link for it.
Return text for a page link, where startstr and stopstr are the text for the lower/upper boundaries of the page.
By default text are stripped down to
nb_chars
characters.
Return HTML for the whole navigation: blocklist is a list of HTML snippets for each page, basepath and params will be necessary to build previous/next links.
Below an example from the tracker cube:
class TicketsNavigation(navigation.SortedNavigation): __select__ = (navigation.SortedNavigation.__select__ & ~paginated_rset(4) & is_instance('Ticket')) def sort_on(self): col, attrname = super(TicketsNavigation, self).sort_on() if col == 6: # sort on state, we don't want that return None, None return col, attrname
The idea is that in trackers’ticket tables, result set is first ordered on ticket’s state while this doesn’t make any sense in the navigation. So we override
sort_on()
so that if we detect such sorting, we disable the feature to go back to item number in the pagination.Also notice the ~paginated_rset(4) in the selector so that if there are more than 4 pages to display,
PageNavigationSelect
will still be selected.
Pagination will appear when needed according to the page-size ui property.
This module monkey-patch the paginate()
function to the base View
class, so that you can ask pagination explicitly on every result-set based views.
paginate results if the view is paginable