# HG changeset patch # User Aurelien Campeas # Date 1271352670 -7200 # Node ID f4219a6e62e3ce7b6b769f7e35fceddd37ce4254 # Parent 058db99425e483fa371bcb5be01669a520673fd9 [doc/book] stuff a bit the publishing process (including various docstrings) diff -r 058db99425e4 -r f4219a6e62e3 doc/book/en/development/devweb/index.rst --- a/doc/book/en/development/devweb/index.rst Thu Apr 15 19:28:28 2010 +0200 +++ b/doc/book/en/development/devweb/index.rst Thu Apr 15 19:31:10 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 diff -r 058db99425e4 -r f4219a6e62e3 doc/book/en/development/devweb/publisher.rst --- a/doc/book/en/development/devweb/publisher.rst Thu Apr 15 19:28:28 2010 +0200 +++ b/doc/book/en/development/devweb/publisher.rst Thu Apr 15 19:31:10 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: diff -r 058db99425e4 -r f4219a6e62e3 doc/book/en/development/devweb/request.rst --- a/doc/book/en/development/devweb/request.rst Thu Apr 15 19:28:28 2010 +0200 +++ b/doc/book/en/development/devweb/request.rst Thu Apr 15 19:31:10 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 diff -r 058db99425e4 -r f4219a6e62e3 doc/book/en/development/devweb/views/boxes.rst --- a/doc/book/en/development/devweb/views/boxes.rst Thu Apr 15 19:28:28 2010 +0200 +++ b/doc/book/en/development/devweb/views/boxes.rst Thu Apr 15 19:31:10 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. diff -r 058db99425e4 -r f4219a6e62e3 doc/book/en/development/devweb/views/index.rst --- a/doc/book/en/development/devweb/views/index.rst Thu Apr 15 19:28:28 2010 +0200 +++ b/doc/book/en/development/devweb/views/index.rst Thu Apr 15 19:31:10 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 diff -r 058db99425e4 -r f4219a6e62e3 doc/book/en/development/devweb/views/startup.rst --- a/doc/book/en/development/devweb/views/startup.rst Thu Apr 15 19:28:28 2010 +0200 +++ b/doc/book/en/development/devweb/views/startup.rst Thu Apr 15 19:31:10 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 diff -r 058db99425e4 -r f4219a6e62e3 doc/book/en/development/devweb/views/urlpublish.rst --- a/doc/book/en/development/devweb/views/urlpublish.rst Thu Apr 15 19:28:28 2010 +0200 +++ b/doc/book/en/development/devweb/views/urlpublish.rst Thu Apr 15 19:31:10 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: + + diff -r 058db99425e4 -r f4219a6e62e3 web/views/urlpublishing.py --- a/web/views/urlpublishing.py Thu Apr 15 19:28:28 2010 +0200 +++ b/web/views/urlpublishing.py Thu Apr 15 19:31:10 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: * +* minimal REST publishing: -* minimal REST publishing: * * [//]* - * 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 diff -r 058db99425e4 -r f4219a6e62e3 web/views/urlrewrite.py --- a/web/views/urlrewrite.py Thu Apr 15 19:28:28 2010 +0200 +++ b/web/views/urlrewrite.py Thu Apr 15 19:31:10 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'