`) - and call the view `sameetypelistitem` for each entity of the result set. - -*sameetypelistitem* - This view redirects by default to the `listitem` view. - -*csv* - This view applies to entity groups, which are individually - displayed using the `incontext` view. It displays each entity as a - coma separated list. It is NOT related to the well-known text file - format. - -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 - `navigation.short-line-size` property if necessary. - -*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. diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/development/devweb/views/boxes.rst --- a/doc/book/en/development/devweb/views/boxes.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,36 +0,0 @@ -Boxes ------ - -(:mod:`cubicweb.web.views.boxes`) - -*sidebox* - This view displays usually a side box of some related entities - in a primary view. - -The action box -~~~~~~~~~~~~~~~ - -The ``add_related`` is an automatic menu in the action box that allows to create -an entity automatically related to the initial entity (context in -which the box is displayed). By default, the links generated in this -box are computed from the schema properties of the displayed entity, -but it is possible to explicitly specify them thanks to the -`cubicweb.web.uicfg.rmode` *relation tag*: - -* `link`, indicates that a relation is in general created pointing - to an existing entity and that we should not to display a link - for this relation - -* `create`, indicates that a relation is in general created pointing - to new entities and that we should display a link to create a new - entity and link to it automatically - - -If necessary, it is possible to overwrite the method -`relation_mode(rtype, targettype, x='subject')` to dynamically -compute a relation creation category. - -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 354cf5ef31dc -r 092bb9355769 doc/book/en/development/devweb/views/breadcrumbs.rst --- a/doc/book/en/development/devweb/views/breadcrumbs.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,58 +0,0 @@ -Breadcrumbs ------------ - -Breadcrumbs are a navigation component to help the user locate himself -along a path of entities. - -Display -~~~~~~~ - -Breadcrumbs are displayed by default in the header section (see -:ref:`the_main_template_sections`). With the default main -template, the header section is composed by the logo, the application -name, breadcrumbs and, at the most right, the login box. Breadcrumbs -are displayed just next to the application name, thus breadcrumbs -begin with a separator. - -Here is the header section of the CubicWeb's forge: - -.. image:: ../../../images/breadcrumbs_header.png - -There are three breadcrumbs components defined in -:mod:`cubicweb.web.views.ibreadcrumbs`: - -- `BreadCrumbEntityVComponent`: displayed for a result set with one line - if the entity implements the ``IBreadCrumbs`` interface. -- `BreadCrumbETypeVComponent`: displayed for a result set with more than - one line, but with all entities of the same type which implement the - ``IBreadCrumbs`` interface. -- `BreadCrumbAnyRSetVComponent`: displayed for any other result set. - -Building breadcrumbs -~~~~~~~~~~~~~~~~~~~~ - -The ``IBreadCrumbs`` interface is defined in the -:mod:`cubicweb.interfaces` module. It specifies that an entity which -implements this interface must have a ``breadcrumbs`` method. - -.. note:: - - Redefining the breadcrumbs is the hammer way to do it. Another way - is to define the `parent` method on an entity (as defined in the - `ITree` interface). If available, it will be used to compute - breadcrumbs. - -Here is the API of the ``breadcrumbs`` method: - -.. automethod:: cubicweb.interfaces.IBreadCrumbs.breadcrumbs - -If the breadcrumbs method return a list of entities, the -``cubicweb.web.views.ibreadcrumbs.BreadCrumbView`` is used to display -the elements. - -By default, for any entity, if recurs=True, breadcrumbs method returns -a list of entities, else a list of a simple string. - -In order to see a hierarchical breadcrumbs, entities must have a -``parent`` method which returns the parent entity. By default this -method doesn't exist on entity, given that it can not be guessed. diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/development/devweb/views/editforms.rst --- a/doc/book/en/development/devweb/views/editforms.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,6 +0,0 @@ -Standard forms --------------- - - (:mod:`cubicweb.web.views.editforms`) - -XXX feed me diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/development/devweb/views/embedding.rst --- a/doc/book/en/development/devweb/views/embedding.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,9 +0,0 @@ -.. -*- coding: utf-8 -*- - -Embedding external pages ------------------------- - -(:mod:`cubicweb.web.views.embedding`) - -including external content - diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/development/devweb/views/idownloadable.rst --- a/doc/book/en/development/devweb/views/idownloadable.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -The 'download' view -------------------- - -(:mod:`cubicweb.web.views.idownloadable`) - diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/development/devweb/views/index.rst --- a/doc/book/en/development/devweb/views/index.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,30 +0,0 @@ -The View system -=============== - -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|. - - -.. toctree:: - :maxdepth: 3 - - views - basetemplates - primary - baseviews - startup - boxes - table - xmlrss -.. editforms - -.. toctree:: - :maxdepth: 3 - - urlpublish - breadcrumbs -.. wdoc -.. embedding -.. idownloadable - diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/development/devweb/views/primary.rst --- a/doc/book/en/development/devweb/views/primary.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,312 +0,0 @@ -.. _primary_view: - -The Primary View ------------------ - -(:mod:`cubicweb.web.views.primary`) - -By default, *CubicWeb* provides a view that fits every available -entity type. This is the first view you might be interested in -modifying. It is also one of the richest and most complex. - -It is automatically selected on a one line result set containing an -entity. - -This view is supposed to render a maximum of informations about the -entity. - -.. _primary_view_layout: - -Layout -`````` - -The primary view has the following layout. - -.. image:: ../../../images/primaryview_template.png - -.. _primary_view_configuration: - -Primary view configuration -`````````````````````````` - -If you want to customize the primary view of an entity, overriding the primary -view class may not be necessary. For simple adjustments (attributes or relations -display locations and styles), a much simpler way is to use uicfg. - -Attributes/relations display location -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In the primary view, there are 3 sections where attributes and -relations can be displayed (represented in pink in the image above): - -* attributes -* relations -* sideboxes - -**Attributes** can only be displayed in the attributes section (default - behavior). They can also be hidden. - -For instance, to hide the ``title`` attribute of the ``Blog`` entity: - -.. sourcecode:: python - - from cubicweb.web import uicfg - uicfg.primaryview_section.tag_attribute(('Blog', 'title'), 'hidden') - -**Relations** can be either displayed in one of the three sections or hidden. - -For relations, there are two methods: - -* ``tag_object_of`` for modifying the primary view of the object -* ``tag_subject_of`` for modifying the primary view of the subject - -These two methods take two arguments: - -* a triplet ``(subject, relation_name, object)``, where subject or object can be replaced with ``'*'`` -* the section name or ``hidden`` - -.. sourcecode:: python - - pv_section = uicfg.primaryview_section - # hide every relation `entry_of` in the `Blog` primary view - pv_section.tag_object_of(('*', 'entry_of', 'Blog'), 'hidden') - - # display `entry_of` relations in the `relations` - # section in the `BlogEntry` primary view - pv_section.tag_subject_of(('BlogEntry', 'entry_of', '*'), 'relations') - - -Display content -^^^^^^^^^^^^^^^ - -You can use ``primaryview_display_ctrl`` to customize the display of attributes -or relations. Values of ``primaryview_display_ctrl`` are dictionaries. - - -Common keys for attributes and relations are: - -* ``vid``: specifies the regid of the view for displaying the attribute or the relation. - - If ``vid`` is not specified, the default value depends on the section: - * ``attributes`` section: 'reledit' view - * ``relations`` section: 'autolimited' view - * ``sideboxes`` section: 'sidebox' view - -* ``order``: int used to control order within a section. When not specified, - automatically set according to order in which tags are added. - -.. sourcecode:: python - - # let us remind the schema of a blog entry - class BlogEntry(EntityType): - title = String(required=True, fulltextindexed=True, maxsize=256) - publish_date = Date(default='TODAY') - content = String(required=True, fulltextindexed=True) - entry_of = SubjectRelation('Blog', cardinality='?*') - - # now, we want to show attributes - # with an order different from that in the schema definition - view_ctrl = uicfg.primaryview_display_ctrl - for index, attr in enumerate('title', 'content', 'publish_date'): - view_ctrl.tag_attribute(('BlogEntry', attr), {'order': index}) - -Keys for relations only: - -* ``label``: label for the relations section or side box - -* ``showlabel``: boolean telling whether the label is displayed - -* ``limit``: boolean telling if the results should be limited. If so, a link to all results is displayed - -* ``filter``: callback taking the related result set as argument and returning it filtered - -.. sourcecode:: python - - pv_section = uicfg.primaryview_section - # in `CWUser` primary view, display `created_by` - # relations in relations section - pv_section.tag_object_of(('*', 'created_by', 'CWUser'), 'relations') - - # display this relation as a list, sets the label, - # limit the number of results and filters on comments - def filter_comment(rset): - return rset.filtered_rset(lambda x: x.e_schema == 'Comment') - pv_ctrl = uicfg.primaryview_display_ctrl - pv_ctrl.tag_object_of(('*', 'created_by', 'CWUser'), - {'vid': 'list', 'label': _('latest comment(s):'), - 'limit': True, - 'filter': filter_comment}) - -.. warning:: with the ``primaryview_display_ctrl`` rtag, the subject or the - object of the relation is ignored for respectively ``tag_object_of`` or - ``tag_subject_of``. To avoid warnings during execution, they should be set to - ``'*'``. - -Rendering methods and attributes -```````````````````````````````` - -The basic layout of a primary view is as in the -:ref:`primary_view_layout` section. This layout is actually drawn by -the `render_entity` method. - -The methods you may want to modify while customizing a ``PrimaryView`` -are: - -*render_entity_title(self, entity)* - Renders the entity title using the ``def dc_title(self)`` method. - -*render_entity_metadata(self, entity)* - Renders the entity metadata by calling the ``metadata`` view on the - entity. This generic view is in cubicweb.views.baseviews. - -*render_entity_attributes(self, entity)* - Renders all the attribute of an entity with the exception of - attribute of type `Password` and `Bytes`. The skip_none class - attribute controls the display of None valued attributes. - -*render_entity_relations(self, entity)* - Renders all the relations of the entity in the main section of the page. - -*render_side_boxes(self, entity, boxes)* - Renders relations of the entity in a side box. - -The placement of relations in the relations section or in side boxes -can be controlled through the :ref:`primary_view_configuration` mechanism. - -*content_navigation_components(self, context)* - This method is applicable only for entity type implementing the interface - `IPrevNext`. This interface is for entities which can be linked to a previous - and/or next entity. This method will render the navigation links between - entities of this type, either at the top or at the bottom of the page - given the context (navcontent{top|bottom}). - -Also, please note that by setting the following attributes in your -subclass, you can already customize some of the rendering: - -*show_attr_label* - Renders the attribute label next to the attribute value if set to True. - Otherwise, does only display the attribute value. - -*show_rel_label* - Renders the relation label next to the relation value if set to True. - Otherwise, does only display the relation value. - -*skip_none* - Does not render an attribute value that is None if set to True. - -*main_related_section* - Renders the relations of the entity if set to True. - -A good practice is for you to identify the content of your entity type for which -the default rendering does not answer your need so that you can focus on the specific -method (from the list above) that needs to be modified. We do not advise you to -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. - -We continue along the basic tutorial :ref:`tuto_blog`. - -If you want to change the way a ``BlogEntry`` is displayed, just override -the method ``cell_call()`` of the view ``primary`` in ``BlogDemo/views.py``. - -.. sourcecode:: python - - from cubicweb.selectors import implements - from cubicweb.web.views.primary import Primaryview - - class BlogEntryPrimaryView(PrimaryView): - __select__ = PrimaryView.__select__ & implements('BlogEntry') - - def render_entity_attributes(self, entity): - self.w(u'

published on %s

' % - entity.publish_date.strftime('%Y-%m-%d')) - super(BlogEntryPrimaryView, self).render_entity_attributes(entity) - -The above source code defines a new primary view for -``BlogEntry``. The `id` class attribute is not repeated there since it -is inherited through the `primary.PrimaryView` class. - -The selector for this view chains the selector of the inherited class -with its own specific criterion. - -The view method ``self.w()`` is used to output data. Here `lines -08-09` output HTML for the publication date of the entry. - -.. image:: ../../../images/lax-book.09-new-view-blogentry.en.png - :alt: blog entries now look much nicer - -Let us now improve the primary view of a blog - -.. sourcecode:: python - - from logilab.mtconverter import xml_escape - from cubicweb.selectors import implements, one_line_rset - from cubicweb.web.views.primary import Primaryview - - class BlogPrimaryView(PrimaryView): - __regid__ = 'primary' - __select__ = PrimaryView.__select__ & implements('Blog') - rql = 'Any BE ORDERBY D DESC WHERE BE entry_of B, BE publish_date D, B eid %(b)s' - - def render_entity_relations(self, entity): - rset = self._cw.execute(self.rql, {'b' : entity.eid}) - for entry in rset.entities(): - self.w(u'

' % entry.view('inblogcontext')) - - class BlogEntryInBlogView(EntityView): - __regid__ = 'inblogcontext' - __select__ = implements('BlogEntry') - - def cell_call(self, row, col): - entity = self.cw_rset.get_entity(row, col) - self.w(u'%s' % - entity.absolute_url(), - xml_escape(entity.content[:50]), - xml_escape(entity.description)) - -This happens in two places. First we override the -render_entity_relations method of a Blog's primary view. Here we want -to display our blog entries in a custom way. - -At `line 10`, 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 infers that such entities have to be of the -``BlogEntry`` kind and retrieves them (in the prescribed publish_date -order). - -The request returns a selection of data called a result set. Result -set objects have an .entities() method returning a generator on -requested entities (going transparently through the `ORM` layer). - -At `line 13` the view 'inblogcontext' is applied to each blog entry to -output HTML. (Note that the 'inblogcontext' view is not defined -whatsoever in *CubicWeb*. You are absolutely free to define whole view -families.) We juste arrange to wrap each blogentry output in a 'p' -html element. - -Next, we define the 'inblogcontext' view. This is NOT a primary view, -with its well-defined sections (title, metadata, attribtues, -relations/boxes). All a basic view has to define is cell_call. - -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 -20`). Then we can spit some HTML. - -.. warning:: - - Be careful: all strings manipulated in *CubicWeb* are actually - unicode strings. While web browsers are usually tolerant to - incoherent encodings they are being served, we should not abuse - it. Hence we have to properly escape our data. The xml_escape() - function has to be used to safely fill (X)HTML elements from Python - unicode strings. - -Assuming we added entries to the blog titled `MyLife`, displaying it -now allows to read its description and all its entries. - -.. image:: ../../../images/lax-book.10-blog-with-two-entries.en.png - :alt: a blog and all its entries diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/development/devweb/views/startup.rst --- a/doc/book/en/development/devweb/views/startup.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,15 +0,0 @@ -Startup views -------------- - -(:mod:`cubicweb.web.views.startup`) - -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 - a result set to apply to. - -*schema* - A view dedicated to the display of the schema of the instance - diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/development/devweb/views/table.rst --- a/doc/book/en/development/devweb/views/table.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,19 +0,0 @@ -Table view ----------- - -(:mod:`cubicweb.web.views.tableview`) - -*table* - Creates a HTML table (``) and call the view `cell` for each cell of - the result set. Applicable on any result set. - -*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 354cf5ef31dc -r 092bb9355769 doc/book/en/development/devweb/views/urlpublish.rst --- a/doc/book/en/development/devweb/views/urlpublish.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,73 +0,0 @@ -.. -*- coding: utf-8 -*- - -URL publishing --------------- - -(:mod:`cubicweb.web.views.urlpublishing`) - -.. automodule:: cubicweb.web.views.urlpublishing - -.. autoclass:: cubicweb.web.views.urlpublishing.URLPublisherComponent - :members: - -URL rewriting -------------- - -(:mod:`cubicweb.web.views.urlrewrite`) - -.. autoclass:: cubicweb.web.views.urlrewrite.URLRewriter - :members: - -.. autoclass:: cubicweb.web.views.urlrewrite.SimpleReqRewriter - :members: - -.. autoclass:: cubicweb.web.views.urlrewrite.SchemaBasedRewriter - :members: - - -``SimpleReqRewriter`` is enough for a certain number of simple cases. If it is not sufficient, ``SchemaBasedRewriter`` allows to do more elaborate things. - -Here is an example of ``SimpleReqRewriter`` usage with plain string: - -.. sourcecode:: python - - from cubicweb.web.views.urlrewrite import SimpleReqRewriter - class TrackerSimpleReqRewriter(SimpleReqRewriter): - rules = [ - ('/versions', dict(vid='versionsinfo')), - ] - -When the url is `/versions`, the view with the __regid__ `versionsinfo` is displayed. - -Here is an example of ``SimpleReqRewriter`` usage with regular expressions: - -.. sourcecode:: python - - from cubicweb.web.views.urlrewrite import ( - SimpleReqRewriter, rgx) - - class BlogReqRewriter(SimpleReqRewriter): - rules = [ - (rgx('/blogentry/([a-z_]+)\.rss'), - dict(rql=('Any X ORDERBY CD DESC LIMIT 20 WHERE X is BlogEntry,' - 'X creation_date CD, X created_by U, ' - 'U login "%(user)s"' - % {'user': r'\1'}, vid='rss'))), - ] - -When a url matches the regular expression, the view with the __regid__ -`rss` which match the result set is displayed. - -Here is an example of ``SchemaBasedRewriter`` usage: - -.. sourcecode:: python - - from cubicweb.web.views.urlrewrite import ( - SchemaBasedRewriter, rgx, build_rset) - - class TrackerURLRewriter(SchemaBasedRewriter): - rules = [ - (rgx('/project/([^/]+)/([^/]+)/tests'), - build_rset(rql='Version X WHERE X version_of P, P name %(project)s, X num %(num)s', - rgxgroups=[('project', 1), ('num', 2)], vid='versiontests')), - ] diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/development/devweb/views/views.rst --- a/doc/book/en/development/devweb/views/views.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,142 +0,0 @@ - -.. _Views: - -Principles ----------- - -We'll start with a description of the interface providing a basic -understanding of the available classes and methods, then detail the -view selection principle. - -A `View` is an object responsible for the rendering of data from the -model into an end-user consummable form. They typically churn out an -XHTML stream, but there are views concerned with email other non-html -outputs. - -.. _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 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 -attributes: - -* `templatable` indicates if the view may be embedded in a main - template or if it has to be rendered standalone (i.e. pure XML views - must not be embedded in the main template of HTML pages) - -* if the view is not templatable, it should set the `content_type` - class attribute to the correct MIME type (text/xhtml being the - default) - -* the `category` attribute may be used in the interface to regroup - related view kinds together - -A view writes to its output stream thanks to its attribute `w` (the -append method of an `UStreamIO`, except for binary views). - -At instantiation time, the standard `_cw` and `cw_rset` attributes are -added and the `w` attribute will be set at rendering time. - -The basic interface for views is as follows (remember that the result -set has a tabular structure with rows and columns, hence cells): - -* `render(**context)`, render the view by calling `call` or - `cell_call` depending on the context - -* `call(**kwargs)`, call the view for a complete result set or null - (the default implementation calls `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 (`row` and `col` being integers used to access the cell) - -* `url()`, returns the URL enabling us to get the view with the current - result set - -* `wview(__vid, rset, __fallback_vid=None, **kwargs)`, call the view of - identifier `__vid` on the given result set. It is possible to give a - fallback view identifier that will be used if the requested view is - not applicable to the result set. - -* `html_headers()`, returns a list of HTML headers to be set by the - main template - -* `page_title()`, returns the title to use in the HTML header `title` - -Other basic view classes -```````````````````````` -Here are some of the subclasses of `View` defined in `cubicweb.common.view` -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 -* `AnyRsetView`, view applicable to any result set - -Examples of views class -``````````````````````` - -- Using `templatable`, `content_type` and HTTP cache configuration - -.. sourcecode:: python - - class RSSView(XMLView): - __regid__ = 'rss' - title = _('rss') - templatable = False - content_type = 'text/xml' - http_cache_manager = MaxAgeHTTPCacheManager - cache_max_age = 60*60*2 # stay in http cache for 2 hours by default - - -- Using a custom selector - -.. sourcecode:: python - - class SearchForAssociationView(EntityView): - """view called by the edition view when the user asks - to search for something to link to the edited eid - """ - __regid__ = 'search-associate' - title = _('search for association') - __select__ = one_line_rset() & match_search_state('linksearch') & implements('Any') - - -XML views, binaries views... -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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 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` or any - relevant and more specialised mime type - -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 354cf5ef31dc -r 092bb9355769 doc/book/en/development/devweb/views/wdoc.rst --- a/doc/book/en/development/devweb/views/wdoc.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,9 +0,0 @@ -.. -*- coding: utf-8 -*- - -Online documentation system ---------------------------- - -(:mod:`cubicweb.web.views.wdoc`) - -XXX describe the on-line documentation system - diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/development/devweb/views/xmlrss.rst --- a/doc/book/en/development/devweb/views/xmlrss.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,60 +0,0 @@ -.. _XmlAndRss: - -XML and RSS views ------------------ - -(:mod:`cubicweb.web.views.xmlrss`) - -Overview -+++++++++ - -*rss* - Creates a RSS/XML view and call the view `rssitem` for each entity of - the result set. - -*rssitem* - Create a RSS/XML view for each entity based on the results of the dublin core - methods of the entity (`dc_*`) - -RSS Channel Example -++++++++++++++++++++ - -Assuming you have several blog entries, click on the title of the -search box in the left column. A larger search box should appear. Enter:: - - Any X ORDERBY D WHERE X is BlogEntry, X creation_date D - -and you get a list of blog entries. - -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. - -Enter the same query in the search box and you will see the same list, -plus a box titled "possible views" in the left column. Click on -"entityview", then "RSS". - -You just applied the "RSS" view to the RQL selection you requested. - -That's it, you have a RSS channel for your blog. - -Try again with:: - - Any X ORDERBY D WHERE X is BlogEntry, X creation_date D, - X entry_of B, B title "MyLife" - -Another RSS channel, but a bit more focused. - -A last one for the road:: - - Any C ORDERBY D WHERE C is Comment, C creation_date D LIMIT 15 - -displayed with the RSS view, that's a channel for the last fifteen -comments posted. - -[WRITE ME] - -* show that the RSS view can be used to display an ordered selection - of blog entries, thus providing a RSS channel - -* show that a different selection (by category) means a different channel diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/development/entityclasses/application-logic.rst --- a/doc/book/en/development/entityclasses/application-logic.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,166 +0,0 @@ -How to use entities objects ---------------------------- - -The previous chapters detailed the classes and methods available to -the developper at the so-called `ORM`_ level. However they say little -about the common patterns of usage of these objects. - -.. _`ORM`: http://en.wikipedia.org/wiki/Object-relational_mapping - -Entities objects are used in the repository and web sides of -CubicWeb. On the repository side of things, one should manipulate them -in Hooks and Operations. - -Hooks and Operations provide support for the implementation of rules -such as computed attributes, coherency invariants, etc (they play the -same role as database triggers, but in a way that is independant of -the actual data sources). - -So a lot of an application's business rules will be written in Hooks -(or Operations). - -On the web side, views also typically operate using entity -objects. Obvious entity methods for use in views are the dublin code -method like dc_title, etc. For separation of concerns reasons, one -should ensure no ui logic pervades the entities level, and also no -business logic should creep into the views. - -In the duration of a transaction, entities objects can be instantiated -many times, in views and hooks, even for the same database entity. For -instance, in a classic CubicWeb deployment setup, the repository and -the web frontend are separated process communicating over the -wire. There is no way state can be shared between these processes -(there is a specific API for that). Hence, it is not possible to use -entity objects as messengers between these components of an -application. It means that an attribute set as in `obj.x = 42`, -whether or not x is actually an entity schema attribute, has a short -life span, limited to the hook, operation or view within which the -object was built. - -Setting an attribute or relation value can be done in the context of a -Hook/Operation, using the obj.set_attributes(x=42) notation or a plain -RQL SET expression. - -In views, it would be preferable to encapsulate the necessary logic in -a method of the concerned entity class(es). But of course, this advice -is also reasonnable for Hooks/Operations, though the separation of -concerns here is less stringent than in the case of views. - -This leads to the practical role of entity objects: it's where an -important part of the application logic lie (the other part being -located in the Hook/Operations). - -Anatomy of an entity class --------------------------- - -We can look now at a real life example coming from the `tracker`_ -cube. Let us begin to study the entities/project.py content. - -.. sourcecode:: python - - class Project(TreeMixIn, AnyEntity): - __regid__ = 'Project' - __implements__ = AnyEntity.__implements__ + (ITree,) - fetch_attrs, fetch_order = fetch_config(('name', 'description', - 'description_format', 'summary')) - - TICKET_DEFAULT_STATE_RESTR = 'S name IN ("created","identified","released","scheduled")' - - tree_attribute = 'subproject_of' - parent_target = 'subject' - children_target = 'object' - - def dc_title(self): - return self.name - -First we see that it uses an ITree interface and the TreeMixIn default -implementation. The attributes `tree_attribute`, `parent_target` and -`children_target` are used by the TreeMixIn code. This is typically -used in views concerned with the representation of tree-like -structures (CubicWeb provides several such views). - -It is important that the views themselves try not to implement this -logic, not only because such views would be hardly applyable to other -tree-like relations, but also because it is perfectly fine and useful -to use such an interface in Hooks. - -In fact, Tree nature is a property of the data model that cannot be -fully and portably expressed at the level of database entities (think -about the transitive closure of the child relation). This is a further -argument to implement it at entity class level. - -The `dc_title` method provides a (unicode string) value likely to be -consummed by views, but note that here we do not care about output -encodings. We care about providing data in the most universal format -possible, because the data could be used by a web view (which would be -responsible of ensuring XHTML compliance), or a console or file -oriented output (which would have the necessary context about the -needed byte stream encoding). - -The fetch_attrs, fetch_order class attributes are parameters of the -`ORM`_ layer. They tell which attributes should be loaded at once on -entity object instantiation (by default, only the eid is known, other -attributes are loaded on demand), and which attribute is to be used to -order the .related() and .unrelated() methods output. - -Finally, we can observe the big TICKET_DEFAULT_STATE_RESTR is a pure -application domain piece of data. There is, of course, no limitation -to the amount of class attributes of this kind. - -Let us now dig into more substantial pieces of code. - -.. sourcecode:: python - - def latest_version(self, states=('published',), reverse=None): - """returns the latest version(s) for the project in one of the given - states. - - when no states specified, returns the latest published version. - """ - order = 'DESC' - if reverse is not None: - warn('reverse argument is deprecated', - DeprecationWarning, stacklevel=1) - if reverse: - order = 'ASC' - rset = self.versions_in_state(states, order, True) - if rset: - return rset.get_entity(0, 0) - return None - - def versions_in_state(self, states, order='ASC', limit=False): - """returns version(s) for the project in one of the given states, sorted - by version number. - - If limit is true, limit result to one version. - If reverse, versions are returned from the smallest to the greatest. - """ - if limit: - order += ' LIMIT 1' - rql = 'Any V,N ORDERBY version_sort_value(N) %s ' \ - 'WHERE V num N, V in_state S, S name IN (%s), ' \ - 'V version_of P, P eid %%(p)s' % (order, ','.join(repr(s) for s in states)) - return self._cw.execute(rql, {'p': self.eid}) - -.. _`tracker`: http://www.cubicweb.org/project/cubicweb-tracker/ - -These few lines exhibit the important properties we want to outline: - -* entity code is concerned with the application domain - -* it is NOT concerned with database coherency (this is the realm of - Hooks/Operations); in other words, it assumes a coherent world - -* it is NOT concerned with end-user interfaces - -* however it can be used in both contexts - -* it does not create or manipulate the internal object's state - -* it plays freely with RQL expression as needed - -* it is not concerned with internationalization - -* it does not raise exceptions - - diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/development/entityclasses/data-as-objects.rst --- a/doc/book/en/development/entityclasses/data-as-objects.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,136 +0,0 @@ -Access to persistent data --------------------------- - -Python-level access to persistent data is provided by the -:class:`Entity ` class. - -An entity class is bound to a schema entity type. Descriptors are added when -classes are registered in order to initialize the class according to its schema: - -* we can access the defined attributes in the schema thanks to the attributes of - the same name on instances (typed value) - -* we can access the defined relations in the schema thanks to the relations of - the same name on instances (entities instances list) - - -:Formatting and output generation: - - * `view(__vid, __registry='views', **kwargs)`, applies the given view to the entity - (and returns an unicode string) - - * `absolute_url(*args, **kwargs)`, returns an absolute URL to access the primary view - of an entity - - * `rest_path()`, returns a relative REST URL to get the entity - - * `printable_value(attr, value=_marker, attrtype=None, format='text/html', displaytime=True)`, - returns a string enabling the display of an attribute value in a given format - (the value is automatically recovered if necessary) - -:Data handling: - - * `as_rset()`, converts the entity into an equivalent result set simulating the - request `Any X WHERE X eid _eid_` - - * `complete(skip_bytes=True)`, executes a request that recovers at - once all the missing attributes of an entity - - * `get_value(name)`, returns the value associated to the attribute name given - in parameter - - * `related(rtype, role='subject', limit=None, entities=False)`, - returns a list of entities related to the current entity by the - relation given in parameter - - * `unrelated(rtype, targettype, role='subject', limit=None)`, - returns a result set corresponding to the entities not (yet) - related to the current entity by the relation given in parameter - and satisfying its constraints - - * `set_attributes(**kwargs)`, updates the attributes list with the corresponding - values given named parameters - - * `set_relations(**kwargs)`, add relations to the given object. To - set a relation where this entity is the object of the relation, - use `reverse_` as argument name. Values may be an - entity, a list of entities, or None (meaning that all relations of - the given type from or to this object should be deleted). - - * `copy_relations(ceid)`, copies the relations of the entities having the eid - given in the parameters on the current entity - - * `delete()` allows to delete the entity - - -The :class:`AnyEntity` class ----------------------------- - -To provide a specific behavior for each entity, we have to define a class -inheriting from `cubicweb.entities.AnyEntity`. In general, we define this class -in `mycube.entities` module (or in a submodule if we want to split code among -multiple files) so that it will be available on both server and client side. - -The class `AnyEntity` is a sub-class of Entity that add methods to it, -and helps specializing (by further subclassing) the handling of a -given entity type. - -Most methods defined for `AnyEntity`, in addition to `Entity`, add -support for the `Dublin Core`_ metadata. - -.. _`Dublin Core`: http://dublincore.org/ - -:Standard meta-data (Dublin Core): - - * `dc_title()`, returns a unicode string corresponding to the - meta-data `Title` (used by default is the first non-meta attribute - of the entity schema) - - * `dc_long_title()`, same as dc_title but can return a more - detailed title - - * `dc_description(format='text/plain')`, returns a unicode string - corresponding to the meta-data `Description` (looks for a - description attribute by default) - - * `dc_authors()`, returns a unicode string corresponding to the meta-data - `Authors` (owners by default) - - * `dc_creator()`, returns a unicode string corresponding to the - creator of the entity - - * `dc_date(date_format=None)`, returns a unicode string corresponding to - the meta-data `Date` (update date by default) - - * `dc_type(form='')`, returns a string to display the entity type by - specifying the preferred form (`plural` for a plural form) - - * `dc_language()`, returns the language used by the entity - - -:Misc methods: - - * `after_deletion_path`, return (path, parameters) which should be - used as redirect information when this entity is being deleted - - * `pre_web_edit`, callback called by the web editcontroller when an - entity will be created/modified, to let a chance to do some entity - specific stuff (does nothing by default) - -Inheritance ------------ - -When describing a data model, entities can inherit from other entities as is -common in object-oriented programming. - -You have the possibility to adapt some entity attributes, as follow: - -.. sourcecode:: python - - from cubes.OTHER_CUBE import entities - class EntityExample(entities.EntityExample): - def dc_long_title(self): - return '%s (%s)' % (self.name, self.description) - -Notice this is different than yams schema inheritance. - diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/development/entityclasses/index.rst --- a/doc/book/en/development/entityclasses/index.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ -Data as objects -=============== - -In this chapter, we will introduce the objects that are used to handle -the logic associated to the data stored in the database. - -.. toctree:: - :maxdepth: 1 - - data-as-objects - load-sort - interfaces - application-logic diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/development/entityclasses/interfaces.rst --- a/doc/book/en/development/entityclasses/interfaces.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,65 +0,0 @@ -Interfaces ----------- - -This is the same thing as object-oriented programming `interfaces`_. - -.. _`interfaces`: http://java.sun.com/docs/books/tutorial/java/concepts/interface.html - -Definition of an interface is quite trivial. An example from cubicweb -itself (found in cubicweb/interfaces.py): - -.. sourcecode:: python - - class ITree(Interface): - - def parent(self): - """returns the parent entity""" - - def children(self): - """returns the item's children""" - - def children_rql(self): - """returns RQL to get children""" - - def iterchildren(self): - """iterates over the item's children""" - - def is_leaf(self): - """returns true if this node as no child""" - - def is_root(self): - """returns true if this node has no parent""" - - def root(self): - """returns the root object""" - - -Declaration of interfaces implemented by a class -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. sourcecode:: python - - from cubicweb.interfaces import ITree - from cubicweb.mixins import TreeMixIn - - class MyEntity(TreeMixIn, AnyEntity): - __regid__ = 'MyEntity' - __implements__ = AnyEntity.__implements__ + ('ITree',) - - tree_attribute = 'filed_under' - -The TreeMixIn here provides a default implementation for the -interface. The tree_attribute class attribute is actually used by this -implementation to help implement correct behaviour. - -Interfaces (and some implementations as mixins) defined in the library -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: cubicweb.interfaces - :members: - -.. automodule:: cubicweb.mixins - :members: - - - diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/development/entityclasses/load-sort.rst --- a/doc/book/en/development/entityclasses/load-sort.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,53 +0,0 @@ - -.. _FetchAttrs: - -Loaded attributes and default sorting management -```````````````````````````````````````````````` - -* The class attribute `fetch_attrs` allows to define in an entity class a list - of names of attributes or relations that should be automatically loaded when - entities of this type are fetched from the database. In the case of relations, - we are limited to *subject of cardinality `?` or `1`* relations. - -* The class method `fetch_order(attr, var)` expects an attribute (or relation) - name as a parameter and a variable name, and it should return a string - to use in the requirement `ORDERBY` of an RQL query to automatically - sort the list of entities of such type according to this attribute, or - `None` if we do not want to sort on the attribute given in the parameter. - By default, the entities are sorted according to their creation date. - -* The class method `fetch_unrelated_order(attr, var)` is similar to - the method `fetch_order` except that it is essentially used to - control the sorting of drop-down lists enabling relations creation - in the editing view of an entity. The default implementation uses - the modification date. Here's how to adapt it for one entity (sort - on the name attribute): :: - - class MyEntity(AnyEntity): - __regid__ = 'MyEntity' - fetch_attrs = ('modification_date', 'name') - - @classmethod - def fetch_unrelated_order(cls, attr, var): - if attr == 'name': - return '%s ASC' % var - return None - - -The function `fetch_config(fetchattrs, mainattr=None)` simplifies the -definition of the attributes to load and the sorting by returning a -list of attributes to pre-load (considering automatically the -attributes of `AnyEntity`) and a sorting function based on the main -attribute (the second parameter if specified, otherwise the first -attribute from the list `fetchattrs`). This function is defined in -`cubicweb.entities`. - -For example: :: - - class Transition(AnyEntity): - """...""" - __regid__ = 'Transition' - fetch_attrs, fetch_order = fetch_config(['name']) - -Indicates that for the entity type "Transition", you have to pre-load -the attribute `name` and sort by default on this attribute. diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/development/index.rst --- a/doc/book/en/development/index.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,22 +0,0 @@ -.. _Part2: - ------------ -Development ------------ - -This part is about developing web applications with the *CubicWeb* framework. - -.. toctree:: - :maxdepth: 2 - :numbered: - - cubes/index - vreg.rst - datamodel/index - entityclasses/index - devcore/index - devweb/index - devrepo/index - testing.rst - migration.rst - profiling.rst diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/development/migration.rst --- a/doc/book/en/development/migration.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,198 +0,0 @@ -.. -*- coding: utf-8 -*- - -.. _migration: - -Migration -========= - -One of the main design goals of *CubicWeb* was to support iterative and agile -development. For this purpose, multiple actions are provided to facilitate the -improvement of an instance, and in particular to handle the changes to be -applied to the data model, without loosing existing data. - -The current version of a cube (and of cubicweb itself) is provided in the file -`__pkginfo__.py` as a tuple of 3 integers. - -Migration scripts management ----------------------------- - -Migration scripts has to be located in the directory `migration` of your -cube and named accordingly: - -:: - - [_]_.py - -in which : - -* X.Y.Z is the model version number to which the script enables to migrate. - -* *mode* (between the last "_" and the extension ".py") is used for - distributed installation. It indicates to which part - of the application (RQL server, web server) the script applies. - Its value could be : - - * `common`, applies to the RQL server as well as the web server and updates - files on the hard drive (configuration files migration for example). - - * `web`, applies only to the web server and updates files on the hard drive. - - * `repository`, applies only to the RQL server and updates files on the - hard drive. - - * `Any`, applies only to the RQL server and updates data in the database - (schema and data migration for example). - -Again in the directory `migration`, the file `depends.map` allows to indicate -that for the migration to a particular model version, you always have to first -migrate to a particular *CubicWeb* version. This file can contain comments (lines -starting by `#`) and a dependancy is listed as follows: :: - - : - -For example: :: - - 0.12.0: 2.26.0 - 0.13.0: 2.27.0 - # 0.14 works with 2.27 <= cubicweb <= 2.28 at least - 0.15.0: 2.28.0 - -Base context ------------- - -The following identifiers are pre-defined in migration scripts: - -* `config`, instance configuration - -* `interactive_mode`, boolean indicating that the script is executed in - an interactive mode or not - -* `versions_map`, dictionary of migrated versions (key are cubes - names, including 'cubicweb', values are (from version, to version) - -* `confirm(question)`, function asking the user and returning true - if the user answers yes, false otherwise (always returns true in - non-interactive mode) - -* `_()` is equivalent to `unicode` allowing to flag the strings to - internationalize in the migration scripts. - -In the `repository` scripts, the following identifiers are also defined: - -* `commit(ask_confirm=True)`, request confirming and executing a "commit" - -* `schema`, instance schema (readen from the database) - -* `fsschema`, installed schema on the file system (e.g. schema of - the updated model and cubicweb) - -* `repo`, repository object - -* `session`, repository session object - - -Schema migration ----------------- -The following functions for schema migration are available in `repository` -scripts: - -* `add_attribute(etype, attrname, attrtype=None, commit=True)`, adds a new - attribute to an existing entity type. If the attribute type is not specified, - then it is extracted from the updated schema. - -* `drop_attribute(etype, attrname, commit=True)`, removes an attribute from an - existing entity type. - -* `rename_attribute(etype, oldname, newname, commit=True)`, renames an attribute - -* `add_entity_type(etype, auto=True, commit=True)`, adds a new entity type. - If `auto` is True, all the relations using this entity type and having a known - entity type on the other hand will automatically be added. - -* `drop_entity_type(etype, commit=True)`, removes an entity type and all the - relations using it. - -* `rename_entity_type(oldname, newname, commit=True)`, renames an entity type - -* `add_relation_type(rtype, addrdef=True, commit=True)`, adds a new relation - type. If `addrdef` is True, all the relations definitions of this type will - be added. - -* `drop_relation_type(rtype, commit=True)`, removes a relation type and all the - definitions of this type. - -* `rename_relation(oldname, newname, commit=True)`, renames a relation. - -* `add_relation_definition(subjtype, rtype, objtype, commit=True)`, adds a new - relation definition. - -* `drop_relation_definition(subjtype, rtype, objtype, commit=True)`, removes - a relation definition. - -* `sync_schema_props_perms(ertype=None, syncperms=True, syncprops=True, syncrdefs=True, commit=True)`, - synchronizes properties and/or permissions on: - - the whole schema if ertype is None - - an entity or relation type schema if ertype is a string - - a relation definition if ertype is a 3-uple (subject, relation, object) - -* `change_relation_props(subjtype, rtype, objtype, commit=True, **kwargs)`, changes - properties of a relation definition by using the named parameters of the properties - to change. - -* `set_widget(etype, rtype, widget, commit=True)`, changes the widget used for the - relation of entity type . - -* `set_size_constraint(etype, rtype, size, commit=True)`, changes the size constraints - for the relation of entity type . - -Data migration --------------- -The following functions for data migration are available in `repository` scripts: - -* `rql(rql, kwargs=None, cachekey=None, ask_confirm=True)`, executes an arbitrary RQL - query, either to interrogate or update. A result set object is returned. - -* `add_entity(etype, *args, **kwargs)`, adds a nes entity type of the given - type. The attribute and relation values are specified using the named and - positionned parameters. - -Workflow creation ------------------ - -The following functions for workflow creation are available in `repository` -scripts: - -* `add_workflow(label, workflowof, initial=False, commit=False, **kwargs)`, adds a new workflow - for a given type(s) - -You can find more details about workflows in the chapter :ref:`Workflow` . - -Configuration migration ------------------------ - -The following functions for configuration migration are available in all -scripts: - -* `option_renamed(oldname, newname)`, indicates that an option has been renamed - -* `option_group_change(option, oldgroup, newgroup)`, indicates that an option does not - belong anymore to the same group. - -* `option_added(oldname, newname)`, indicates that an option has been added. - -* `option_removed(oldname, newname)`, indicates that an option has been deleted. - - -Others migration functions --------------------------- -Those functions are only used for low level operations that could not be -accomplished otherwise or to repair damaged databases during interactive -session. They are available in `repository` scripts: - -* `sql(sql, args=None, ask_confirm=True)`, executes an arbitrary SQL query on the system source -* `add_entity_type_table(etype, commit=True)` -* `add_relation_type_table(rtype, commit=True)` -* `uninline_relation(rtype, commit=True)` - - -[FIXME] Add explanation on how to use cubicweb-ctl shell diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/development/profiling.rst --- a/doc/book/en/development/profiling.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,55 +0,0 @@ -Profiling and performance -========================= - -If you feel that one of your pages takes more time than it should to be -generated, chances are that you're making too many RQL queries. Obviously, -there are other reasons but experience tends to show this is the first thing to -track down. Luckily, CubicWeb provides a configuration option to log RQL -queries. In your ``all-in-one.conf`` file, set the **query-log-file** option:: - - # web application query log file - query-log-file=~/myapp-rql.log - -Then restart your application, reload your page and stop your application. -The file ``myapp-rql.log`` now contains the list of RQL queries that were -executed during your test. It's a simple text file containing lines such as:: - - Any A WHERE X eid %(x)s, X lastname A {'x': 448} -- (0.002 sec, 0.010 CPU sec) - Any A WHERE X eid %(x)s, X firstname A {'x': 447} -- (0.002 sec, 0.000 CPU sec) - -The structure of each line is:: - - -- - -CubicWeb also provides the **exlog** command to examine and summarize data found -in such a file: - -.. sourcecode:: sh - - $ cubicweb-ctl exlog < ~/myapp-rql.log - 0.07 50 Any A WHERE X eid %(x)s, X firstname A {} - 0.05 50 Any A WHERE X eid %(x)s, X lastname A {} - 0.01 1 Any X,AA ORDERBY AA DESC WHERE E eid %(x)s, E employees X, X modification_date AA {} - 0.01 1 Any X WHERE X eid %(x)s, X owned_by U, U eid %(u)s {, } - 0.01 1 Any B,T,P ORDERBY lower(T) WHERE B is Bookmark,B title T, B path P, B bookmarked_by U, U eid %(x)s {} - 0.01 1 Any A,B,C,D WHERE A eid %(x)s,A name B,A creation_date C,A modification_date D {} - -This command sorts and uniquifies queries so that it's easy to see where -is the hot spot that needs optimization. - -Do not neglect to set the **fetch_attrs** attribute you can define in your -entity classes because it can greatly reduce the number of queries executed (see -:ref:`FetchAttrs`). - -You should also know about the **profile** option in the ``all-in-on.conf``. If -set, this option will make your application run in an `hotshot`_ session and -store the results in the specified file. - -.. _hotshot: http://docs.python.org/library/hotshot.html#module-hotshot - -Last but no least, if you're using the PostgreSQL database backend, VACUUMing -your database can significantly improve the performance of the queries (by -updating the statistics used by the query optimizer). Nowadays, this is done -automatically from time to time, but if you've just imported a large amount of -data in your db, you will want to vacuum it (with the analyse option on). Read -the documentation of your database for more information. diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/development/testing.rst --- a/doc/book/en/development/testing.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,258 +0,0 @@ -.. -*- coding: utf-8 -*- - -Tests -===== - -Unit tests ----------- - -The *CubicWeb* framework provides the `CubicWebTC` test base class in -the module `cubicweb.devtools.testlib`. - -Tests shall be put into the mycube/test directory. Additional test -data shall go into mycube/test/data. - -It is much advised to write tests concerning entities methods, hooks -and operations, security. The CubicWebTC base class has convenience -methods to help test all of this. - -.. note:: - - In the realm of views, there is not much to do but check that the - views are valid XHTML. See :ref:`automatic_views_tests` for - details. Integration of CubicWeb tests with UI testing tools such as - `selenium`_ are currently under invesitgation. - -.. _selenium: http://seleniumhq.org/projects/ide/ - -Most unit tests need a live database to work against. This is achieved -by CubicWeb using automatically sqlite (bundled with Python, see -http://docs.python.org/library/sqlite3.html) as a backend. - -The database is stored in the mycube/test/tmpdb, -mycube/test/tmpdb-template files. If it does not (yet) exists, it will -be built automatically when the test suit starts. - -.. warning:: - - Whenever the schema changes (new entities, attributes, relations) - one must delete these two files. Changes concerned only with entity - or relation type properties (constraints, cardinalities, - permissions) and generally dealt with using the - `sync_schema_props_perms()` fonction of the migration environment - need not a database regeneration step. - -Unit test by example -```````````````````` - -We start with an example extracted from the keyword cube (available -from http://www.cubicweb.org/project/cubicweb-keyword). - -.. sourcecode:: python - - from cubicweb.devtools.testlib import CubicWebTC - from cubicweb import ValidationError - - class ClassificationHooksTC(CubicWebTC): - - def setup_database(self): - req = self.request() - group_etype = req.execute('Any X WHERE X name "CWGroup"').get_entity(0,0) - c1 = req.create_entity('Classification', name=u'classif1', - classifies=group_etype) - user_etype = req.execute('Any X WHERE X name "CWUser"').get_entity(0,0) - c2 = req.create_entity('Classification', name=u'classif2', - classifies=user_etype) - self.kw1 = req.create_entity('Keyword', name=u'kwgroup', included_in=c1) - self.kw2 = req.create_entity('Keyword', name=u'kwuser', included_in=c2) - - def test_cannot_create_cycles(self): - # direct obvious cycle - self.assertRaises(ValidationError, self.kw1.set_relations, - subkeyword_of=self.kw1) - # testing indirect cycles - kw3 = self.execute('INSERT Keyword SK: SK name "kwgroup2", SK included_in C, ' - 'SK subkeyword_of K WHERE C name "classif1", K eid %s' - % self.kw1.eid).get_entity(0,0) - self.kw1.set_relations(subkeyword_of=kw3) - self.assertRaises(ValidationError, self.commit) - -The test class defines a `setup_database` method which populates the -database with initial data. Each test of the class runs with this -pre-populated database. - -The test case itself checks that an Operation does it job of -preventing cycles amongst Keyword entities. - -You can see an example of security tests in the -:ref:`adv_tuto_security`. - -It is possible to have these tests run continuously using `apycot`_. - -.. _apycot: http://www.logilab.org/project/apycot - -Managing connections or users -+++++++++++++++++++++++++++++ - -Since unit tests are done with the SQLITE backend and this does not -support multiple connections at a time, you must be careful when -simulating security, changing users. - -By default, tests run with a user with admin privileges. This -user/connection must never be closed. - -Before a self.login, one has to release the connection pool in use -with a self.commit, self.rollback or self.close. - -The `login` method returns a connection object that can be used as a -context manager: - -.. sourcecode:: python - - with self.login('user1') as user: - req = user.req - req.execute(...) - -On exit of the context manager, either a commit or rollback is issued, -which releases the connection. - -When one is logged in as a normal user and wants to switch back to the -admin user without committing, one has to use -self.restore_connection(). - -Usage with restore_connection: - -.. sourcecode:: python - - # execute using default admin connection - self.execute(...) - # I want to login with another user, ensure to free admin connection pool - # (could have used rollback but not close here - # we should never close defaut admin connection) - self.commit() - cnx = self.login('user') - # execute using user connection - self.execute(...) - # I want to login with another user or with admin user - self.commit(); cnx.close() - # restore admin connection, never use cnx = self.login('admin'), it will return - # the default admin connection and one may be tempted to close it - self.restore_connection() - -.. warning:: - - Do not use the references kept to the entities created with a - connection from another ! - -Email notifications tests -------------------------- - -When running tests potentially generated e-mails are not really sent -but is found in the list `MAILBOX` of module -`cubicweb.devtools.testlib`. - -You can test your notifications by analyzing the contents of this list, which -contains objects with two attributes: - -* `recipients`, the list of recipients -* `msg`, object email.Message - -Let us look at simple example from the ``blog`` cube. - -.. sourcecode:: python - - from cubicweb.devtools.testlib import CubicWebTC, MAILBOX - - class BlogTestsCubicWebTC(CubicWebTC): - """test blog specific behaviours""" - - def test_notifications(self): - req = self.request() - cubicweb_blog = req.create_entity('Blog', title=u'cubicweb', - description=u'cubicweb is beautiful') - blog_entry_1 = req.create_entity('BlogEntry', title=u'hop', - content=u'cubicweb hop') - blog_entry_1.set_relations(entry_of=cubicweb_blog) - blog_entry_2 = req.create_entity('BlogEntry', title=u'yes', - content=u'cubicweb yes') - blog_entry_2.set_relations(entry_of=cubicweb_blog) - self.assertEquals(len(MAILBOX), 0) - self.commit() - self.assertEquals(len(MAILBOX), 2) - mail = MAILBOX[0] - self.assertEquals(mail.subject, '[data] hop') - mail = MAILBOX[1] - self.assertEquals(mail.subject, '[data] yes') - -.. _automatic_views_tests: - -Automatic views testing ------------------------ - -This is done automatically with the AutomaticWebTest class. At cube -creation time, the mycube/test/test_mycube.py file contains such a -test. The code here has to be uncommented to be usable, without -further modification. - -The ``auto_populate`` method uses a smart algorithm to create -pseudo-random data in the database, thus enabling the views to be -invoked and tested. - -Depending on the schema, hooks and operations constraints, it is not -always possible for the automatic auto_populate to proceed. - -It is possible of course to completely redefine auto_populate. A -lighter solution is to give hints (fill some class attributes) about -what entities and relations have to be skipped by the auto_populate -mechanism. These are: - -* `no_auto_populate`, may contain a list of entity types to skip -* `ignored_relations`, may contain a list of relation types to skip -* `application_rql`, may contain a list of rql expressions that - auto_populate cannot guess by itself; these must yield resultsets - against which views may be selected. - - -Test APIS ---------- - -Using Pytest -```````````` - -The `pytest` utility (shipping with `logilab-common`_, which is a -mandatory dependency of CubicWeb) extends the Python unittest -functionality and is the preferred way to run the CubicWeb test -suites. Bare unittests also work the usual way. - -.. _logilab-common: http://www.logilab.org/project/logilab-common - -To use it, you may: - -* just launch `pytest` in your cube to execute all tests (it will - discover them automatically) -* launch `pytest unittest_foo.py` to execute one test file -* launch `pytest unittest_foo.py bar` to execute all test methods and - all test cases whose name contain `bar` - -Additionally, the `-x` option tells pytest to exit at the first error -or failure. The `-i` option tells pytest to drop into pdb whenever an -exception occurs in a test. - -When the `-x` option has been used and the run stopped on a test, it -is possible, after having fixed the test, to relaunch pytest with the -`-R` option to tell it to start testing again from where it previously -failed. - -Using the `TestCase` base class -``````````````````````````````` - -The base class of CubicWebTC is logilab.common.testlib.TestCase, which -provides a lot of convenient assertion methods. - -.. autoclass:: logilab.common.testlib.TestCase - :members: - -CubicWebTC API -`````````````` -.. autoclass:: cubicweb.devtools.testlib.CubicWebTC - :members: diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/development/vreg.rst --- a/doc/book/en/development/vreg.rst Fri Apr 23 13:36:43 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,107 +0,0 @@ -The VRegistry, selectors and application objects -================================================ - -This chapter talks about core concepts of the |cubicweb| framework, -that make it different from other frameworks (and maybe not easy to -grasp at a first glance). To be able to do advanced development with -|cubicweb| you need a good understanding of what is explained below. - -This chapter goes deep into details. You don't have to remember them -all but keep it in mind so you can go back there later. - -An overview of AppObjects, the VRegistry and Selectors is given in the -:ref:`VRegistryIntro` chapter. - -.. autodocstring:: cubicweb.cwvreg -.. autodocstring:: cubicweb.selectors -.. automodule:: cubicweb.appobject - -Base selectors --------------- - -Selectors are scoring functions that are called by the registry to tell whenever -an appobject can be selected in a given context. Selector sets are for instance -the glue that tie views to the data model. Using them appropriately is an -essential part of the construction of well behaved cubes. - -Of course you may have to write your own set of selectors as your needs grows and -you get familiar with the framework (see :ref:`CustomSelectors`). - -Here is a description of generic selectors provided by CubicWeb that should suit -most of your needs. - -Bare selectors -~~~~~~~~~~~~~~ -Those selectors are somewhat dumb, which doesn't mean they're not (very) useful. - -.. autoclass:: cubicweb.appobject.yes -.. autoclass:: cubicweb.selectors.match_kwargs -.. autoclass:: cubicweb.selectors.appobject_selectable - - -Result set selectors -~~~~~~~~~~~~~~~~~~~~~ -Those selectors are looking for a result set in the context ('rset' argument or -the input context) and match or not according to its shape. Some of these -selectors have different behaviour if a particular cell of the result set is -specified using 'row' and 'col' arguments of the input context or not. - -.. autoclass:: cubicweb.selectors.none_rset -.. autoclass:: cubicweb.selectors.any_rset -.. autoclass:: cubicweb.selectors.nonempty_rset -.. autoclass:: cubicweb.selectors.empty_rset -.. autoclass:: cubicweb.selectors.one_line_rset -.. autoclass:: cubicweb.selectors.multi_lines_rset -.. autoclass:: cubicweb.selectors.multi_columns_rset -.. autoclass:: cubicweb.selectors.paginated_rset -.. autoclass:: cubicweb.selectors.sorted_rset -.. autoclass:: cubicweb.selectors.one_etype_rset -.. autoclass:: cubicweb.selectors.multi_etypes_rset - - -Entity selectors -~~~~~~~~~~~~~~~~ -Those selectors are looking for either an `entity` argument in the input context, -or entity found in the result set ('rset' argument or the input context) and -match or not according to entity's (instance or class) properties. - -.. autoclass:: cubicweb.selectors.non_final_entity -.. autoclass:: cubicweb.selectors.implements -.. autoclass:: cubicweb.selectors.score_entity -.. autoclass:: cubicweb.selectors.rql_condition -.. autoclass:: cubicweb.selectors.relation_possible -.. autoclass:: cubicweb.selectors.partial_relation_possible -.. autoclass:: cubicweb.selectors.has_related_entities -.. autoclass:: cubicweb.selectors.partial_has_related_entities -.. autoclass:: cubicweb.selectors.has_permission -.. autoclass:: cubicweb.selectors.has_add_permission - - -Logged user selectors -~~~~~~~~~~~~~~~~~~~~~ -Those selectors are looking for properties of the user issuing the request. - -.. autoclass:: cubicweb.selectors.anonymous_user -.. autoclass:: cubicweb.selectors.authenticated_user -.. autoclass:: cubicweb.selectors.match_user_groups - - -Web request selectors -~~~~~~~~~~~~~~~~~~~~~ -Those selectors are looking for properties of *web* request, they can not be -used on the data repository side. - -.. autoclass:: cubicweb.selectors.match_form_params -.. autoclass:: cubicweb.selectors.match_search_state -.. autoclass:: cubicweb.selectors.match_context_prop -.. autoclass:: cubicweb.selectors.match_view -.. autoclass:: cubicweb.selectors.primary_view -.. autoclass:: cubicweb.selectors.specified_etype_implements - - -Other selectors -~~~~~~~~~~~~~~~ -.. autoclass:: cubicweb.selectors.match_transition - -You'll also find some other (very) specific selectors hidden in other modules -than :mod:`cubicweb.selectors`. diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devrepo/cubes/available-cubes.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devrepo/cubes/available-cubes.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,64 @@ + +Available cubes +--------------- + +An instance is based on several basic cubes. In the set of available +basic cubes we can find for example : + +Base entity types +~~~~~~~~~~~~~~~~~ +* addressbook_: PhoneNumber and PostalAddress +* card_: Card, generic documenting card +* event_: Event (define events, display them in calendars) +* file_: File (to allow users to upload and store binary or text files) +* link_: Link (to collect links to web resources) +* mailinglist_: MailingList (to reference a mailing-list and the URLs + for its archives and its admin interface) +* person_: Person (easily mixed with addressbook) +* task_: Task (something to be done between start and stop date) +* zone_: Zone (to define places within larger places, for example a + city in a state in a country) + + +Classification +~~~~~~~~~~~~~~ +* folder_: Folder (to organize things but grouping them in folders) +* keyword_: Keyword (to define classification schemes) +* tag_: Tag (to tag anything) + +Other features +~~~~~~~~~~~~~~ +* basket_: Basket (like a shopping cart) +* blog_: a blogging system uxing Blog and BlogEntry entity types +* comment_: system to attach comment threads to entities) +* email_: archiving management for emails (`Email`, `Emailpart`, + `Emailthread`), trigger action in cubicweb through email + + + + + +.. _addressbook: http://www.cubicweb.org/project/cubicweb-addressbook +.. _basket: http://www.cubicweb.org/project/cubicweb-basket +.. _card: http://www.cubicweb.org/project/cubicweb-card +.. _blog: http://www.cubicweb.org/project/cubicweb-blog +.. _comment: http://www.cubicweb.org/project/cubicweb-comment +.. _email: http://www.cubicweb.org/project/cubicweb-email +.. _event: http://www.cubicweb.org/project/cubicweb-event +.. _file: http://www.cubicweb.org/project/cubicweb-file +.. _folder: http://www.cubicweb.org/project/cubicweb-folder +.. _keyword: http://www.cubicweb.org/project/cubicweb-keyword +.. _link: http://www.cubicweb.org/project/cubicweb-link +.. _mailinglist: http://www.cubicweb.org/project/cubicweb-mailinglist +.. _person: http://www.cubicweb.org/project/cubicweb-person +.. _tag: http://www.cubicweb.org/project/cubicweb-tag +.. _task: http://www.cubicweb.org/project/cubicweb-task +.. _zone: http://www.cubicweb.org/project/cubicweb-zone + +To declare the use of a component, once installed, add the name of the component +to the variable `__use__` in the file `__pkginfo__.py` of your own component. + +.. note:: + The listed cubes above are available as debian-packages on `CubicWeb's forge`_. + +.. _`CubicWeb's forge`: http://www.cubicweb.org/project?vtitle=All%20cubicweb%20projects diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devrepo/cubes/cc-newcube.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devrepo/cubes/cc-newcube.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,50 @@ +Creating a new cube from scratch using :command:`cubicweb-ctl newcube` +---------------------------------------------------------------------- + +Let's start by creating the cube environment in which we will develop :: + + cd ~/cubes + # use cubicweb-ctl to generate a template for the cube + # will ask some questions, most with nice default + cubicweb-ctl newcube mycube + # makes the cube source code managed by mercurial + cd mycube + hg init + hg add . + hg ci + +If all went well, you should see the cube you just created in the list +returned by ``cubicweb-ctl list`` in the section *Available cubes*, +and if it is not the case please refer to :ref:`ConfigurationEnv`. + +To reuse an existing cube, add it to the list named +``__depends_cubes__`` and defined in :file:`__pkginfo__.py`. This +variable is used for the instance packaging (dependencies handled by +system utility tools such as APT) and the usable cubes at the time the +base is created (import_erschema('MyCube') will not properly work +otherwise). + +.. note:: + + Please note that if you do not wish to use default directory for your cubes + library, you should set the :envvar:`CW_CUBES_PATH` environment variable to + add extra directories where cubes will be search, and you'll then have to use + the option `--directory` to specify where you would like to place the source + code of your cube: + + ``cubicweb-ctl newcube --directory=/path/to/cubes/library mycube`` + + +.. XXX resurrect once live-server is back +.. Usage of :command:`cubicweb-ctl liveserver` +.. ------------------------------------------- + +.. To quickly test a new cube, you can also use the `liveserver` command for cubicweb-ctl +.. which allows to create an instance in memory (using an SQLite database by +.. default) and make it accessible through a web server :: + +.. cubicweb-ctl live-server mycube + +.. or by using an existing database (SQLite or Postgres):: + +.. cubicweb-ctl live-server -s myfile_sources mycube diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devrepo/cubes/index.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devrepo/cubes/index.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,11 @@ +Cubes +===== + +This chapter describes how to define your own cubes and reuse already available cubes. + +.. toctree:: + :maxdepth: 1 + + layout.rst + cc-newcube.rst + available-cubes.rst diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devrepo/cubes/layout.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devrepo/cubes/layout.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,134 @@ + +.. _foundationsCube: + +.. _cubelayout: + +Standard structure for a cube +----------------------------- + +A cube is structured as follows: + +:: + + mycube/ + | + |-- data/ + | |-- cubes.mycube.css + | |-- cubes.mycube.js + | `-- external_resources + | + |-- debian/ + | |-- changelog + | |-- compat + | |-- control + | |-- copyright + | |-- cubicweb-mycube.prerm + | `-- rules + | + |-- entities.py + | + |-- i18n/ + | |-- en.po + | |-- es.po + | `-- fr.po + | + |-- __init__.py + | + |-- MANIFEST.in + | + |-- migration/ + | |-- postcreate.py + | `-- precreate.py + | + |-- __pkginfo__.py + | + |-- schema.py + | + |-- setup.py + | + |-- site_cubicweb.py + | + |-- hooks.py + | + |-- test/ + | |-- data/ + | | `-- bootstrap_cubes + | |-- pytestconf.py + | |-- realdb_test_mycube.py + | `-- test_mycube.py + | + `-- views.py + + +We can use subpackages instead of python modules for ``views.py``, ``entities.py``, +``schema.py`` or ``hooks.py``. For example, we could have: + +:: + + mycube/ + | + |-- entities.py + |-- hooks.py + `-- views/ + |-- forms.py + |-- primary.py + `-- widgets.py + + +where : + +* ``schema`` contains the schema definition (server side only) +* ``entities`` contains the entities definition (server side and web interface) +* ``hooks`` contains hooks and/or views notifications (server side only) +* ``views`` contains the web interface components (web interface only) +* ``test`` contains tests related to the cube (not installed) +* ``i18n`` contains message catalogs for supported languages (server side and + web interface) +* ``data`` contains data files for static content (images, css, javascripts) + ...(web interface only) +* ``migration`` contains initialization files for new instances (``postcreate.py``) + and a file containing dependencies of the component depending on the version + (``depends.map``) +* ``debian`` contains all the files managing debian packaging (you will find + the usual files ``control``, ``rules``, ``changelog``... not installed) +* file ``__pkginfo__.py`` provides component meta-data, especially the distribution + and the current version (server side and web interface) or sub-cubes used by + the cube. + + +At least you should have the file ``__pkginfo__.py``. + + +The :file:`__init__.py` and :file:`site_cubicweb.py` files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :file:`__pkginfo__.py` file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It contains metadata describing your cubes, mostly useful for +packaging. + + +:file:`migration/precreate.py` and :file:`migration/postcreate.py` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. XXX detail steps of instance creation + + +External resources such as image, javascript and css files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. XXX naming convention external_resources file + + +Out-of the box testing +~~~~~~~~~~~~~~~~~~~~~~ + +.. XXX MANIFEST.in, __pkginfo__.include_dirs, debian + + +Packaging and distribution +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. XXX MANIFEST.in, __pkginfo__.include_dirs, debian + diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devrepo/datamodel/baseschema.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devrepo/datamodel/baseschema.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,43 @@ +.. _pre_defined_entity_types: + +Pre-defined entities in the library +----------------------------------- + +The library defines a set of entity schemas that are required by the system +or commonly used in *CubicWeb* instances. + + +Entity types used to store the schema +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* _`CWEType`, entity type +* _`CWRType`, relation type +* _`CWRelation`, relation definition +* _`CWAttribute`, attribute relation definition +* _`CWConstraint`, `CWConstraintType`, `RQLExpression` + +Entity types used to manage users and permissions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* _`CWUser`, system users +* _`CWGroup`, users groups +* _`CWPermission`, used to configure the security of the instance + +Entity types used to manage workflows +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* _`Workflow`, workflow entity, linked to some entity types which may use this workflow +* _`State`, workflow state +* _`Transition`, workflow transition +* _`TrInfo`, record of a transition trafic for an entity + +Other entity types +~~~~~~~~~~~~~~~~~~ +* _`CWCache`, cache entities used to improve performances +* _`CWProperty`, used to configure the instance + +* _`EmailAddress`, email address, used by the system to send notifications + to the users and also used by others optionnals schemas + +* _`Bookmark`, an entity type used to allow a user to customize his links within + the instance + +* _`ExternalUri`, used for semantic web site to indicate that an entity is the + same as another from an external site diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devrepo/datamodel/define-workflows.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devrepo/datamodel/define-workflows.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,161 @@ +.. -*- coding: utf-8 -*- + +.. _Workflow: + +Defining a Workflow +=================== + +General +------- + +A workflow describes how certain entities have to evolve between +different states. Hence we have a set of states, and a "transition +graph", i.e. a set of possible transitions from one state to another +state. + +We will define a simple workflow for a blog, with only the following +two states: `submitted` and `published`. So first, we create a simple +|cubicweb| instance in five minutes (see :ref:`BlogFiveMinutes`). + +Setting up a workflow +--------------------- + +We want to create a workflow to control the quality of the BlogEntry +submitted on the instance. When a BlogEntry is created by a user +its state should be `submitted`. To be visible to all, it has to +be in the state `published`. To move it from `submitted` to `published`, +we need a transition that we can call `approve_blogentry`. + +A BlogEntry state should not be modifiable by every user. +So we have to define a group of users, `moderators`, and +this group will have appropriate permissions to publish a BlogEntry. + +There are two ways to create a workflow: from the user interface, or +by defining it in ``migration/postcreate.py``. This script is executed +each time a new ``cubicweb-ctl db-init`` is done. We strongly +recommend to create the workflow in ``migration/postcreate.py`` and we +will now show you how. Read `Two bits of warning`_ to understand why. + +The state of an entity is managed by the `in_state` attribute which +can be added to your entity schema by inheriting from +`cubicweb.schema.WorkflowableEntityType`. + + +About our example of BlogEntry, we must have: + +.. sourcecode:: python + + from cubicweb.schema import WorkflowableEntityType + + class BlogEntry(WorkflowableEntityType): + ... + + +Creating states, transitions and group permissions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :mod:`postcreate` script is executed in a special environment, +adding several |cubicweb| primitives that can be used. + +They are all defined in the :class:`ServerMigrationHelper` class. +We will only discuss the methods we use to create a workflow in this example. + +A workflow is a collection of entities of type ``State`` and of type +``Transition`` which are standard *CubicWeb* entity types. + +To define a workflow for BlogDemo, please add the following lines +to ``migration/postcreate.py``: + +.. sourcecode:: python + + _ = unicode + + moderators = add_entity('CWGroup', name=u"moderators") + +This adds the `moderators` user group. + +.. sourcecode:: python + + wf = add_workflow(u'blog publication workflow', 'BlogEntry') + +At first, instanciate a new workflow object with a gentle description +and the concerned entity types (this one can be a tuple for multiple +value). + +.. sourcecode:: python + + submitted = wf.add_state(_('submitted'), initial=True) + published = wf.add_state(_('published')) + +This will create two entities of type ``State``, one with name +'submitted', and the other with name 'published'. + +``add_state`` expects as first argument the name of the state you want +to create and an optional argument to say if it is supposed to be the +initial state of the entity type. + +.. sourcecode:: python + + wf.add_transition(_('approve_blogentry'), (submitted,), published, ('moderators', 'managers'),) + +This will create an entity of type ``Transition`` with name +`approve_blogentry` which will be linked to the ``State`` entities +created before. + +``add_transition`` expects + + * as the first argument: the name of the transition + * then the list of states on which the transition can be triggered, + * the target state of the transition, + * and the permissions + (e.g. a list of user groups who can apply the transition; the user + has to belong to at least one of the listed group to perform the action). + +.. sourcecode:: python + + checkpoint() + +.. note:: + Do not forget to add the `_()` in front of all states and + transitions names while creating a workflow so that they will be + identified by the i18n catalog scripts. + +In addition to the user groups (one of which the user needs to belong +to), we could have added a RQL condition. In this case, the user can +only perform the action if the two conditions are satisfied. + +If we use an RQL condition on a transition, we can use the following variables: + +* `X`, the entity on which we may pass the transition +* `U`, the user executing that may pass the transition + + +.. image:: ../../images/03-transitions-view_en.png + +You can notice that in the action box of a BlogEntry, the state is now +listed as well as the possible transitions for the current state +defined by the workflow. + +The transitions will only be displayed for users having the right permissions. +In our example, the transition `approve_blogentry` will only be displayed +for the users belonging to the group `moderators` or `managers`. + + +Two bits of warning +~~~~~~~~~~~~~~~~~~~ + +We could perfectly use the administration interface to do these +operations. It is a convenient thing to do at times (when doing +development, to quick-check things). But it is not recommended beyond +that because it is a bit complicated to do it right and it will be +only local to your instance (or, said a bit differently, such a +workflow only exists in an instance database). Furthermore, you cannot +write unit tests against deployed instances, and experience shows it +is mandatory to have tests for any mildly complicated workflow +setup. + +Indeed, if you create the states and transitions through the user +interface, next time you initialize the database you will have to +re-create all the workflow entities. The user interface should only be +a reference for you to view the states and transitions, but is not the +appropriate interface to define your application workflow. diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devrepo/datamodel/definition.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devrepo/datamodel/definition.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,631 @@ + .. -*- coding: utf-8 -*- + +Yams *schema* +------------- + +The **schema** is the core piece of a *CubicWeb* instance as it +defines and handles the data model. It is based on entity types that +are either already defined in `Yams`_ and the *CubicWeb* standard +library; or more specific types defined in cubes. The schema for a +cube is defined in a `schema` python module or package. + +.. _`Yams`: http://www.logilab.org/project/yams + +Overview +~~~~~~~~ + +The core idea of the yams schema is not far from the classical +`Entity-relationship`_ model. But while an E/R model (or `logical +model`) traditionally has to be manually translated to a lower-level +data description language (such as the SQL `create table` +sublanguage), also often described as the `physical model`, no such +step is required with |yams| and |cubicweb|. + +.. _`Entity-relationship`: http://en.wikipedia.org/wiki/Entity-relationship_model + +This is because in addition to high-level, logical |yams| models, one +uses the |rql| data manipulation language to query, insert, update and +delete data. |rql| abstracts as much of the underlying SQL database as +a |yams| schema abstracts from the physical layout. The vagaries of +SQL are avoided. + +As a bonus point, such abstraction make it quite comfortable to build +or use different backends to which |rql| queries apply. + +So, as in the E/R formalism, the building blocks are ``entities`` +(:ref:`EntityType`), ``relationships`` (:ref:`RelationType`, +:ref:`RelationDefinition`) and ``attributes`` (handled like relation +with |yams|). + +Let us detail a little the divergences between E/R and |yams|: + +* all relationship are binary which means that to represent a + non-binary relationship, one has to use an entity, +* relationships do not support attributes (yet, see: + http://www.cubicweb.org/ticket/341318), hence the need to reify it + as an entity if need arises, +* all entities have an `eid` attribute (an integer) that is its + primary key (but it is possible to declare uniqueness on other + attributes) + +Also |yams| supports the notions of: + +* entity inheritance (quite experimental yet, and completely + undocumented), +* relation type: that is, relationships can be established over a set + of couple of entity types (henre the distinction made between + `RelationType` and `RelationDefinition` below) + +Finally |yams| has a few concepts of its own: + +* relationships being oriented and binary, we call the left hand + entity type the `subject` and the right hand entity type the + `object` + +.. note:: + + The |yams| schema is available at run time through the .schema + attribute of the `vregistry`. It's an instance of + :class:`cubicweb.schema.Schema`, which extends + :class:`yams.schema.Schema`. + +.. _EntityType: + +Entity type +~~~~~~~~~~~ + +An entity type is an instance of :class:`yams.schema.EntitySchema`. Each entity type has +a set of attributes and relations, and some permissions which define who can add, read, +update or delete entities of this type. + +The following built-in types are available: ``String``, ``Int``, +``Float``, ``Decimal``, ``Boolean``, ``Date``, ``Datetime``, ``Time``, +``Interval``, ``Byte`` and ``Password``. They can only be used as +attributes of an other entity type. + +You can find more base entity types in +:ref:`pre_defined_entity_types`. + +.. XXX yams inheritance + +.. _RelationType: + +Relation type +~~~~~~~~~~~~~ + +A relation type is an instance of +:class:`yams.schema.RelationSchema`. A relation type is simply a +semantic definition of a kind of relationship that may occur in an +application. + +It may be referenced by zero, one or more relation definitions. + +It is important to choose a good name, at least to avoid conflicts +with some semantically different relation defined in other cubes +(since there's only a shared name space for these names). + +A relation type holds the following properties (which are hence shared +between all relation definitions of that type): + +* `inlined`: boolean handling the physical optimization for archiving + the relation in the subject entity table, instead of creating a specific + table for the relation. This applies to relations where cardinality + of subject->relation->object is 0..1 (`?`) or 1..1 (`1`) for *all* its relation + definitions. + +* `symmetric`: boolean indicating that the relation is symmetrical, which + means that `X relation Y` implies `Y relation X`. + +.. _RelationDefinition: + +Relation definition +~~~~~~~~~~~~~~~~~~~ + +A relation definition is an instance of +:class:`yams.schema.RelationDefinition`. It is a complete triplet +"

') + for field in fields: + if field.name == 'mailbody': + w(u'

') + w(u'') + w(u'

') + w(field.render(form, self)) + w(u'

') + else: + w(u'') + w(u'%s' % self.render_label(form, field)) + w(u'') + w(field.render(form, self)) + w(u'') + + def render_buttons(self, w, form): + pass + +We simply override the `_render_fields` and `render_buttons` method of the base form renderer +to arrange fields as we desire it: here we'll have first a two columns table with label and +value of the sender, recipients and subject field (form order respected), then form controls, +then a div containing the textarea for the email's content. + +To bind this renderer to our form, we should add to our form definition above: + +.. sourcecode:: python + + form_renderer_id = 'massmailing' + + +.. Example of entity fields form diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/httpcaching.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/httpcaching.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,3 @@ +HTTP cache management +--------------------- +XXX feedme \ No newline at end of file diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/index.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/index.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,21 @@ +Web side development +==================== + +In this chapter, we will describe the core APIs for web development in +the *CubicWeb* framework. + +.. toctree:: + :maxdepth: 2 + + publisher + controllers + request + views/index + rtags + js + css + form + facets + internationalization +.. property + httpcaching diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/internationalization.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/internationalization.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,222 @@ +.. -*- coding: utf-8 -*- + +.. _internationalization: + +Internationalization +--------------------- + +Cubicweb fully supports the internalization of its content and interface. + +Cubicweb's interface internationalization is based on the translation project `GNU gettext`_. + +.. _`GNU gettext`: http://www.gnu.org/software/gettext/ + +Cubicweb' internalization involves two steps: + +* in your Python code and cubicweb-tal templates : mark translatable strings + +* in your instance : handle the translation catalog, edit translations + +String internationalization +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +User defined string +``````````````````` + +In the Python code and cubicweb-tal templates translatable strings can be +marked in one of the following ways : + + * by using the *built-in* function `_` :: + + class PrimaryView(EntityView): + """the full view of an non final entity""" + __regid__ = 'primary' + title = _('primary') + + OR + + * by using the equivalent request's method :: + + class NoResultView(View): + """default view when no result has been found""" + __regid__ = 'noresult' + + def call(self, **kwargs): + self.w(u'

\n' + % self._cw._('No result matching query')) + +The goal of the *built-in* function `_` is only **to mark the +translatable strings**, it will only return the string to translate +itself, but not its translation (it's actually another name for the +`unicode` builtin). + +In the other hand the request's method `self._cw._` is also meant to +retrieve the proper translation of translation strings in the +requested language. + +Finally you can also use the `__` attribute of request object to get a +translation for a string *which should not itself added to the catalog*, +usually in case where the actual msgid is created by string interpolation :: + + self._cw.__('This %s' % etype) + +In this example ._cw.__` is used instead of ._cw._` so we don't have 'This %s' in +messages catalogs. + +Translations in cubicweb-tal template can also be done with TAL tags +`i18n:content` and `i18n:replace`. + +If you need to add messages on top of those that can be found in the source, +you can create a file named `i18n/static-messages.pot`. + +You could put there messages not found in the python sources or +overrides for some messages of used cubes. + +Generated string +```````````````` + +We do not need to mark the translation strings of entities/relations used by a +particular instance's schema as they are generated automatically. String for +various actions are also generated. + +For exemple the following schema :: + + Class EntityA(EntityType): + relation_a2b = SubjectRelation('EntityB') + + class EntityB(EntityType): + pass + +May generate the following message :: + + add EntityA relation_a2b EntityB subject + +This message will be used in views of ``EntityA`` for creation of a new +``EntityB`` with a preset relation ``relation_a2b`` between the current +``EntityA`` and the new ``EntityB``. The opposite message :: + + add EntityA relation_a2b EntityB object + +Is used for similar creation of an ``EntityA`` from a view of ``EntityB``. The +title of they respective creation form will be :: + + creating EntityB (EntityA %(linkto)s relation_a2b EntityB) + + creating EntityA (EntityA relation_a2b %(linkto)s EntityA) + +In the translated string you can use ``%(linkto)s`` for reference to the source +``entity``. + +Handling the translation catalog +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once the internationalization is done in your code, you need to populate and +update the translation catalog. Cubicweb provides the following commands for this +purpose: + + +* `i18ncubicweb` updates Cubicweb framework's translation + catalogs. Unless you actually work on the framework itself, you + don't need to use this command. + +* `i18ncube` updates the translation catalogs of *one particular cube* + (or of all cubes). After this command is executed you must update + the translation files *.po* in the "i18n" directory of your + cube. This command will of course not remove existing translations + still in use. It will mark unused translation but not remove them. + +* `i18ninstance` recompiles the translation catalogs of *one particular + instance* (or of all instances) after the translation catalogs of + its cubes have been updated. This command is automatically + called every time you create or update your instance. The compiled + catalogs (*.mo*) are stored in the i18n//LC_MESSAGES of + instance where `lang` is the language identifier ('en' or 'fr' + for exemple). + + +Example +``````` + +You have added and/or modified some translation strings in your cube +(after creating a new view or modifying the cube's schema for exemple). +To update the translation catalogs you need to do: + +1. `cubicweb-ctl i18ncube ` +2. Edit the /i18n/xxx.po files and add missing translations (empty `msgstr`) +3. `hg ci -m "updated i18n catalogs"` +4. `cubicweb-ctl i18ninstance ` + +Editing po files +~~~~~~~~~~~~~~~~ + +Using a PO aware editor +```````````````````````` + +Many tools exist to help maintain .po (PO) files. Common editors or +development environment provides modes for these. One can also find +dedicated PO files editor, such as `poedit`_. + +.. _`poedit`: http://www.poedit.net/ + +While usage of such a tool is commendable, PO files are perfectly +editable with a (unicode aware) plain text editor. It is also useful +to know their structure for troubleshooting purposes. + +Structure of a PO file +`````````````````````` + +In this section, we selectively quote passages of the `GNU gettext`_ +manual chapter on PO files, available there:: + + http://www.gnu.org/software/hello/manual/gettext/PO-Files.html + +One PO file entry has the following schematic structure:: + + white-space + # translator-comments + #. extracted-comments + #: reference... + #, flag... + #| msgid previous-untranslated-string + msgid untranslated-string + msgstr translated-string + + +A simple entry can look like this:: + + #: lib/error.c:116 + msgid "Unknown system error" + msgstr "Error desconegut del sistema" + +It is also possible to have entries with a context specifier. They +look like this:: + + white-space + # translator-comments + #. extracted-comments + #: reference... + #, flag... + #| msgctxt previous-context + #| msgid previous-untranslated-string + msgctxt context + msgid untranslated-string + msgstr translated-string + + +The context serves to disambiguate messages with the same +untranslated-string. It is possible to have several entries with the +same untranslated-string in a PO file, provided that they each have a +different context. Note that an empty context string and an absent +msgctxt line do not mean the same thing. + +Contexts and CubicWeb +````````````````````` + +CubicWeb PO files have both non-contextual and contextual msgids. + +Contextual entries are automatically used in some cases. For instance, +entity.dc_type(), eschema.display_name(req) or display_name(etype, +req, form, context) methods/function calls will use them. + +It is also possible to explicitly use the with _cw.pgettext(context, +msgid). diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/js.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/js.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,355 @@ +.. -*- coding: utf-8 -*- + +Javascript +---------- + +*CubicWeb* uses quite a bit of javascript in its user interface and +ships with jquery (1.3.x) and parts of the jquery UI library, plus a +number of homegrown files and also other third party libraries. + +All javascript files are stored in cubicweb/web/data/. There are +around thirty js files there. In a cube it goes to data/. + +Obviously one does not want javascript pieces to be loaded all at +once, hence the framework provides a number of mechanisms and +conventions to deal with javascript resources. + +Conventions +~~~~~~~~~~~ + +It is good practice to name cube specific js files after the name of +the cube, like this : 'cube.mycube.js', so as to avoid name clashes. + +.. XXX external_resources variable (which needs love) + +CubicWeb javascript API +~~~~~~~~~~~~~~~~~~~~~~~ + +Javascript resources are typically loaded on demand, from views. The +request object (available as self._cw from most application objects, +for instance views and entities objects) has a few methods to do that: + +* `add_js(self, jsfiles, localfile=True)` which takes a sequence of + javascript files and writes proper entries into the HTML header + section. The localfile parameter allows to declare resources which + are not from web/data (for instance, residing on a content delivery + network). + +* `add_onload(self, jscode)` which adds one raw javascript code + snippet inline in the html headers. This is quite useful for setting + up early jQuery(document).ready(...) initialisations. + +CubicWeb javascript events +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* ``server-response``: this event is triggered on HTTP responses (both + standard and ajax). The two following extra parameters are passed + to callbacks : + + - ``ajax``: a boolean that says if the reponse was issued by an + ajax request + + - ``node``: the DOM node returned by the server in case of an + ajax request, otherwise the document itself for standard HTTP + requests. + +Important AJAX APIS +~~~~~~~~~~~~~~~~~~~ + +* `asyncRemoteExec` and `remoteExec` are the base building blocks for + doing arbitrary async (resp. sync) communications with the server + +* `reloadComponent` is a convenience function to replace a DOM node + with server supplied content coming from a specific registry (this + is quite handy to refresh the content of some boxes for instances) + +* `jQuery.fn.loadxhtml` is an important extension to jQuery which + allows proper loading and in-place DOM update of xhtml views. It is + suitably augmented to trigger necessary events, and process CubicWeb + specific elements such as the facet system, fckeditor, etc. + + +A simple example with asyncRemoteExec +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the python side, we have to extend the BaseController class. The +@jsonize decorator ensures that the `return value` of the method is +encoded as JSON data. By construction, the JSonController inputs +everything in JSON format. + +.. sourcecode: python + + from cubicweb.web.views.basecontrollers import JSonController, jsonize + + @monkeypatch(JSonController) + @jsonize + def js_say_hello(self, name): + return u'hello %s' % name + +In the javascript side, we do the asynchronous call. Notice how it +creates a `deferred` object. Proper treatment of the return value or +error handling has to be done through the addCallback and addErrback +methods. + +.. sourcecode: javascript + + function asyncHello(name) { + var deferred = asyncRemoteExec('say_hello', name); + deferred.addCallback(function (response) { + alert(response); + }); + deferred.addErrback(function (error) { + alert('something fishy happened'); + }); + } + + function syncHello(name) { + alert( remoteExec('say_hello', name) ); + } + +Anatomy of a reloadComponent call +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`reloadComponent` allows to dynamically replace some DOM node with new +elements. It has the following signature: + +* `compid` (mandatory) is the name of the component to be reloaded + +* `rql` (optional) will be used to generate a result set given as + argument to the selected component + +* `registry` (optional) defaults to 'components' but can be any other + valid registry name + +* `nodeid` (optional) defaults to compid + 'Component' but can be any + explicitly specified DOM node id + +* `extraargs` (optional) should be a dictionary of values that will be + given to the cell_call method of the component + +A simple reloadComponent example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The server side implementation of `reloadComponent` is the +js_component method of the JSonController. + +The following function implements a two-steps method to delete a +standard bookmark and refresh the UI, while keeping the UI responsive. + +.. sourcecode:: javascript + + function removeBookmark(beid) { + d = asyncRemoteExec('delete_bookmark', beid); + d.addCallback(function(boxcontent) { + reloadComponent('bookmarks_box', '', 'boxes', 'bookmarks_box'); + document.location.hash = '#header'; + updateMessage(_("bookmark has been removed")); + }); + } + +`reloadComponent` is called with the id of the bookmark box as +argument, no rql expression (because the bookmarks display is actually +independant of any dataset context), a reference to the 'boxes' +registry (which hosts all left, right and contextual boxes) and +finally an explicit 'bookmarks_box' nodeid argument that stipulates +the target DOM node. + +Anatomy of a loadxhtml call +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`jQuery.fn.loadxhtml` is an important extension to jQuery which allows +proper loading and in-place DOM update of xhtml views. The existing +`jQuery.load`_ function does not handle xhtml, hence the addition. The +API of loadxhtml is roughly similar to that of `jQuery.load`_. + +.. _`jQuery.load`: http://api.jquery.com/load/ + + +* `url` (mandatory) should be a complete url (typically referencing + the JSonController, but this is not strictly mandatory) + +* `data` (optional) is a dictionary of values given to the + controller specified through an `url` argument; some keys may have a + special meaning depending on the choosen controller (such as `fname` + for the JSonController); the `callback` key, if present, must refer + to a function to be called at the end of loadxhtml (more on this + below) + +* `reqtype` (optional) specifies the request method to be used (get or + post); if the argument is 'post', then the post method is used, + otherwise the get method is used + +* `mode` (optional) is one of `replace` (the default) which means the + loaded node will replace the current node content, `swap` to replace + the current node with the loaded node, and `append` which will + append the loaded node to the current node content + +About the `callback` option: + +* it is called with two parameters: the current node, and a list + containing the loaded (and post-processed node) + +* whenever is returns another function, this function is called in + turn with the same parameters as above + +This mechanism allows callback chaining. + + +A simple example with loadxhtml +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Here we are concerned with the retrieval of a specific view to be +injected in the live DOM. The view will be of course selected +server-side using an entity eid provided by the client side. + +.. sourcecode:: python + + from cubicweb import typed_eid + from cubicweb.web.views.basecontrollers import JSonController, xhtmlize + + @monkeypatch(JSonController) + @xhtmlize + def js_frob_status(self, eid, frobname): + entity = self._cw.entity_from_eid(typed_eid(eid)) + return entity.view('frob', name=frobname) + +.. sourcecode:: javascript + + function update_some_div(divid, eid, frobname) { + var params = {fname:'frob_status', eid: eid, frobname:frobname}; + jQuery('#'+divid).loadxhtml(JSON_BASE_URL, params, 'post'); + } + +In this example, the url argument is the base json url of a cube +instance (it should contain something like +`http://myinstance/json?`). The actual JSonController method name is +encoded in the `params` dictionary using the `fname` key. + +A more real-life example from CubicWeb +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A frequent use case of Web 2 applications is the delayed (or +on-demand) loading of pieces of the DOM. This is typically achieved +using some preparation of the initial DOM nodes, jQuery event handling +and proper use of loadxhtml. + +We present here a skeletal version of the mecanism used in CubicWeb +and available in web/views/tabs.py, in the `LazyViewMixin` class. + +.. sourcecode:: python + + def lazyview(self, vid, rql=None): + """ a lazy version of wview """ + w = self.w + self._cw.add_js('cubicweb.lazy.js') + urlparams = {'vid' : vid, 'fname' : 'view'} + if rql is not None: + urlparams['rql'] = rql + w(u'

' % ( + vid, xml_escape(self._cw.build_url('json', **urlparams)))) + w(u'

') + self._cw.add_onload(u""" + jQuery('#lazy-%(vid)s').bind('%(event)s', function() { + load_now('#lazy-%(vid)s');});""" + % {'event': 'load_%s' % vid, 'vid': vid}) + +This creates a `div` with a specific event associated to it. + +The full version deals with: + +* optional parameters such as an entity eid, an rset + +* the ability to further reload the fragment + +* the ability to display a spinning wheel while the fragment is still + not loaded + +* handling of browsers that do not support ajax (search engines, + text-based browsers such as lynx, etc.) + +The javascript side is quite simple, due to loadxhtml awesomeness. + +.. sourcecode:: javascript + + function load_now(eltsel) { + var lazydiv = jQuery(eltsel); + lazydiv.loadxhtml(lazydiv.attr('cubicweb:loadurl')); + } + +This is all significantly different of the previous `simple example` +(albeit this example actually comes from real-life code). + +Notice how the `cubicweb:loadurl` is used to convey the url +information. The base of this url is similar to the global javascript +JSON_BASE_URL. According to the pattern described earlier, +the `fname` parameter refers to the standard `js_view` method of the +JSonController. This method renders an arbitrary view provided a view +id (or `vid`) is provided, and most likely an rql expression yielding +a result set against which a proper view instance will be selected. + +The `cubicweb:loadurl` is one of the 29 attributes extensions to XHTML +in a specific cubicweb namespace. It is a means to pass information +without breaking HTML nor XHTML compliance and without resorting to +ungodly hacks. + +Given all this, it is easy to add a small nevertheless useful feature +to force the loading of a lazy view (for instance, a very +computation-intensive web page could be scinded into one fast-loading +part and a delayed part). + +On the server side, a simple call to a javascript function is +sufficient. + +.. sourcecode:: python + + def forceview(self, vid): + """trigger an event that will force immediate loading of the view + on dom readyness + """ + self._cw.add_onload("trigger_load('%s');" % vid) + +The browser-side definition follows. + +.. sourcecode:: javascript + + function trigger_load(divid) { + jQuery('#lazy-' + divd).trigger('load_' + divid); + } + + + + +.. XXX reloadComponent +.. XXX userCallback / user_callback + +Javascript library: overview +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* jquery.* : jquery and jquery UI library + +* cubicweb.ajax.js : concentrates all ajax related facilities (it + extends jQuery with the loahxhtml function, provides a handfull of + high-level ajaxy operations like asyncRemoteExec, reloadComponent, + replacePageChunk, getDomFromResponse) + +* cubicweb.python.js : adds a number of practical extension to stdanrd + javascript objects (on Date, Array, String, some list and dictionary + operations), and a pythonesque way to build classes. Defines a + CubicWeb namespace. + +* cubicweb.htmlhelpers.js : a small bag of convenience functions used + in various other cubicweb javascript resources (baseuri, progress + cursor handling, popup login box, html2dom function, etc.) + +* cubicweb.widgets.js : provides a widget namespace and constructors + and helpers for various widgets (mainly facets and timeline) + +* cubicweb.edition.js : used by edition forms + +* cubicweb.preferences.js : used by the preference form + +* cubicweb.facets.js : used by the facets mechanism + +There is also javascript support for massmailing, gmap (google maps), +fckcwconfig (fck editor), timeline, calendar, goa (CubicWeb over +AppEngine), flot (charts drawing), tabs and bookmarks. diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/property.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/property.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,13 @@ +The property mecanism +--------------------- + +.. XXX CWProperty and co + + +Property API +~~~~~~~~~~~~ +.. XXX feed me + +Registering and using your own property +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. XXX feed me diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/publisher.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/publisher.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,65 @@ +.. _publisher: + +Publisher +--------- + +What happens when an HTTP request is issued ? + +The story begins with the ``CubicWebPublisher.main_publish`` +method. We do not get upper in the bootstrap process because it is +dependant on the used HTTP library. With `twisted`_ however, +``cubicweb.etwist.server.CubicWebRootResource.render_request`` is the +real entry point. + +.. _`twisted`: http://twistedmatrix.com/trac/ + +What main_publish does: + +* get a controller id and a result set from the path (this is actually + delegated to the `urlpublisher` component) + +* the controller is then selected (if not, this is considered an + authorization failure and signaled as such) and called + +* then either a proper result is returned, in which case the + request/connection object issues a ``commit`` and returns the result + +* or error handling must happen: + + * ``ValidationErrors`` pop up there and may lead to a redirect to a + previously arranged url or standard error handling applies + * an HTTP 500 error (`Internal Server Error`) is issued + + +Now, let's turn to the controller. There are many of them in +:mod:`cubicweb.web.views.basecontrollers`. We can just follow the +default `view` controller that is selected on a `view` path. See the +:ref:`controllers` chapter for more information on controllers. + +The `View` controller's entry point is the `publish` method. It does +the following: + +* compute the `main` view to be applied, using either the given result + set or building one from a user provided rql string (`rql` and `vid` + can be forced from the url GET parameters), that is: + + * compute the `vid` using the result set and the schema (see + `cubicweb.web.views.vid_from_rset`) + * handle all error cases that could happen in this phase + +* do some cache management chores + +* select a main template (typically `TheMainTemplate`, see chapter + :ref:`templates`) + +* call it with the result set and the computed view. + +What happens next actually depends on the template and the view, but +in general this is the rendering phase. + + +CubicWebPublisher API +````````````````````` + +.. autoclass:: cubicweb.web.application.CubicWebPublisher + :members: diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/request.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/request.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,79 @@ +The `Request` class (`cubicweb.web`) +------------------------------------ + +Overview +```````` + +A request instance is created when an HTTP request is sent to the web server. +It contains informations such as form parameters, user authenticated, etc. + +**Globally, a request represents a user query, either through HTTP or not +(we also talk about RQL queries on the server side for example).** + +An instance of `Request` has the following attributes: + +* `user`, instance of `cubicweb.common.utils.User` corresponding to the authenticated + user +* `form`, dictionary containing the values of a web form +* `encoding`, character encoding to use in the response + +But also: + +* `Session data handling` + + * `session_data()`, returns a dictionary containing all the session data + * `get_session_data(key, default=None)`, returns a value associated to the given + key or the value `default` if the key is not defined + * `set_session_data(key, value)`, assign a value to a key + * `del_session_data(key)`, suppress the value associated to a key + +* `Cookies handling` + + * `get_cookie()`, returns a dictionary containing the value of the header + HTTP 'Cookie' + * `set_cookie(cookie, key, maxage=300)`, adds a header HTTP `Set-Cookie`, + with a minimal 5 minutes length of duration by default (`maxage` = None + returns a *session* cookie which will expire when the user closes the browser + window) + * `remove_cookie(cookie, key)`, forces a value to expire + +* `URL handling` + + * `url()`, returns the full URL of the HTTP request + * `base_url()`, returns the root URL of the web application + * `relative_path()`, returns the relative path of the request + +* `And more...` + + * `set_content_type(content_type, filename=None)`, adds the header HTTP + 'Content-Type' + * `get_header(header)`, returns the value associated to an arbitrary header + of the HTTP request + * `set_header(header, value)`, adds an arbitrary header in the response + * `cursor()` returns a RQL cursor on the session + * `execute(*args, **kwargs)`, shortcut to ``.cursor().execute()`` + * `property_value(key)`, properties management (`CWProperty`) + * dictionary `data` to store data to share informations between components + *while a request is executed* + +Please note that this class is abstract and that a concrete implementation +will be provided by the *frontend* web used (in particular *twisted* as of +today). For the views or others that are executed on the server side, +most of the interface of `Request` is defined in the session associated +to the client. + +API +``` + +The elements we gave in overview for above are built in three layers, +from ``cubicweb.req.RequestSessionBase``, ``cubicweb.dbapi.DBAPIRequest`` and +``cubicweb.web.CubicWebRequestBase``. + +.. autoclass:: cubicweb.req.RequestSessionBase + :members: + +.. autoclass:: cubicweb.dbapi.DBAPIRequest + :members: + +.. autoclass:: cubicweb.web.request.CubicWebRequestBase + :members: diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/rtags.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/rtags.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,21 @@ +Configuring the user interface +------------------------------ + +.. _relation_tags: + +Relation tags +~~~~~~~~~~~~~ +.. automodule:: cubicweb.rtags + +.. _uicfg: + +The ``uicfg`` module +~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + The part of uicfg that deals with primary views is in the + :ref:`primary_view_configuration` chapter. + +.. automodule:: cubicweb.web.uicfg + diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/views/basetemplates.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/views/basetemplates.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,115 @@ +.. -*- coding: utf-8 -*- + +.. |cubicweb| replace:: *CubicWeb* + +.. _templates: + +Templates +========= + +Templates are the entry point for the |cubicweb| view system. As seen +in :ref:`views_base_class`, there are two kinds of views: the +templatable and non-templatable. + +Non-templatable views are standalone. They are responsible for all the +details such as setting a proper content type (or mime type), the +proper document headers, namespaces, etc. Examples are pure xml views +such as RSS or Semantic Web views (`SIOC`_, `DOAP`_, `FOAF`_, `Linked +Data`_, etc.). + +.. _`SIOC`: http://sioc-project.org/ +.. _`DOAP`: http://trac.usefulinc.com/doap +.. _`FOAF`: http://www.foaf-project.org/ +.. _`Linked Data`: http://linkeddata.org/ + +Templatable views are not concerned with such pesky details. They +leave it to the template. Conversely, the template's main job is to: + +* set up the proper document header and content type +* define the general layout of a document +* invoke adequate views in the various sections of the document + + +Look at :mod:`cubicweb.web.views.basetemplates` and you will find the +base templates used to generate (X)HTML for your application. The most +important template there is `TheMainTemplate`. + +.. _the_main_template_layout: + +TheMainTemplate +--------------- + +.. _the_main_template_sections: + +Layout and sections +``````````````````` + +A page is composed as indicated on the schema below : + +.. image:: ../../images/main_template.png + +The sections dispatches specific views: + +* `header`: the rendering of the header is delegated to the + `htmlheader` view, whose default implementation can be found in + ``basetemplates.py`` and which does the following things: + + * inject the favicon if there is one + * inject the global style sheets and javascript resources + * call and display a link to an rss component if there is one available + + it also sets up the page title, and fills the actual + `header` section with top-level components, using the `header` view, which: + + * tries to display a logo, the name of the application and the `breadcrumbs` + * provides a login status area + * provides a login box (hiden by default) + +* `left column`: this is filled with all selectable boxes matching the + `left` context (there is also a right column but nowadays it is + seldom used due to bad usability) + +* `contentcol`: this is the central column; it is filled with: + + * the `rqlinput` view (hidden by default) + * the `applmessages` component + * the `contentheader` view which in turns dispatches all available + content navigation components having the `navtop` context (this + is used to navigate through entities implementing the IPrevNext + interface) + * the view that was given as input to the template's `call` + method, also dealing with pagination concerns + * the `contentfooter` + +* `footer`: adds all footer actions + +.. note:: + + How and why a view object is given to the main template is explained + in the :ref:`publisher` chapter. + +Class attributes +```````````````` + +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 dictionary of the forms parameters, before going the classic way (through + step 1 and 2 described juste above) + +Other templates +--------------- + +Other standard templates include: + +* `login` and `logout` + +* `error-template` specializes TheMainTemplate to do proper end-user + output if an error occurs during the computation of TheMainTemplate + (it is a fallback view). diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/views/baseviews.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/views/baseviews.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,84 @@ +.. -*- coding: utf-8 -*- + +Base 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: + +HTML views +~~~~~~~~~~ + +Special views +````````````` + +*noresult* + This view is the default view used when no result has been found + (e.g. empty result set). + +*final* + 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. + +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 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 produces the result of `text` + in a link leading to the primary view of the entity. + +List +````` + +*list* + This view displays a list of entities by creating a HTML list (`

`) + and call the view `sameetypelistitem` for each entity of the result set. + +*sameetypelistitem* + This view redirects by default to the `listitem` view. + +*csv* + This view applies to entity groups, which are individually + displayed using the `incontext` view. It displays each entity as a + coma separated list. It is NOT related to the well-known text file + format. + +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 + `navigation.short-line-size` property if necessary. + +*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. diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/views/boxes.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/views/boxes.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,36 @@ +Boxes +----- + +(:mod:`cubicweb.web.views.boxes`) + +*sidebox* + This view displays usually a side box of some related entities + in a primary view. + +The action box +~~~~~~~~~~~~~~~ + +The ``add_related`` is an automatic menu in the action box that allows to create +an entity automatically related to the initial entity (context in +which the box is displayed). By default, the links generated in this +box are computed from the schema properties of the displayed entity, +but it is possible to explicitly specify them thanks to the +`cubicweb.web.uicfg.rmode` *relation tag*: + +* `link`, indicates that a relation is in general created pointing + to an existing entity and that we should not to display a link + for this relation + +* `create`, indicates that a relation is in general created pointing + to new entities and that we should display a link to create a new + entity and link to it automatically + + +If necessary, it is possible to overwrite the method +`relation_mode(rtype, targettype, x='subject')` to dynamically +compute a relation creation category. + +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 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/views/breadcrumbs.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/views/breadcrumbs.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,58 @@ +Breadcrumbs +----------- + +Breadcrumbs are a navigation component to help the user locate himself +along a path of entities. + +Display +~~~~~~~ + +Breadcrumbs are displayed by default in the header section (see +:ref:`the_main_template_sections`). With the default main +template, the header section is composed by the logo, the application +name, breadcrumbs and, at the most right, the login box. Breadcrumbs +are displayed just next to the application name, thus breadcrumbs +begin with a separator. + +Here is the header section of the CubicWeb's forge: + +.. image:: ../../images/breadcrumbs_header.png + +There are three breadcrumbs components defined in +:mod:`cubicweb.web.views.ibreadcrumbs`: + +- `BreadCrumbEntityVComponent`: displayed for a result set with one line + if the entity implements the ``IBreadCrumbs`` interface. +- `BreadCrumbETypeVComponent`: displayed for a result set with more than + one line, but with all entities of the same type which implement the + ``IBreadCrumbs`` interface. +- `BreadCrumbAnyRSetVComponent`: displayed for any other result set. + +Building breadcrumbs +~~~~~~~~~~~~~~~~~~~~ + +The ``IBreadCrumbs`` interface is defined in the +:mod:`cubicweb.interfaces` module. It specifies that an entity which +implements this interface must have a ``breadcrumbs`` method. + +.. note:: + + Redefining the breadcrumbs is the hammer way to do it. Another way + is to define the `parent` method on an entity (as defined in the + `ITree` interface). If available, it will be used to compute + breadcrumbs. + +Here is the API of the ``breadcrumbs`` method: + +.. automethod:: cubicweb.interfaces.IBreadCrumbs.breadcrumbs + +If the breadcrumbs method return a list of entities, the +``cubicweb.web.views.ibreadcrumbs.BreadCrumbView`` is used to display +the elements. + +By default, for any entity, if recurs=True, breadcrumbs method returns +a list of entities, else a list of a simple string. + +In order to see a hierarchical breadcrumbs, entities must have a +``parent`` method which returns the parent entity. By default this +method doesn't exist on entity, given that it can not be guessed. diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/views/editforms.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/views/editforms.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,6 @@ +Standard forms +-------------- + + (:mod:`cubicweb.web.views.editforms`) + +XXX feed me diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/views/embedding.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/views/embedding.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,9 @@ +.. -*- coding: utf-8 -*- + +Embedding external pages +------------------------ + +(:mod:`cubicweb.web.views.embedding`) + +including external content + diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/views/idownloadable.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/views/idownloadable.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,5 @@ +The 'download' view +------------------- + +(:mod:`cubicweb.web.views.idownloadable`) + diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/views/index.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/views/index.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,30 @@ +The View system +=============== + +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|. + + +.. toctree:: + :maxdepth: 3 + + views + basetemplates + primary + baseviews + startup + boxes + table + xmlrss +.. editforms + +.. toctree:: + :maxdepth: 3 + + urlpublish + breadcrumbs +.. wdoc +.. embedding +.. idownloadable + diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/views/primary.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/views/primary.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,314 @@ +.. _primary_view: + +The Primary View +----------------- + +By default, *CubicWeb* provides a view that fits every available +entity type. This is the first view you might be interested in +modifying. It is also one of the richest and most complex. + +It is automatically selected on a one line result set containing an +entity. + +This view is supposed to render a maximum of informations about the +entity. + +It lives in the :mod:`cubicweb.web.views.primary` module. + +.. _primary_view_layout: + +Layout +`````` + +The primary view has the following layout. + +.. image:: ../../images/primaryview_template.png + +.. _primary_view_configuration: + +Primary view configuration +`````````````````````````` + +If you want to customize the primary view of an entity, overriding the primary +view class may not be necessary. For simple adjustments (attributes or relations +display locations and styles), a much simpler way is to use uicfg. + +Attributes/relations display location +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In the primary view, there are 3 sections where attributes and +relations can be displayed (represented in pink in the image above): + +* attributes +* relations +* sideboxes + +**Attributes** can only be displayed in the attributes section (default + behavior). They can also be hidden. + +For instance, to hide the ``title`` attribute of the ``Blog`` entity: + +.. sourcecode:: python + + from cubicweb.web import uicfg + uicfg.primaryview_section.tag_attribute(('Blog', 'title'), 'hidden') + +**Relations** can be either displayed in one of the three sections or hidden. + +For relations, there are two methods: + +* ``tag_object_of`` for modifying the primary view of the object +* ``tag_subject_of`` for modifying the primary view of the subject + +These two methods take two arguments: + +* a triplet ``(subject, relation_name, object)``, where subject or object can be replaced with ``'*'`` +* the section name or ``hidden`` + +.. sourcecode:: python + + pv_section = uicfg.primaryview_section + # hide every relation `entry_of` in the `Blog` primary view + pv_section.tag_object_of(('*', 'entry_of', 'Blog'), 'hidden') + + # display `entry_of` relations in the `relations` + # section in the `BlogEntry` primary view + pv_section.tag_subject_of(('BlogEntry', 'entry_of', '*'), 'relations') + + +Display content +^^^^^^^^^^^^^^^ + +You can use ``primaryview_display_ctrl`` to customize the display of attributes +or relations. Values of ``primaryview_display_ctrl`` are dictionaries. + + +Common keys for attributes and relations are: + +* ``vid``: specifies the regid of the view for displaying the attribute or the relation. + + If ``vid`` is not specified, the default value depends on the section: + * ``attributes`` section: 'reledit' view + * ``relations`` section: 'autolimited' view + * ``sideboxes`` section: 'sidebox' view + +* ``order``: int used to control order within a section. When not specified, + automatically set according to order in which tags are added. + +.. sourcecode:: python + + # let us remind the schema of a blog entry + class BlogEntry(EntityType): + title = String(required=True, fulltextindexed=True, maxsize=256) + publish_date = Date(default='TODAY') + content = String(required=True, fulltextindexed=True) + entry_of = SubjectRelation('Blog', cardinality='?*') + + # now, we want to show attributes + # with an order different from that in the schema definition + view_ctrl = uicfg.primaryview_display_ctrl + for index, attr in enumerate('title', 'content', 'publish_date'): + view_ctrl.tag_attribute(('BlogEntry', attr), {'order': index}) + +Keys for relations only: + +* ``label``: label for the relations section or side box + +* ``showlabel``: boolean telling whether the label is displayed + +* ``limit``: boolean telling if the results should be limited. If so, a link to all results is displayed + +* ``filter``: callback taking the related result set as argument and returning it filtered + +.. sourcecode:: python + + pv_section = uicfg.primaryview_section + # in `CWUser` primary view, display `created_by` + # relations in relations section + pv_section.tag_object_of(('*', 'created_by', 'CWUser'), 'relations') + + # display this relation as a list, sets the label, + # limit the number of results and filters on comments + def filter_comment(rset): + return rset.filtered_rset(lambda x: x.e_schema == 'Comment') + pv_ctrl = uicfg.primaryview_display_ctrl + pv_ctrl.tag_object_of(('*', 'created_by', 'CWUser'), + {'vid': 'list', 'label': _('latest comment(s):'), + 'limit': True, + 'filter': filter_comment}) + +.. warning:: with the ``primaryview_display_ctrl`` rtag, the subject or the + object of the relation is ignored for respectively ``tag_object_of`` or + ``tag_subject_of``. To avoid warnings during execution, they should be set to + ``'*'``. + +Rendering methods and attributes +```````````````````````````````` + +The basic layout of a primary view is as in the +:ref:`primary_view_layout` section. This layout is actually drawn by +the `render_entity` method. + +The methods you may want to modify while customizing a ``PrimaryView`` +are: + +*render_entity_title(self, entity)* + Renders the entity title using the ``def dc_title(self)`` method. + +*render_entity_metadata(self, entity)* + Renders the entity metadata by calling the ``metadata`` view on the + entity. This generic view is in cubicweb.views.baseviews. + +*render_entity_attributes(self, entity)* + Renders all the attribute of an entity with the exception of + attribute of type `Password` and `Bytes`. The skip_none class + attribute controls the display of None valued attributes. + +*render_entity_relations(self, entity)* + Renders all the relations of the entity in the main section of the page. + +*render_side_boxes(self, entity, boxes)* + Renders relations of the entity in a side box. + +The placement of relations in the relations section or in side boxes +can be controlled through the :ref:`primary_view_configuration` mechanism. + +*content_navigation_components(self, context)* + This method is applicable only for entity type implementing the interface + `IPrevNext`. This interface is for entities which can be linked to a previous + and/or next entity. This method will render the navigation links between + entities of this type, either at the top or at the bottom of the page + given the context (navcontent{top|bottom}). + +Also, please note that by setting the following attributes in your +subclass, you can already customize some of the rendering: + +*show_attr_label* + Renders the attribute label next to the attribute value if set to True. + Otherwise, does only display the attribute value. + +*show_rel_label* + Renders the relation label next to the relation value if set to True. + Otherwise, does only display the relation value. + +*skip_none* + Does not render an attribute value that is None if set to True. + +*main_related_section* + Renders the relations of the entity if set to True. + +A good practice is for you to identify the content of your entity type for which +the default rendering does not answer your need so that you can focus on the specific +method (from the list above) that needs to be modified. We do not advise you to +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. + +We continue along the basic tutorial :ref:`tuto_blog`. + +If you want to change the way a ``BlogEntry`` is displayed, just +override the method ``cell_call()`` of the view ``primary`` in +``BlogDemo/views.py``. + +.. sourcecode:: python + + from cubicweb.selectors import implements + from cubicweb.web.views.primary import Primaryview + + class BlogEntryPrimaryView(PrimaryView): + __select__ = PrimaryView.__select__ & implements('BlogEntry') + + def render_entity_attributes(self, entity): + self.w(u'

published on %s

' % + entity.publish_date.strftime('%Y-%m-%d')) + super(BlogEntryPrimaryView, self).render_entity_attributes(entity) + + +The above source code defines a new primary view for +``BlogEntry``. The `id` class attribute is not repeated there since it +is inherited through the `primary.PrimaryView` class. + +The selector for this view chains the selector of the inherited class +with its own specific criterion. + +The view method ``self.w()`` is used to output data. Here `lines +08-09` output HTML for the publication date of the entry. + +.. image:: ../../images/lax-book_09-new-view-blogentry_en.png + :alt: blog entries now look much nicer + +Let us now improve the primary view of a blog + +.. sourcecode:: python + + from logilab.mtconverter import xml_escape + from cubicweb.selectors import implements, one_line_rset + from cubicweb.web.views.primary import Primaryview + + class BlogPrimaryView(PrimaryView): + __regid__ = 'primary' + __select__ = PrimaryView.__select__ & implements('Blog') + rql = 'Any BE ORDERBY D DESC WHERE BE entry_of B, BE publish_date D, B eid %(b)s' + + def render_entity_relations(self, entity): + rset = self._cw.execute(self.rql, {'b' : entity.eid}) + for entry in rset.entities(): + self.w(u'

' % entry.view('inblogcontext')) + + class BlogEntryInBlogView(EntityView): + __regid__ = 'inblogcontext' + __select__ = implements('BlogEntry') + + def cell_call(self, row, col): + entity = self.cw_rset.get_entity(row, col) + self.w(u'%s' % + entity.absolute_url(), + xml_escape(entity.content[:50]), + xml_escape(entity.description)) + +This happens in two places. First we override the +render_entity_relations method of a Blog's primary view. Here we want +to display our blog entries in a custom way. + +At `line 10`, 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 infers that such entities have to be of the +``BlogEntry`` kind and retrieves them (in the prescribed publish_date +order). + +The request returns a selection of data called a result set. Result +set objects have an .entities() method returning a generator on +requested entities (going transparently through the `ORM` layer). + +At `line 13` the view 'inblogcontext' is applied to each blog entry to +output HTML. (Note that the 'inblogcontext' view is not defined +whatsoever in *CubicWeb*. You are absolutely free to define whole view +families.) We juste arrange to wrap each blogentry output in a 'p' +html element. + +Next, we define the 'inblogcontext' view. This is NOT a primary view, +with its well-defined sections (title, metadata, attribtues, +relations/boxes). All a basic view has to define is cell_call. + +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 +20`). Then we can spit some HTML. + +.. warning:: + + Be careful: all strings manipulated in *CubicWeb* are actually + unicode strings. While web browsers are usually tolerant to + incoherent encodings they are being served, we should not abuse + it. Hence we have to properly escape our data. The xml_escape() + function has to be used to safely fill (X)HTML elements from Python + unicode strings. + +Assuming we added entries to the blog titled `MyLife`, displaying it +now allows to read its description and all its entries. + +.. image:: ../../images/lax-book_10-blog-with-two-entries_en.png + :alt: a blog and all its entries diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/views/startup.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/views/startup.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,15 @@ +Startup views +------------- + +(:mod:`cubicweb.web.views.startup`) + +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 + a result set to apply to. + +*schema* + A view dedicated to the display of the schema of the instance + diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/views/table.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/views/table.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,19 @@ +Table view +---------- + +(:mod:`cubicweb.web.views.tableview`) + +*table* + Creates a HTML table (``) and call the view `cell` for each cell of + the result set. Applicable on any result set. + +*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 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/views/urlpublish.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/views/urlpublish.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,73 @@ +.. -*- coding: utf-8 -*- + +URL publishing +-------------- + +(:mod:`cubicweb.web.views.urlpublishing`) + +.. automodule:: cubicweb.web.views.urlpublishing + +.. autoclass:: cubicweb.web.views.urlpublishing.URLPublisherComponent + :members: + +URL rewriting +------------- + +(:mod:`cubicweb.web.views.urlrewrite`) + +.. autoclass:: cubicweb.web.views.urlrewrite.URLRewriter + :members: + +.. autoclass:: cubicweb.web.views.urlrewrite.SimpleReqRewriter + :members: + +.. autoclass:: cubicweb.web.views.urlrewrite.SchemaBasedRewriter + :members: + + +``SimpleReqRewriter`` is enough for a certain number of simple cases. If it is not sufficient, ``SchemaBasedRewriter`` allows to do more elaborate things. + +Here is an example of ``SimpleReqRewriter`` usage with plain string: + +.. sourcecode:: python + + from cubicweb.web.views.urlrewrite import SimpleReqRewriter + class TrackerSimpleReqRewriter(SimpleReqRewriter): + rules = [ + ('/versions', dict(vid='versionsinfo')), + ] + +When the url is `/versions`, the view with the __regid__ `versionsinfo` is displayed. + +Here is an example of ``SimpleReqRewriter`` usage with regular expressions: + +.. sourcecode:: python + + from cubicweb.web.views.urlrewrite import ( + SimpleReqRewriter, rgx) + + class BlogReqRewriter(SimpleReqRewriter): + rules = [ + (rgx('/blogentry/([a-z_]+)\.rss'), + dict(rql=('Any X ORDERBY CD DESC LIMIT 20 WHERE X is BlogEntry,' + 'X creation_date CD, X created_by U, ' + 'U login "%(user)s"' + % {'user': r'\1'}, vid='rss'))), + ] + +When a url matches the regular expression, the view with the __regid__ +`rss` which match the result set is displayed. + +Here is an example of ``SchemaBasedRewriter`` usage: + +.. sourcecode:: python + + from cubicweb.web.views.urlrewrite import ( + SchemaBasedRewriter, rgx, build_rset) + + class TrackerURLRewriter(SchemaBasedRewriter): + rules = [ + (rgx('/project/([^/]+)/([^/]+)/tests'), + build_rset(rql='Version X WHERE X version_of P, P name %(project)s, X num %(num)s', + rgxgroups=[('project', 1), ('num', 2)], vid='versiontests')), + ] diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/views/views.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/views/views.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,142 @@ + +.. _Views: + +Principles +---------- + +We'll start with a description of the interface providing a basic +understanding of the available classes and methods, then detail the +view selection principle. + +A `View` is an object responsible for the rendering of data from the +model into an end-user consummable form. They typically churn out an +XHTML stream, but there are views concerned with email other non-html +outputs. + +.. _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 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 +attributes: + +* `templatable` indicates if the view may be embedded in a main + template or if it has to be rendered standalone (i.e. pure XML views + must not be embedded in the main template of HTML pages) + +* if the view is not templatable, it should set the `content_type` + class attribute to the correct MIME type (text/xhtml being the + default) + +* the `category` attribute may be used in the interface to regroup + related view kinds together + +A view writes to its output stream thanks to its attribute `w` (the +append method of an `UStreamIO`, except for binary views). + +At instantiation time, the standard `_cw` and `cw_rset` attributes are +added and the `w` attribute will be set at rendering time. + +The basic interface for views is as follows (remember that the result +set has a tabular structure with rows and columns, hence cells): + +* `render(**context)`, render the view by calling `call` or + `cell_call` depending on the context + +* `call(**kwargs)`, call the view for a complete result set or null + (the default implementation calls `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 (`row` and `col` being integers used to access the cell) + +* `url()`, returns the URL enabling us to get the view with the current + result set + +* `wview(__vid, rset, __fallback_vid=None, **kwargs)`, call the view of + identifier `__vid` on the given result set. It is possible to give a + fallback view identifier that will be used if the requested view is + not applicable to the result set. + +* `html_headers()`, returns a list of HTML headers to be set by the + main template + +* `page_title()`, returns the title to use in the HTML header `title` + +Other basic view classes +```````````````````````` +Here are some of the subclasses of `View` defined in `cubicweb.common.view` +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 +* `AnyRsetView`, view applicable to any result set + +Examples of views class +``````````````````````` + +- Using `templatable`, `content_type` and HTTP cache configuration + +.. sourcecode:: python + + class RSSView(XMLView): + __regid__ = 'rss' + title = _('rss') + templatable = False + content_type = 'text/xml' + http_cache_manager = MaxAgeHTTPCacheManager + cache_max_age = 60*60*2 # stay in http cache for 2 hours by default + + +- Using a custom selector + +.. sourcecode:: python + + class SearchForAssociationView(EntityView): + """view called by the edition view when the user asks + to search for something to link to the edited eid + """ + __regid__ = 'search-associate' + title = _('search for association') + __select__ = one_line_rset() & match_search_state('linksearch') & implements('Any') + + +XML views, binaries views... +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 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` or any + relevant and more specialised mime type + +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 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/views/wdoc.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/views/wdoc.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,9 @@ +.. -*- coding: utf-8 -*- + +Online documentation system +--------------------------- + +(:mod:`cubicweb.web.views.wdoc`) + +XXX describe the on-line documentation system + diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/devweb/views/xmlrss.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/devweb/views/xmlrss.rst Mon Apr 26 12:52:48 2010 +0200 @@ -0,0 +1,60 @@ +.. _XmlAndRss: + +XML and RSS views +----------------- + +(:mod:`cubicweb.web.views.xmlrss`) + +Overview ++++++++++ + +*rss* + Creates a RSS/XML view and call the view `rssitem` for each entity of + the result set. + +*rssitem* + Create a RSS/XML view for each entity based on the results of the dublin core + methods of the entity (`dc_*`) + +RSS Channel Example +++++++++++++++++++++ + +Assuming you have several blog entries, click on the title of the +search box in the left column. A larger search box should appear. Enter:: + + Any X ORDERBY D WHERE X is BlogEntry, X creation_date D + +and you get a list of blog entries. + +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. + +Enter the same query in the search box and you will see the same list, +plus a box titled "possible views" in the left column. Click on +"entityview", then "RSS". + +You just applied the "RSS" view to the RQL selection you requested. + +That's it, you have a RSS channel for your blog. + +Try again with:: + + Any X ORDERBY D WHERE X is BlogEntry, X creation_date D, + X entry_of B, B title "MyLife" + +Another RSS channel, but a bit more focused. + +A last one for the road:: + + Any C ORDERBY D WHERE C is Comment, C creation_date D LIMIT 15 + +displayed with the RSS view, that's a channel for the last fifteen +comments posted. + +[WRITE ME] + +* show that the RSS view can be used to display an ordered selection + of blog entries, thus providing a RSS channel + +* show that a different selection (by category) means a different channel diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/03-transitions-view.en.png Binary file doc/book/en/images/03-transitions-view.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/03-transitions-view_en.png Binary file doc/book/en/images/03-transitions-view_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/archi_globale.en.png Binary file doc/book/en/images/archi_globale.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/archi_globale_en.png Binary file doc/book/en/images/archi_globale_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/cbw-add-relation-entryof.en.png Binary file doc/book/en/images/cbw-add-relation-entryof.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/cbw-add-relation-entryof_en.png Binary file doc/book/en/images/cbw-add-relation-entryof_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/cbw-create-blog.en.png Binary file doc/book/en/images/cbw-create-blog.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/cbw-create-blog_en.png Binary file doc/book/en/images/cbw-create-blog_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/cbw-detail-one-blogentry.en.png Binary file doc/book/en/images/cbw-detail-one-blogentry.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/cbw-detail-one-blogentry_en.png Binary file doc/book/en/images/cbw-detail-one-blogentry_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/cbw-list-one-blog.en.png Binary file doc/book/en/images/cbw-list-one-blog.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/cbw-list-one-blog_en.png Binary file doc/book/en/images/cbw-list-one-blog_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/cbw-list-two-blog.en.png Binary file doc/book/en/images/cbw-list-two-blog.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/cbw-list-two-blog_en.png Binary file doc/book/en/images/cbw-list-two-blog_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/cbw-schema.en.png Binary file doc/book/en/images/cbw-schema.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/cbw-schema_en.png Binary file doc/book/en/images/cbw-schema_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/cbw-update-primary-view.en.png Binary file doc/book/en/images/cbw-update-primary-view.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/cbw-update-primary-view_en.png Binary file doc/book/en/images/cbw-update-primary-view_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book.00-login.en.png Binary file doc/book/en/images/lax-book.00-login.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book.01-start.en.png Binary file doc/book/en/images/lax-book.01-start.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book.02-cookie-values.en.png Binary file doc/book/en/images/lax-book.02-cookie-values.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book.02-create-blog.en.png Binary file doc/book/en/images/lax-book.02-create-blog.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book.03-list-one-blog.en.png Binary file doc/book/en/images/lax-book.03-list-one-blog.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book.03-site-config-panel.en.png Binary file doc/book/en/images/lax-book.03-site-config-panel.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book.03-state-submitted.en.png Binary file doc/book/en/images/lax-book.03-state-submitted.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book.03-transitions-view.en.png Binary file doc/book/en/images/lax-book.03-transitions-view.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book.04-detail-one-blog.en.png Binary file doc/book/en/images/lax-book.04-detail-one-blog.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book.05-list-two-blog.en.png Binary file doc/book/en/images/lax-book.05-list-two-blog.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book.06-add-relation-entryof.en.png Binary file doc/book/en/images/lax-book.06-add-relation-entryof.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book.06-header-no-login.en.png Binary file doc/book/en/images/lax-book.06-header-no-login.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book.06-main-template-layout.en.png Binary file doc/book/en/images/lax-book.06-main-template-layout.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book.06-main-template-logo.en.png Binary file doc/book/en/images/lax-book.06-main-template-logo.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book.06-simple-main-template.en.png Binary file doc/book/en/images/lax-book.06-simple-main-template.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book.07-detail-one-blogentry.en.png Binary file doc/book/en/images/lax-book.07-detail-one-blogentry.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book.08-schema.en.png Binary file doc/book/en/images/lax-book.08-schema.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book.09-new-view-blogentry.en.png Binary file doc/book/en/images/lax-book.09-new-view-blogentry.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book.10-blog-with-two-entries.en.png Binary file doc/book/en/images/lax-book.10-blog-with-two-entries.en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book_00-login_en.png Binary file doc/book/en/images/lax-book_00-login_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book_01-start_en.png Binary file doc/book/en/images/lax-book_01-start_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book_02-cookie-values_en.png Binary file doc/book/en/images/lax-book_02-cookie-values_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book_02-create-blog_en.png Binary file doc/book/en/images/lax-book_02-create-blog_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book_03-list-one-blog_en.png Binary file doc/book/en/images/lax-book_03-list-one-blog_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book_03-site-config-panel_en.png Binary file doc/book/en/images/lax-book_03-site-config-panel_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book_03-state-submitted_en.png Binary file doc/book/en/images/lax-book_03-state-submitted_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book_03-transitions-view_en.png Binary file doc/book/en/images/lax-book_03-transitions-view_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book_04-detail-one-blog_en.png Binary file doc/book/en/images/lax-book_04-detail-one-blog_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book_05-list-two-blog_en.png Binary file doc/book/en/images/lax-book_05-list-two-blog_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book_06-add-relation-entryof_en.png Binary file doc/book/en/images/lax-book_06-add-relation-entryof_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book_06-header-no-login_en.png Binary file doc/book/en/images/lax-book_06-header-no-login_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book_06-main-template-layout_en.png Binary file doc/book/en/images/lax-book_06-main-template-layout_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book_06-main-template-logo_en.png Binary file doc/book/en/images/lax-book_06-main-template-logo_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book_06-simple-main-template_en.png Binary file doc/book/en/images/lax-book_06-simple-main-template_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book_07-detail-one-blogentry_en.png Binary file doc/book/en/images/lax-book_07-detail-one-blogentry_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book_08-schema_en.png Binary file doc/book/en/images/lax-book_08-schema_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book_09-new-view-blogentry_en.png Binary file doc/book/en/images/lax-book_09-new-view-blogentry_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/images/lax-book_10-blog-with-two-entries_en.png Binary file doc/book/en/images/lax-book_10-blog-with-two-entries_en.png has changed diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/index.rst --- a/doc/book/en/index.rst Fri Apr 23 13:36:43 2010 +0200 +++ b/doc/book/en/index.rst Mon Apr 26 12:52:48 2010 +0200 @@ -40,9 +40,6 @@ .. _`mailing-list`: http://lists.cubicweb.org/mailman/listinfo/cubicweb .. _blog: http://www.cubicweb.org/blog/1238 -Table of Contents -================= - .. toctree:: :maxdepth: 2 @@ -52,7 +49,8 @@ .. toctree:: :maxdepth: 3 - development/index + devrepo/index + devweb/index .. toctree:: :maxdepth: 2 diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/intro/concepts.rst --- a/doc/book/en/intro/concepts.rst Fri Apr 23 13:36:43 2010 +0200 +++ b/doc/book/en/intro/concepts.rst Mon Apr 26 12:52:48 2010 +0200 @@ -16,8 +16,8 @@ ----- A cube is a software component made of three parts: its data model -(:file:`schema`), its logic (:file:`entities`) and its user interface -(:file:`views`). +(:mod:`schema`), its logic (:mod:`entities`) and its user interface +(:mod:`views`). A cube can use other cubes as building blocks and assemble them to provide a whole with richer functionnalities than its parts. The cubes `cubicweb-blog`_ and @@ -59,7 +59,7 @@ repository. For applications that support high traffic, several web (front-end) and data (back-end) instances can be set-up to share the load. -.. image:: ../images/archi_globale.en.png +.. image:: ../images/archi_globale_en.png The command :command:`cubicweb-ctl list` also displays the list of instances installed on your system. @@ -70,7 +70,7 @@ environment variable. -.. Note:: +.. note:: The term application is used to refer to "something that should do something as a whole", eg more like a project and so can refer to an instance or to a cube, @@ -101,14 +101,14 @@ repository side, you can for instance by-pass security checks, which isn't possible from client code. -Some logic can be attached to events that happen in the repository, like -creation of entities, deletion of relations, etc. This is used for example to -send email notifications when the state of an object changes. See :ref:`HookIntro` below. +Some logic can be attached to events that happen in the repository, +like creation of entities, deletion of relations, etc. This is used +for example to send email notifications when the state of an object +changes. See :ref:`HookIntro` below. .. [1] not to be confused with a Mercurial repository or a Debian repository. .. _`Python Remote Objects`: http://pyro.sourceforge.net/ - .. _WebEngineIntro: Web Engine @@ -237,11 +237,11 @@ The RQL query language ---------------------- -**No need for a complicated ORM when you have a powerful data - manipulation language** +No need for a complicated ORM when you have a powerful data +manipulation language. -All the persistent data in a |cubicweb| instance is retrieved and modified by -using the Relation Query Language. +All the persistent data in a |cubicweb| instance is retrieved and +modified using RQL (see :ref:`rql_intro`). This query language is inspired by SQL but is on a higher level in order to emphasize browsing relations. @@ -252,6 +252,8 @@ The repository exposes a `db-api`_ like api but using the RQL instead of SQL. +.. _`db-api`: http://www.python.org/dev/peps/pep-0249/ + You basically get a connection using :func:`cubicweb.dbapi.connect` , then get a cursor to call its `execute` method which will return result set for the given rql query. @@ -336,8 +338,6 @@ Hooks and operation are an essential building block of any moderately complicated cubicweb application. -.. Note: +.. note:: RQL queries executed in hooks and operations are *unsafe* by default, e.g. the read and write security is deactivated unless explicitly asked. - -.. |cubicweb| replace:: *CubicWeb* diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/tutorials/base/create-cube.rst --- a/doc/book/en/tutorials/base/create-cube.rst Fri Apr 23 13:36:43 2010 +0200 +++ b/doc/book/en/tutorials/base/create-cube.rst Mon Apr 26 12:52:48 2010 +0200 @@ -174,7 +174,7 @@ ``everything about technology`` as the description, then validate the form by clicking on ``Validate``. -.. image:: ../../images/cbw-create-blog.en.png +.. image:: ../../images/cbw-create-blog_en.png :alt: from to create blog Click on the logo at top left to get back to the home page, then @@ -182,7 +182,7 @@ You should be seeing a list with a single item ``Tech-blog`` you just created. -.. image:: ../../images/cbw-list-one-blog.en.png +.. image:: ../../images/cbw-list-one-blog_en.png :alt: displaying a list of a single blog Clicking on this item will get you to its detailed description except @@ -194,7 +194,7 @@ again to follow the Blog link for the second time. The list now has two items. -.. image:: ../../images/cbw-list-two-blog.en.png +.. image:: ../../images/cbw-list-two-blog_en.png :alt: displaying a list of two blogs Add a BlogEntry @@ -215,21 +215,21 @@ combobox titled ``add relation`` would have showed up. -.. image:: ../../images/cbw-add-relation-entryof.en.png +.. image:: ../../images/cbw-add-relation-entryof_en.png :alt: editing a blog entry to add a relation to a blog Validate the changes by clicking ``Validate``. The entity BlogEntry that is displayed now includes a link to the entity Blog named ``MyLife``. -.. image:: ../../images/cbw-detail-one-blogentry.en.png +.. image:: ../../images/cbw-detail-one-blogentry_en.png :alt: displaying the detailed view of a blogentry Note that all of this was handled by the framework and that the only input that was provided so far is the schema. To get a graphical view of the schema, point your browser to the URL http://localhost:8080/schema -.. image:: ../../images/cbw-schema.en.png +.. image:: ../../images/cbw-schema_en.png :alt: graphical view of the schema (aka data-model) @@ -325,7 +325,7 @@ You can now see that the publication date has a prefix. -.. image:: ../../images/cbw-update-primary-view.en.png +.. image:: ../../images/cbw-update-primary-view_en.png :alt: modified primary view diff -r 354cf5ef31dc -r 092bb9355769 doc/book/en/tutorials/base/maintemplate.rst --- a/doc/book/en/tutorials/base/maintemplate.rst Fri Apr 23 13:36:43 2010 +0200 +++ b/doc/book/en/tutorials/base/maintemplate.rst Mon Apr 26 12:52:48 2010 +0200 @@ -8,7 +8,7 @@ A page is composed as indicated on the schema below: -.. image:: ../../images/lax-book.06-main-template-layout.en.png +.. image:: ../../images/lax-book_06-main-template-layout_en.png In this section we will demonstrate a change in one of the main interesting template from the three you will look for, @@ -83,7 +83,7 @@ -.. image:: ../../images/lax-book.06-header-no-login.en.png +.. image:: ../../images/lax-book_06-header-no-login_en.png Customize footer ```````````````` @@ -121,7 +121,7 @@ be used based on TheMainTemplate called SimpleMainTemplate which does not have a top section. -.. image:: ../../images/lax-book.06-simple-main-template.en.png +.. image:: ../../images/lax-book_06-simple-main-template_en.png XXX [WRITE ME] diff -r 354cf5ef31dc -r 092bb9355769 server/migractions.py --- a/server/migractions.py Fri Apr 23 13:36:43 2010 +0200 +++ b/server/migractions.py Mon Apr 26 12:52:48 2010 +0200 @@ -116,10 +116,10 @@ return super(ServerMigrationHelper, self).cmd_process_script( migrscript, funcname, *args, **kwargs) else: - print - print ('-> ignoring %s, only .py .sql and .txt scripts are considered' % + print >> sys.stderr + print >> sys.stderr, ('-> ignoring %s, only .py .sql and .txt scripts are considered' % migrscript) - print + print >> sys.stderr self.commit() except: self.rollback() diff -r 354cf5ef31dc -r 092bb9355769 web/views/baseviews.py --- a/web/views/baseviews.py Fri Apr 23 13:36:43 2010 +0200 +++ b/web/views/baseviews.py Mon Apr 26 12:52:48 2010 +0200 @@ -311,7 +311,8 @@ def call(self, **kwargs): """display a list of entities by calling their view""" - if not 'vtitle' in self._cw.form: + showtitle = kwargs.pop('showtitle', not 'vtitle' in self._cw.form) + if showtitle: self.w(u'

%s

' % self.title) super(SameETypeListView, self).call(**kwargs)