From e62e479e338e428f6cfd3b07790545982b7cb94f Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 27 Jan 2009 21:57:11 +0000 Subject: Features -------- - The ``repoze.bfg.url.model_url`` API now works against contexts derived from Routes URL dispatch (``Routes.util.url_for`` is called under the hood). - "Virtual root" support for traversal-based applications has been added. Virtual root support is useful when you'd like to host some model in a :mod:`repoze.bfg` model graph as an application under a URL pathname that does not include the model path itself. For more information, see the (new) "Virtual Hosting" chapter in the documentation. - A ``repoze.bfg.traversal.virtual_root`` API has been added. When called, it returns the virtual root object (or the physical root object if no virtual root has been specified). Implementation Changes ---------------------- - ``repoze.bfg.traversal.RoutesModelTraverser`` has been moved to ``repoze.bfg.urldispatch``. - ``model_url`` URL generation is now performed via an adapter lookup based on the context and the request. - ZCML which registers two adapters for the ``IContextURL`` interface has been added to the configure.zcml in ``repoze.bfg.includes``. --- docs/narr/vhosting.rst | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 docs/narr/vhosting.rst (limited to 'docs/narr') diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst new file mode 100644 index 000000000..2cd1346e3 --- /dev/null +++ b/docs/narr/vhosting.rst @@ -0,0 +1,69 @@ +.. _vhosting_chapter: + +Virtual Hosting +=============== + +:mod:`repoze.bfg` supports a traditional form of virtual hosting +provided by packages like Paste's `urlmap +`_ middleware, where you +can host a :mod:`repoze.bfg` application as a "subset" of some other +site (e.g. ``http://example.com/mybfgapplication``). Nothing special +needs to be done within a :mod:`repoze.bfg` application to make this +work. + +However, :mod:`repoze.bfg` also supports "virtual roots", which can be +used in :term:`traversal` -based (but not :term:`URL-dispatch` -based) +applications. These are explained below. + +Virtual Root Support +-------------------- + +Virtual root support is useful when you'd like to host some model in a +:mod:`repoze.bfg` model graph as an application under a URL pathname +that does not include the model path itself. For example, you might +want to serve the object at the traversal path ``/cms`` as an +application on reachable via ``http://example.com/`` (as opposed to +``http://example.com/cms``). To specify a virtual root, cause an +environment variable to be inserted into the WSGI environ named +``HTTP_X_VHM_ROOT`` with a value that is the absolute pathname to the +model object in the traversal graph that should behave as the "root" +model. As a result, the traversal machinery will respect this value +during traversal (prepending it to the PATH_INFO before traversal +starts), and the ``repoze.bfg.url.model_url`` API will generate the +"correct" virtually-rooted URLs. + +An example of an Apache ``mod_proxy`` configuration that will host the +``/cms`` subobject as ``http://www.example.com/`` using this facility +is below: + +.. code-block:: xml + + NameVirtualHost *:80 + + + ServerName www.example.com + RewriteEngine On + RewriteRule ^/(.*) http://127.0.0.1:6543/$1 [L,P] + ProxyPreserveHost on + RequestHeader add X-Vhm-Root /cms + + +For a :mod:`repoze.bfg` application running under ``mod_wsgi``, the +same can be achieved using ``SetEnv``: + +.. code-block:: xml + + + SetEnv HTTP_X_VHM_ROOT /cms + + +Setting a virtual root has no effect when using an application based +on :term:`URL dispatch`. + +Further Documentation and Examples +---------------------------------- + +The API documentation in :ref:`traversal_module` documents a +``repoze.bfg.traversal.virtual_root`` API. When called, it returns +the virtual root object (or the physical root object if no virtual +root has been specified). -- cgit v1.2.3