# HG changeset patch # User Aurelien Campeas # Date 1271428825 -7200 # Node ID d2dbba898a96294aebabb92a5871e69f347b5da2 # Parent 34dc384563768005481bb8f584b5ed462ca23105 [doc/book] misc on views, docstrings diff -r 34dc38456376 -r d2dbba898a96 doc/book/en/annexes/rql/implementation.rst --- a/doc/book/en/annexes/rql/implementation.rst Fri Apr 16 14:39:42 2010 +0200 +++ b/doc/book/en/annexes/rql/implementation.rst Fri Apr 16 16:40:25 2010 +0200 @@ -2,6 +2,7 @@ Implementation -------------- + BNF grammar ~~~~~~~~~~~ @@ -126,7 +127,7 @@ ~~~~~~~~~~~~~~~~~ - The current implementation does not support linking two relations of type 'is' - with a OR. I do not think that the negation is supported on this type of + with an OR. I do not think that the negation is supported on this type of relation (XXX FIXME to be confirmed). - Relations defining the variables must be left to those using them. For @@ -140,11 +141,11 @@ is not. -- missing proper explicit type conversion, COALESCE and certainly other things... +- missing proper explicit type conversion, COALESCE and certainly other things... -- writing a rql query require knowledge of the schema used (with real relation - names and entities, not those viewing in the user interface). On the other - hand, we can not really bypass that, and it is the job of a user interface to +- writing an rql query requires knowledge of the used schema (with real relation + names and entities, not those viewed in the user interface). On the other + hand, we cannot really bypass that, and it is the job of a user interface to hide the RQL. diff -r 34dc38456376 -r d2dbba898a96 doc/book/en/annexes/rql/language.rst --- a/doc/book/en/annexes/rql/language.rst Fri Apr 16 14:39:42 2010 +0200 +++ b/doc/book/en/annexes/rql/language.rst Fri Apr 16 16:40:25 2010 +0200 @@ -373,3 +373,15 @@ DELETE X friend Y WHERE X is Person, X name 'foo' +Virtual RQL relations +~~~~~~~~~~~~~~~~~~~~~ + +Those relations may only be used in RQL query and are not actual +attributes of your entities. + +* `has_text`: relation to use to query the full text index (only for + entities having fulltextindexed attributes). + +* `identity`: relation to use to tell that a RQL variable should be + the same as another (but you've to use two different rql variables + for querying purpose) diff -r 34dc38456376 -r d2dbba898a96 doc/book/en/conf.py --- a/doc/book/en/conf.py Fri Apr 16 14:39:42 2010 +0200 +++ b/doc/book/en/conf.py Fri Apr 16 16:40:25 2010 +0200 @@ -45,7 +45,7 @@ # General substitutions. project = 'CubicWeb' -copyright = '2008-2010, Logilab' +copyright = '2001-2010, Logilab' # The default replacements for |version| and |release|, also used in various # other places throughout the built documents. @@ -188,4 +188,9 @@ # If false, no module index is generated. #latex_use_modindex = True + #aafig_format = dict(latex='pdf', html='svg', text=None) + +rst_epilog = """ +.. |cubicweb| replace:: *CubicWeb* +""" diff -r 34dc38456376 -r d2dbba898a96 doc/book/en/development/datamodel/metadata.rst --- a/doc/book/en/development/datamodel/metadata.rst Fri Apr 16 14:39:42 2010 +0200 +++ b/doc/book/en/development/datamodel/metadata.rst Fri Apr 16 16:40:25 2010 +0200 @@ -1,6 +1,6 @@ -Meta-data ---------- +Metadata +-------- .. index:: schema: meta-data; @@ -9,46 +9,29 @@ Each entity type in |cubicweb| has at least the following meta-data attributes and relations: -eid +`eid` entity's identifier which is unique in an instance. We usually call this identifier `eid` for historical reason. -creation_date +`creation_date` Date and time of the creation of the entity. -modification_date +`modification_date` Date and time of the latest modification of an entity. -cwuri +`cwuri` Reference URL of the entity, which is not expected to change. -created_by +`created_by` Relation to the :ref:`users ` who has created the entity -owned_by +`owned_by` Relation to :ref:`users ` whom the entity belongs; usually the creator but not necessary, and it could have multiple owners notably for permission control -is +`is` Relation to the :ref:`entity type ` of which type the entity is. -is_instance +`is_instance` Relation to the :ref:`entity types ` of which type the entity is an instance of. - -Virtual RQL relations ---------------------- -XXX move this to the RQL chapter. - -Those relations may only be used in RQL query and are not actual attributes of your entities... - -has_text - Relation to use to query the full text index (only for entities having fulltextindexed attributes). - -identity - Relation to use to tell that a RQL variable should be the same as entity another - (but you've to use two different rql variables for querying purpose) - - - -.. |cubicweb| replace:: *CubicWeb* \ No newline at end of file diff -r 34dc38456376 -r d2dbba898a96 doc/book/en/development/devcore/dbapi.rst --- a/doc/book/en/development/devcore/dbapi.rst Fri Apr 16 14:39:42 2010 +0200 +++ b/doc/book/en/development/devcore/dbapi.rst Fri Apr 16 16:40:25 2010 +0200 @@ -80,6 +80,8 @@ the orm. +.. _resultset: + The `ResultSet` API ~~~~~~~~~~~~~~~~~~~ diff -r 34dc38456376 -r d2dbba898a96 doc/book/en/development/devweb/views/baseviews.rst --- a/doc/book/en/development/devweb/views/baseviews.rst Fri Apr 16 14:39:42 2010 +0200 +++ b/doc/book/en/development/devweb/views/baseviews.rst Fri Apr 16 16:40:25 2010 +0200 @@ -1,14 +1,14 @@ .. -*- coding: utf-8 -*- -Base views (:mod:`cubicweb.web.views.baseviews`) ------------------------------------------------- +Base views +---------- -*CubicWeb* provides a lot of standard views. You can find them in -``cubicweb/web/views/``. +*CubicWeb* provides a lot of standard views, that can be found in + :mod:`cubicweb.web.views` and :mod:`cubicweb.web.views.baseviews`. -A certain number of views are used to build the web interface, which apply -to one or more entities. Their identifier is what distinguish them from -each others and the main ones are: +A certain number of views are used to build the web interface, which +apply to one or more entities. Their identifier is what distinguish +them from each others and the main ones are: HTML views ~~~~~~~~~~ @@ -24,22 +24,27 @@ Display the value of a cell without trasnformation (in case of a non final entity, we see the eid). Applicable on any result set. +.. note:: + + `final` entities are merely attributes. + *null* This view is the default view used when nothing needs to be rendered. - It is always applicable and it does not return anything + It is always applicable. Entity views ```````````` + *incontext, outofcontext* Those are used to display a link to an entity, depending on the entity having to be displayed in or out of context - (of another entity). By default it respectively returns the + (of another entity). By default it respectively produces the result of `textincontext` and `textoutofcontext` wrapped in a link leading to the primary view of the entity. *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 returns the result of `text` + displayed in or out of context. By default it produces the result of `text` in a link leading to the primary view of the entity. List @@ -67,6 +72,7 @@ Text entity views ~~~~~~~~~~~~~~~~~ + *text* This is the simplest text view for an entity. By default it returns the result of the `.dc_title` method, which is cut to fit the diff -r 34dc38456376 -r d2dbba898a96 doc/book/en/development/devweb/views/boxes.rst --- a/doc/book/en/development/devweb/views/boxes.rst Fri Apr 16 14:39:42 2010 +0200 +++ b/doc/book/en/development/devweb/views/boxes.rst Fri Apr 16 16:40:25 2010 +0200 @@ -33,3 +33,4 @@ Please note that if at least one action belongs to the `addrelated` category, the automatic behavior is desactivated in favor of an explicit behavior (e.g. display of `addrelated` category actions only). + diff -r 34dc38456376 -r d2dbba898a96 doc/book/en/development/devweb/views/editforms.rst --- a/doc/book/en/development/devweb/views/editforms.rst Fri Apr 16 14:39:42 2010 +0200 +++ b/doc/book/en/development/devweb/views/editforms.rst Fri Apr 16 16:40:25 2010 +0200 @@ -1,3 +1,6 @@ -Standard forms (:mod:`cubicweb.web.views.editforms`) ----------------------------------------------------- +Standard forms +-------------- + + (:mod:`cubicweb.web.views.editforms`) + XXX feed me diff -r 34dc38456376 -r d2dbba898a96 doc/book/en/development/devweb/views/embedding.rst --- a/doc/book/en/development/devweb/views/embedding.rst Fri Apr 16 14:39:42 2010 +0200 +++ b/doc/book/en/development/devweb/views/embedding.rst Fri Apr 16 16:40:25 2010 +0200 @@ -1,9 +1,9 @@ .. -*- coding: utf-8 -*- -Embedding external pages (:mod:`cubicweb.web.views.embedding`) ---------------------------------------------------------------- +Embedding external pages +------------------------ + +(:mod:`cubicweb.web.views.embedding`) including external content -XXX feeed me - diff -r 34dc38456376 -r d2dbba898a96 doc/book/en/development/devweb/views/facets.rst --- a/doc/book/en/development/devweb/views/facets.rst Fri Apr 16 14:39:42 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,3 +0,0 @@ -Facets (:mod:`cubicweb.web.views.facets`) ------------------------------------------ -XXX feed me diff -r 34dc38456376 -r d2dbba898a96 doc/book/en/development/devweb/views/idownloadable.rst --- a/doc/book/en/development/devweb/views/idownloadable.rst Fri Apr 16 14:39:42 2010 +0200 +++ b/doc/book/en/development/devweb/views/idownloadable.rst Fri Apr 16 16:40:25 2010 +0200 @@ -1,3 +1,5 @@ -The 'download' view (:mod:`cubicweb.web.views.idownloadable`) ---------------------------------------------------------------- +The 'download' view +------------------- +(:mod:`cubicweb.web.views.idownloadable`) + diff -r 34dc38456376 -r d2dbba898a96 doc/book/en/development/devweb/views/index.rst --- a/doc/book/en/development/devweb/views/index.rst Fri Apr 16 14:39:42 2010 +0200 +++ b/doc/book/en/development/devweb/views/index.rst Fri Apr 16 16:40:25 2010 +0200 @@ -1,8 +1,6 @@ The View system =============== -.. |cubicweb| replace:: *CubicWeb* - 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|. @@ -27,7 +25,6 @@ urlpublish breadcrumbs -.. facets .. wdoc .. embedding .. idownloadable diff -r 34dc38456376 -r d2dbba898a96 doc/book/en/development/devweb/views/primary.rst --- a/doc/book/en/development/devweb/views/primary.rst Fri Apr 16 14:39:42 2010 +0200 +++ b/doc/book/en/development/devweb/views/primary.rst Fri Apr 16 16:40:25 2010 +0200 @@ -203,7 +203,7 @@ overwrite ``render_entity`` unless you want a completely different layout. Example of customization and creation -------------------------------------- +````````````````````````````````````` We'll show you now an example of a ``primary`` view and how to customize it. diff -r 34dc38456376 -r d2dbba898a96 doc/book/en/development/devweb/views/startup.rst --- a/doc/book/en/development/devweb/views/startup.rst Fri Apr 16 14:39:42 2010 +0200 +++ b/doc/book/en/development/devweb/views/startup.rst Fri Apr 16 16:40:25 2010 +0200 @@ -1,11 +1,10 @@ Startup views ------------- - (:mod:`cubicweb.web.views.startup`) +(:mod:`cubicweb.web.views.startup`) -Usual selector: no_rset or yes. - -Views that don't apply to a result set +The usual selectors are no_rset or yes. These views don't apply to a +result set. *index* This view defines the home page of your application. It does not require diff -r 34dc38456376 -r d2dbba898a96 doc/book/en/development/devweb/views/table.rst --- a/doc/book/en/development/devweb/views/table.rst Fri Apr 16 14:39:42 2010 +0200 +++ b/doc/book/en/development/devweb/views/table.rst Fri Apr 16 16:40:25 2010 +0200 @@ -1,5 +1,7 @@ -Table views (:mod:`cubicweb.web.views.table`) ----------------------------------------------- +Table view +---------- + +(:mod:`cubicweb.web.views.tableview`) *table* Creates a HTML table (``) and call the view `cell` for each cell of @@ -8,3 +10,10 @@ *cell* By default redirects to the `final` view if this is a final entity or `outofcontext` view otherwise + + +API +``` + +.. autoclass:: cubicweb.web.views.tableview.TableView + :members: diff -r 34dc38456376 -r d2dbba898a96 doc/book/en/development/devweb/views/views.rst --- a/doc/book/en/development/devweb/views/views.rst Fri Apr 16 14:39:42 2010 +0200 +++ b/doc/book/en/development/devweb/views/views.rst Fri Apr 16 16:40:25 2010 +0200 @@ -15,14 +15,29 @@ .. _views_base_class: +Discovering possible views +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is possible to configure the web user interface to have a left box +showing all the views than can be applied to the current result set. + +To enable this, click on your login at the top right corner. Chose +"user preferences", then "boxes", then "possible views box" and check +"visible = yes" before validating your changes. + +The views listed there we either not selected because of a lower +score, or they were deliberately excluded by the main template logic. + + Basic class for views ~~~~~~~~~~~~~~~~~~~~~ Class `View` (`cubicweb.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. +This class is an abstraction of a view class, used as a base class for +every renderable object such as views, templates and other user +interface components. A `View` is instantiated to render a result set or part of a result set. `View` subclasses may be parametrized using the following class @@ -109,8 +124,6 @@ __select__ = one_line_rset() & match_search_state('linksearch') & implements('Any') - - XML views, binaries views... ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff -r 34dc38456376 -r d2dbba898a96 doc/book/en/development/devweb/views/xmlrss.rst --- a/doc/book/en/development/devweb/views/xmlrss.rst Fri Apr 16 14:39:42 2010 +0200 +++ b/doc/book/en/development/devweb/views/xmlrss.rst Fri Apr 16 16:40:25 2010 +0200 @@ -1,7 +1,9 @@ .. _XmlAndRss: -XML and RSS views (:mod:`cubicweb.web.views.xmlrss`) ----------------------------------------------------- +XML and RSS views +----------------- + +(:mod:`cubicweb.web.views.xmlrss`) Overview +++++++++ @@ -14,7 +16,6 @@ Create a RSS/XML view for each entity based on the results of the dublin core methods of the entity (`dc_*`) - RSS Channel Example ++++++++++++++++++++ @@ -57,6 +58,3 @@ of blog entries, thus providing a RSS channel * show that a different selection (by category) means a different channel - - - diff -r 34dc38456376 -r d2dbba898a96 rset.py --- a/rset.py Fri Apr 16 14:39:42 2010 +0200 +++ b/rset.py Fri Apr 16 16:40:25 2010 +0200 @@ -15,21 +15,22 @@ class ResultSet(object): - """A result set wraps a RQL query result. This object implements a partial - list protocol to allow direct use as a list of result rows. + """A result set wraps a RQL query result. This object implements + partially the list protocol to allow direct use as a list of + result rows. :type rowcount: int - :ivar rowcount: number of rows in the result + :param rowcount: number of rows in the result :type rows: list - :ivar rows: list of rows of result + :param rows: list of rows of result :type description: list - :ivar description: + :param description: result's description, using the same structure as the result itself :type rql: str or unicode - :ivar rql: the original RQL query string + :param rql: the original RQL query string """ def __init__(self, results, rql, args=None, description=(), cachekey=None, rqlst=None): @@ -204,7 +205,8 @@ return rset def split_rset(self, keyfunc=None, col=0, return_dict=False): - """splits the result set in multiple result set according to a given key + """splits the result set in multiple result sets according to + a given key :type keyfunc: callable(entity or FinalType) :param keyfunc: @@ -252,7 +254,7 @@ return result def limited_rql(self): - """return a printable rql for the result set associated to the object, + """returns a printable rql for the result set associated to the object, with limit/offset correctly set according to maximum page size and currently displayed page when necessary """ @@ -377,12 +379,14 @@ @cached def get_entity(self, row, col): - """special method for query retreiving a single entity, returns a + """convenience method for query retrieving a single entity, returns a partially initialized Entity instance. - WARNING: due to the cache wrapping this function, you should NEVER - give row as a named parameter (i.e. rset.get_entity(req, 0) - is OK but rset.get_entity(row=0, req=req) isn't + .. warning: + + Due to the cache wrapping this function, you should NEVER + give row as a named parameter (i.e. rset.get_entity(req, 0) + is OK but rset.get_entity(row=0, req=req) isn't) :type row,col: int, int :param row,col: diff -r 34dc38456376 -r d2dbba898a96 web/views/tableview.py --- a/web/views/tableview.py Fri Apr 16 14:39:42 2010 +0200 +++ b/web/views/tableview.py Fri Apr 16 16:40:25 2010 +0200 @@ -23,6 +23,11 @@ from cubicweb.web.facet import prepare_facets_rqlst, filter_hiddens class TableView(AnyRsetView): + """The table view accepts any non-empty rset. It uses + introspection on the result set to compute column names and the + proper way to display the cells. + It is however highly configurable and accepts a wealth of options. + """ __regid__ = 'table' title = _('table') finalview = 'final' @@ -50,29 +55,30 @@ def _generate_form(self, divid, baserql, fwidgets, hidden=True, vidargs={}): """display a form to filter table's content. This should only - occurs when a context eid is given + occur when a context eid is given """ + w = self.w self._cw.add_css('cubicweb.facets.css') self._cw.add_js( ('cubicweb.ajax.js', 'cubicweb.facets.js')) # drop False / None values from vidargs vidargs = dict((k, v) for k, v in vidargs.iteritems() if v) - self.w(u'' % - xml_escape(dumps([divid, 'table', False, vidargs]))) - self.w(u'
' % (divid, hidden and 'hidden' or '')) - self.w(u'' % divid) - self.w(u'') - filter_hiddens(self.w, facets=','.join(wdg.facet.__regid__ for wdg in fwidgets), + w(u'' % + xml_escape(dumps([divid, 'table', False, vidargs]))) + w(u'
' % (divid, hidden and 'hidden' or '')) + w(u'' % divid) + w(u'') + filter_hiddens(w, facets=','.join(wdg.facet.__regid__ for wdg in fwidgets), baserql=baserql) - self.w(u'
\n') - self.w(u'\n') + w(u'
\n') + w(u'\n') for wdg in fwidgets: - self.w(u'\n') - self.w(u'\n') - self.w(u'
') - wdg.render(w=self.w) - self.w(u'
\n') - self.w(u'\n') - self.w(u'\n') + w(u'') + wdg.render(w=w) + w(u'\n') + w(u'\n') + w(u'\n') + w(u'\n') + w(u'\n') def main_var_index(self): """returns the index of the first non-attribute variable among the RQL @@ -98,7 +104,7 @@ def call(self, title=None, subvid=None, displayfilter=None, headers=None, displaycols=None, displayactions=None, actions=(), divid=None, cellvids=None, cellattrs=None, mainindex=None): - """Dumps a table displaying a composite query + """Produces a table displaying a composite query :param title: title added before table :param subvid: cell view