diff options
| -rw-r--r-- | docs/narr/project.rst | 7 | ||||
| -rw-r--r-- | docs/narr/startup.rst | 10 | ||||
| -rw-r--r-- | docs/narr/urldispatch.rst | 20 |
3 files changed, 19 insertions, 18 deletions
diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 7f056d645..e0244360f 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -591,9 +591,10 @@ behavior. #. Line 4 defines an instance of MyModel as the root. -#. Line 6 is a function that will be called by the :mod:`repoze.bfg` - *Router* for each request when it wants to find the root of the model - graph. Conventionally this is called ``get_root``. +#. Line 6 is a "root factory" function that will be called by the + :mod:`repoze.bfg` *Router* for each request when it wants to find + the root of the model graph. Conventionally this is called + ``get_root``. In a "real" application, the root object would not be such a simple object. Instead, it would be an object that could access some diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index e12f0ef81..000f4d612 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -99,9 +99,9 @@ press ``return`` after running ``paster serve MyProject.ini``. .. literalinclude:: MyProject/myproject/run.py :linenos: - Note that the app function imports the ``get_root`` function from - the ``myproject.models`` Python module. It then also imports the - "bare" ``myproject`` package, and passes ``get_root``, + Note that the app function imports the ``get_root`` root factory + function from the ``myproject.models`` Python module. It then also + imports the "bare" ``myproject`` package, and passes ``get_root``, ``myproject``, and the result of ``get_options(kw)`` as the ``options`` keyword to the ``make_app`` function of the ``repoze.bfg.router`` module. @@ -120,8 +120,8 @@ press ``return`` after running ``paster serve MyProject.ini``. automatically reloaded by the application when they are changed. ``get_root`` is the first argument to ``make_app``, and it is a - callable that is invoked on every request to retrieve the - application root. It is not called during startup, only when a + root factory callable that is invoked on every request to retrieve + the application root. It is not called during startup, only when a request is handled. We pass in the bare ``myproject`` package so that the ``make_app`` diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 1e26aa52b..059326a15 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -52,21 +52,21 @@ allows you to inject ``route`` ZCML directives into your application's When any ``route`` ZCML directive is present in an application's ``configure.zcml``, "under the hood" :mod:`repoze.bfg` wraps the "root -factory" (aka ``get_root``) in a special ``RoutesRootFactory`` -instance. This instance then acts as the root factory. When it acts -as a root factory, it is willing to check the requested URL against a -*routes map* to find the :term:`context` and the :term:`view name` -before traversal has a chance to find it first. If it finds a context -and a view name via a route, :mod:`repoze.bfg` will attempt to look up -and call a :mod:`repoze.bfg` :term:`view` that matches the context and -the view name. If no route matches, :mod:`repoze.bfg` will fail over -to calling the ``get_root`` callable passed to the application in it's +factory" in a special ``RoutesRootFactory`` instance. The wrapper +instance then acts as the root factory. When it acts as a root +factory, it is willing to check the requested URL against a *routes +map* to find the :term:`context` and the :term:`view name` before +traversal has a chance to find it first. If it finds a context and a +view name via a route, :mod:`repoze.bfg` will attempt to look up and +call a :mod:`repoze.bfg` :term:`view` that matches the context and the +view name. If no route matches, :mod:`repoze.bfg` will fail over to +calling the root factory callable passed to the application in it's ``make_app`` function (usually a traversal function). By configuring your ZCML ``route`` statements appropriately, you can mix and match URL dispatch and traversal in this way. .. note:: See :ref:`modelspy_project_section` for an example of a - simple ``get_root`` callable that will use traversal. + simple root factory callable that will use traversal. The ``route`` ZCML Directive ---------------------------- |