cubicweb: comparison doc/book/en/development/devcore/vreg.rst

equal deleted inserted replaced

-:294e084f1263
+:21f2e01fdd6a
-. -*- coding: utf-8 -*-
 The VRegistry
 --------------
 The recording process on startup
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Details of the recording process
 ````````````````````````````````
-XXX this part needs to be updated and checked
+.. index::
+vregistry: registration_callback
+On startup, |cubicweb| have to fill the vregistry with appobjects defined
+in its library and in cubes used by the instance. Appobjects from the library
+are loaded first, then appobjects provided by cubes are loaded in an ordered
+way (e.g. if your cube depends on an other, appobjects from the dependancy will
+be loaded first). Cube's modules or packages where appobject are looked at is explained
+in :ref:`cubelayout`.
+For each module:
 * by default all objects are registered automatically
 * if some objects have to replace other objects or be included only if a
-condition is true,
+condition is true, you'll have to define a `registration_callback(vreg)`
-- explicitly register the object by defining `registration_callback(vreg)`
+function in your module and explicitly register *all objects* in this
-- call registration methods on objects listed in the vreg registry
+module, using the vregistry api defined below.
 .. note::
 Once the function `registration_callback(vreg)` is implemented, all the objects
 have to be explicitly registered as it disables the automatic object registering.
-Examples:
+API d'enregistrement des objets
+```````````````````````````````
+.. automethod:: cubicweb.cwvreg.CubicWebVRegistry.register_all
+.. automethod:: cubicweb.cwvreg.CubicWebVRegistry.register_and_replace
+.. automethod:: cubicweb.cwvreg.CubicWebVRegistry.register
+.. automethod:: cubicweb.cwvreg.CubicWebVRegistry.register_if_interface_found
+.. automethod:: cubicweb.cwvreg.CubicWebVRegistry.unregister
+Examples
+````````
 .. sourcecode:: python
 # web/views/basecomponents.py
 def registration_callback(vreg):
 # register everything in the module except SeeAlsoComponent
 vreg.register(SeeAlsoVComponent)
 # goa/appobjects/sessions.py
 def registration_callback(vreg):
 vreg.register(SessionsCleaner)
-vreg.register(GAEAuthenticationManager, clear=True)
+# replace AuthenticationManager by GAEAuthenticationManager
-vreg.register(GAEPersistentSessionManager, clear=True)
+vreg.register_and_replace(GAEAuthenticationManager, AuthenticationManager)
+# replace PersistentSessionManager by GAEPersistentSessionManager
+vreg.register_and_replace(GAEPersistentSessionManager, PersistentSessionManager)
-API d'enregistrement des objets
-```````````````````````````````
-.. sourcecode:: python
-register(obj, registryname=None, oid=None, clear=False)
-register_all(objects, modname, butclasses=())
-unregister(obj, registryname=None)
-register_and_replace(obj, replaced, registryname=None)
-register_if_interface_found(obj, ifaces, **kwargs)
 Runtime objects selection
 ~~~~~~~~~~~~~~~~~~~~~~~~~
-Defining selectors
+Using and combining existant selectors
-``````````````````
+``````````````````````````````````````
 The object's selector is defined by its `__select__` class attribute.
 When two selectors are combined using the `&` operator (formerly `chainall`), it
 means that both should return a positive score. On success, the sum of scores is returned.
 positive score is returned.
 Of course you can use paren to balance expressions.
-For instance, if you are selecting the primary (eg `id = 'primary'`) view (eg
+For instance, if you are selecting the primary (eg `__regid__ = 'primary'`) view (eg
 `__registry__ = 'view'`) for a result set containing a `Card` entity, 2 objects
 will probably be selectable:
 * the default primary view (`__select__ = implements('Any')`), meaning
 that the object is selectable for any kind of entity type
 stream url on AnyEntity
 * redefine this method on Blog.
 When to use selectors?
-```````````````````````
+``````````````````````
-Selectors are to be used whenever arises the need of dispatching on
+Selectors are to be used whenever arises the need of dispatching on the shape or
-the shape or content of a result set. That is, almost all the time.
+content of a result set or whatever else context (value in._cwuest form params,
+authenticated user groups, etc...). That is, almost all the time.
+XXX add and example of a single view w/ big "if" inside splitted into two views
+with appropriate selectors.
+Defining your own selectors
+```````````````````````````
+XXX objectify_selector, EntitySelector, EClassSelector...
 Debugging
 `````````
 Once in a while, one needs to understand why a view (or any AppObject)
 Here is an example:
 .. sourcecode:: python
-def possible_objects(self, registry, *args, **kwargs):
+from cubicweb.selectors import traced_selection
-"""return an iterator on possible objects in a registry for this result set
+with traced_selection():
+mycomp = self._cw.vreg['views'].select('wfhistory', self._cw, rset=rset)
-actions returned are classes, not instances
-"""
-from cubicweb.selectors import traced_selection
-with traced_selection():
-for vobjects in self.registry(registry).values():
-try:
-yield self.select(vobjects, *args, **kwargs)
-except NoSelectableObject:
-continue
 Don't forget the 'from __future__ import with_statement' at the module
-top-level.
+top-level if you're using python 2.5.
 This will yield additional WARNINGs in the logs, like this::
 2009-01-09 16:43:52 - (cubicweb.selectors) WARNING: selector one_line_rset returned 0 for <class 'cubicweb.web.views.basecomponents.WFHistoryVComponent'>
+Take care not filtering-out messages whose log level is <= LOG_WARNING!

changeset 4437	21f2e01fdd6a
parent 3581	669854258b90
child 4442	7bc0e4ed4109