merge stable
authorAurelien Campeas <aurelien.campeas@logilab.fr>
Fri, 16 Apr 2010 11:13:46 +0200
branchstable
changeset 5305 d98fccb0da7f
parent 5304 7be2e2cb9244 (current diff)
parent 5301 f4219a6e62e3 (diff)
child 5306 763319a51e72
merge
--- a/doc/book/en/development/devweb/index.rst	Thu Apr 15 19:38:24 2010 +0200
+++ b/doc/book/en/development/devweb/index.rst	Fri Apr 16 11:13:46 2010 +0200
@@ -1,20 +1,21 @@
 Web development
 ===============
 
-In this chapter, we will describe the core api for web development in the *CubicWeb* framework.
+In this chapter, we will describe the core APIs for web development in
+the *CubicWeb* framework.
 
 .. toctree::
    :maxdepth: 2
 
-   request
    publisher
    controllers
-   property
+   request
+   views/index
    rtags
-   views/index
+   js
+   css
    form
    facets
+   internationalization
+   property
    httpcaching
-   js
-   css
-   internationalization
--- a/doc/book/en/development/devweb/publisher.rst	Thu Apr 15 19:38:24 2010 +0200
+++ b/doc/book/en/development/devweb/publisher.rst	Fri Apr 16 11:13:46 2010 +0200
@@ -3,6 +3,61 @@
 Publisher
 ---------
 
-XXX view.vid_from_rset
+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.
+
+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 sich) 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
+
 
-XXX cubicweb.web.application; coop diagram for execution of a http query
+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_rst`)
+    * 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:
--- a/doc/book/en/development/devweb/request.rst	Thu Apr 15 19:38:24 2010 +0200
+++ b/doc/book/en/development/devweb/request.rst	Fri Apr 16 11:13:46 2010 +0200
@@ -62,8 +62,8 @@
 most of the interface of `Request` is defined in the session associated
 to the client.
 
-Automatic API
-`````````````
+API
+```
 
 The elements we gave in overview for above are built in three layers,
 from ``cubicweb.req.RequestSessionBase``, ``cubicweb.dbapi.DBAPIRequest`` and
--- a/doc/book/en/development/devweb/views/boxes.rst	Thu Apr 15 19:38:24 2010 +0200
+++ b/doc/book/en/development/devweb/views/boxes.rst	Fri Apr 16 11:13:46 2010 +0200
@@ -1,5 +1,7 @@
-Boxes (:mod:`cubicweb.web.views.boxes`)
----------------------------------------------------------------
+Boxes
+-----
+
+(:mod:`cubicweb.web.views.boxes`)
 
 *sidebox*
   This view displays usually a side box of some related entities
@@ -24,7 +26,6 @@
   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.
--- a/doc/book/en/development/devweb/views/index.rst	Thu Apr 15 19:38:24 2010 +0200
+++ b/doc/book/en/development/devweb/views/index.rst	Fri Apr 16 11:13:46 2010 +0200
@@ -1,5 +1,5 @@
-The views system
-================
+The View system
+===============
 
 .. |cubicweb| replace:: *CubicWeb*
 
@@ -20,11 +20,15 @@
    table
    xmlrss
    autoform
-   editforms
+..   editforms
+
+.. toctree::
+   :maxdepth: 3
+
    urlpublish
    breadcrumbs
-   facets
-   wdoc
-   embedding
-   idownloadable
+..   facets
+..   wdoc
+..   embedding
+..   idownloadable
 
--- a/doc/book/en/development/devweb/views/startup.rst	Thu Apr 15 19:38:24 2010 +0200
+++ b/doc/book/en/development/devweb/views/startup.rst	Fri Apr 16 11:13:46 2010 +0200
@@ -1,5 +1,8 @@
-Startup views (:mod:`cubicweb.web.views.startup`)
--------------------------------------------------
+Startup views
+-------------
+
+ (:mod:`cubicweb.web.views.startup`)
+
 Usual selector: no_rset or yes.
 
 Views that don't apply to a result set
--- a/doc/book/en/development/devweb/views/urlpublish.rst	Thu Apr 15 19:38:24 2010 +0200
+++ b/doc/book/en/development/devweb/views/urlpublish.rst	Fri Apr 16 11:13:46 2010 +0200
@@ -1,7 +1,27 @@
 .. -*- coding: utf-8 -*-
 
-URL Rewriting (:mod:`cubicweb.web.views.urlpublish`) and (:mod:`cubicweb.web.views.urlrewrite`)
-------------------------------------------------------------------------------------------------
+URL publishing
+--------------
+
+(:mod:`cubicweb.web.views.urlpublishing`)
+
+.. automodule:: cubicweb.web.views.urlpublishing
+
+.. autoclass:: cubicweb.web.views.urlpublishing.URLPublisherComponent
+   :members:
+
+URL rewriting
+-------------
 
-XXX feed me
-show how urls are mapped to selections and views and explain URLRewriting
+(: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:
+
+
--- a/doc/book/en/standard_theme/static/lglb-sphinx-doc.css	Thu Apr 15 19:38:24 2010 +0200
+++ b/doc/book/en/standard_theme/static/lglb-sphinx-doc.css	Fri Apr 16 11:13:46 2010 +0200
@@ -10,9 +10,9 @@
 /* -- page layout ----------------------------------------------------------- */
 
 body {
-    font-family: 'Helvetica', 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva',
+    font-family: 'Bitstream Vera Sans', 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva',
                  'Verdana', sans-serif;
-    font-size: 15px;
+    font-size: 14px;
     line-height: 150%;
     text-align: center;
     background-color: #D0D0D0;
--- a/web/views/urlpublishing.py	Thu Apr 15 19:38:24 2010 +0200
+++ b/web/views/urlpublishing.py	Fri Apr 16 11:13:46 2010 +0200
@@ -1,28 +1,26 @@
-"""associate url's path to view identifier / rql queries
+# organization: Logilab
+# copyright: 2001-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.
+# contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
+# license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses
+"""Associate url's path to view identifier / rql queries.
 
-It currently handle url's path with the forms
+It currently handles url path with the forms:
 
 * <publishing_method>
+* minimal REST publishing:
 
-* minimal REST publishing:
   * <eid>
   * <etype>[/<attribute name>/<attribute value>]*
-
 * folder navigation
 
-
-You can actually control URL (more exactly path) resolution using URL path
-evaluator.
-
-XXX actionpath and folderpath execute a query whose results is lost
-because of redirecting instead of direct traversal
+You can actually control URL (more exactly path) resolution using an
+URL path evaluator.
 
-:organization: Logilab
-:copyright: 2001-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.
-:contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
-:license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses
+.. note::
+
+ Actionpath and Folderpath execute a query whose results is lost
+ because of redirecting instead of direct traversal.
 """
-
 __docformat__ = "restructuredtext en"
 
 from rql import TypeResolverException
@@ -37,17 +35,18 @@
     """
 
 class URLPublisherComponent(component.Component):
-    """associate url's path to view identifier / rql queries,
-    by applying a chain of urlpathevaluator components.
+    """Associate url path to view identifier / rql queries, by
+    applying a chain of urlpathevaluator components.
 
-    An evaluator is a URLPathEvaluator subclass with a .evaluate_path
+    An evaluator is a URLPathEvaluator subclass with an .evaluate_path
     method taking the request object and the path to publish as
-    argument.  It will either returns a publishing method identifier
-    and a rql query on success or raises a `PathDontMatch` exception
-    on failure. URL evaluators are called according to their `priority`
-    attribute, with 0 as the greatest priority and greater values as
-    lower priority.  The first evaluator returning a result or raising
-    something else than `PathDontMatch` will stop the handlers chain.
+    argument.  It will either return a publishing method identifier
+    and an rql query on success or raise a `PathDontMatch` exception
+    on failure. URL evaluators are called according to their
+    `priority` attribute, with 0 as the greatest priority and greater
+    values as lower priority. The first evaluator returning a result
+    or raising something else than `PathDontMatch` will stop the
+    handlers chain.
     """
     __regid__ = 'urlpublisher'
     vreg = None # XXX necessary until property for deprecation warning is on appobject
@@ -64,18 +63,18 @@
         self.evaluators = sorted(evaluators, key=lambda x: x.priority)
 
     def process(self, req, path):
-        """given an url (essentialy caracterized by a path on the server,
-        but additional information may be found in the request object), return
-        a publishing method identifier (eg controller) and an optional result
-        set
+        """Given an url (essentialy caracterized by a path on the
+        server, but additional information may be found in the request
+        object), return a publishing method identifier
+        (e.g. controller) and an optional result set.
 
-        :type req: `cubicweb.web.Request`
+        :type req: `cubicweb.web.request.CubicWebRequestBase`
         :param req: the request object
 
         :type path: str
         :param path: the path of the resource to publish
 
-        :rtype: tuple(str, `cubicweb.utils.ResultSet` or None)
+        :rtype: tuple(str, `cubicweb.rset.ResultSet` or None)
         :return: the publishing method identifier and an optional result set
 
         :raise NotFound: if no handler is able to decode the given path
--- a/web/views/urlrewrite.py	Thu Apr 15 19:38:24 2010 +0200
+++ b/web/views/urlrewrite.py	Fri Apr 16 11:13:46 2010 +0200
@@ -1,4 +1,4 @@
-"""Rules based url rewriter component, to get configurable RESTful urls
+"""Rules based url rewriter component, to get configurable RESTful urls.
 
 :organization: Logilab
 :copyright: 2007-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.
@@ -40,17 +40,17 @@
 
 
 class URLRewriter(AppObject):
-    """base class for URL rewriters
+    """Base class for URL rewriters.
 
-    url rewriters should have a `rules` dict that maps an input URI
+    Url rewriters should have a `rules` dict that maps an input URI
     to something that should be used for rewriting.
 
     The actual logic that defines how the rules dict is used is implemented
-    in the `rewrite` method
+    in the `rewrite` method.
 
     A `priority` attribute might be used to indicate which rewriter
     should be tried first. The higher the priority is, the earlier the
-    rewriter will be tried
+    rewriter will be tried.
     """
     __metaclass__ = metarewriter
     __registry__ = 'urlrewriting'
@@ -62,11 +62,11 @@
 
 
 class SimpleReqRewriter(URLRewriter):
-    """The SimpleReqRewriters uses a `rules` dict that maps
-    input URI (regexp or plain string) to a dictionary to update the
-    request's form
+    """The SimpleReqRewriters uses a `rules` dict that maps input URI
+    (regexp or plain string) to a dictionary to update the request's
+    form.
 
-    If the input uri is a regexp, group substitution is allowed
+    If the input uri is a regexp, group substitution is allowed.
     """
     __regid__ = 'simple'