doc/book/en/devweb/publisher.rst
author Sylvain Thénault <sylvain.thenault@logilab.fr>
Fri, 10 Jun 2011 16:54:20 +0200
changeset 7493 3c46b9390871
parent 5400 b7ab099b128a
permissions -rw-r--r--
[rql2sql] fix for some queries where eid variable used and entities picked as variable's table
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
5284
ad922b7449aa [doc/book] rework the templates chapter (wipe out horrible example, talk more about structure)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
     1
.. _publisher:
ad922b7449aa [doc/book] rework the templates chapter (wipe out horrible example, talk more about structure)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
     2
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     3
Publisher
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     4
---------
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     5
5301
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
     6
What happens when an HTTP request is issued ?
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
     7
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
     8
The story begins with the ``CubicWebPublisher.main_publish``
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
     9
method. We do not get upper in the bootstrap process because it is
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    10
dependant on the used HTTP library. With `twisted`_ however,
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    11
``cubicweb.etwist.server.CubicWebRootResource.render_request`` is the
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    12
real entry point.
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    13
5400
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    14
.. _`twisted`: http://twistedmatrix.com/trac/
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    15
5301
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    16
What main_publish does:
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    17
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    18
* get a controller id and a result set from the path (this is actually
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    19
  delegated to the `urlpublisher` component)
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    20
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    21
* the controller is then selected (if not, this is considered an
5348
db7b4d2eba4b [doc/book] typos
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5301
diff changeset
    22
  authorization failure and signaled as such) and called
5301
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    23
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    24
* then either a proper result is returned, in which case the
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    25
  request/connection object issues a ``commit`` and returns the result
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    26
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    27
* or error handling must happen:
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    28
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    29
  * ``ValidationErrors`` pop up there and may lead to a redirect to a
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    30
    previously arranged url or standard error handling applies
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    31
  * an HTTP 500 error (`Internal Server Error`) is issued
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    32
5284
ad922b7449aa [doc/book] rework the templates chapter (wipe out horrible example, talk more about structure)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    33
5301
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    34
Now, let's turn to the controller. There are many of them in
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    35
:mod:`cubicweb.web.views.basecontrollers`. We can just follow the
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    36
default `view` controller that is selected on a `view` path. See the
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    37
:ref:`controllers` chapter for more information on controllers.
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    38
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    39
The `View` controller's entry point is the `publish` method. It does
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    40
the following:
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    41
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    42
* compute the `main` view to be applied, using either the given result
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    43
  set or building one from a user provided rql string (`rql` and `vid`
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    44
  can be forced from the url GET parameters), that is:
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    45
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    46
    * compute the `vid` using the result set and the schema (see
5348
db7b4d2eba4b [doc/book] typos
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5301
diff changeset
    47
      `cubicweb.web.views.vid_from_rset`)
5301
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    48
    * handle all error cases that could happen in this phase
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    49
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    50
* do some cache management chores
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    51
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    52
* select a main template (typically `TheMainTemplate`, see chapter
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    53
  :ref:`templates`)
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    54
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    55
* call it with the result set and the computed view.
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    56
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    57
What happens next actually depends on the template and the view, but
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    58
in general this is the rendering phase.
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    59
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    60
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    61
CubicWebPublisher API
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    62
`````````````````````
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    63
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    64
.. autoclass:: cubicweb.web.application.CubicWebPublisher
f4219a6e62e3 [doc/book] stuff a bit the publishing process (including various docstrings)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5284
diff changeset
    65
   :members: