From eecdbc34962b00e35d41039af014462cf558acee Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 3 Jan 2010 03:39:30 +0000 Subject: Features -------- - The ``Configurator.add_view`` method now accepts an argument named ``context``. This is an alias for the older argument named ``for_``; it is preferred over ``for_``, but ``for_`` will continue to be supported "forever". - The ``view`` ZCML directive now accepts an attribute named ``context``. This is an alias for the older attribute named ``for``; it is preferred over ``for``, but ``for`` will continue to be supported "forever". - The ``Configurator.add_route`` method now accepts an argument named ``view_context``. This is an alias for the older argument named ``view_for``; it is preferred over ``view_for``, but ``view_for`` will continue to be supported "forever". - The ``route`` ZCML directive now accepts an attribute named ``view_context``. This is an alias for the older attribute named ``view_for``; it is preferred over ``view_for``, but ``view_for`` will continue to be supported "forever". Documentation and Paster Templates ---------------------------------- - All uses of the ``Configurator.add_view`` method that used its ``for_`` argument now use the ``context``argument instead. - All uses of the ``Configurator.add_route`` method that used its ``view_for`` argument now use the ``view_context``argument instead. - All uses of the ``view`` ZCML directive that used its ``for`` attribute now use the ``context`` attribute instead. - All uses of the ``route`` ZCML directive that used its ``view_for`` attribute now use the ``view_context`` attribute instead. --- docs/designdefense.rst | 6 +- docs/glossary.rst | 16 ++-- docs/narr/MyProject/myproject/configure.zcml | 2 +- docs/narr/extending.rst | 4 +- docs/narr/hooks.rst | 10 +-- docs/narr/hybrid.rst | 13 ++-- docs/narr/project.rst | 9 ++- docs/narr/security.rst | 4 +- docs/narr/views.rst | 90 +++++++++++----------- docs/tutorials/bfgwiki/basiclayout.rst | 13 ++-- .../bfgwiki/src/authorization/tutorial/login.py | 4 +- .../bfgwiki/src/authorization/tutorial/views.py | 8 +- .../src/basiclayout/tutorial/configure.zcml | 2 +- .../bfgwiki/src/models/tutorial/configure.zcml | 2 +- .../bfgwiki/src/viewdecorators/tutorial/views.py | 8 +- .../bfgwiki/src/views/tutorial/configure.zcml | 8 +- docs/tutorials/bfgwiki/viewdecorators.rst | 41 +++++----- docs/zcml.rst | 15 ++-- 18 files changed, 132 insertions(+), 123 deletions(-) (limited to 'docs') diff --git a/docs/designdefense.rst b/docs/designdefense.rst index e4ce4f56d..296589c62 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -655,9 +655,9 @@ administrative interface), you can register a route like ```` and then associate "management" views in your code by using the ``route_name`` argument to a ``view`` configuration, e.g. ````. If you wire things up this -way someone then walks up to for example, ``/manage/ob1/ob2``, they -might be presented with a management interface, but walking up to +context=".some.Model" route_name="manage"/>``. If you wire things up +this way someone then walks up to for example, ``/manage/ob1/ob2``, +they might be presented with a management interface, but walking up to ``/ob1/ob2`` would present them with the default object view. There are other tricks you can pull in these hybrid configurations if you're clever (and maybe masochistic) too. diff --git a/docs/glossary.rst b/docs/glossary.rst index e649b3498..c8c07ebb4 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -409,16 +409,16 @@ Glossary internally by :mod:`repoze.bfg` to perform view lookups and other policy lookups. The ability to make use of an interface is exposed to an application programmers during :term:`view - configuration` via the ``for`` argument, the ``request_type`` + configuration` via the ``context`` argument, the ``request_type`` argument and the ``containment`` argument. Interfaces are also exposed to application developers when they make use of the - :term:`event` system. Fundamentally, :mod:`repoze.bfg` programmers - can think of an interface as something that they can attach to an - object that stamps it with a "type" unrelated to its underlying - Python type. Interfaces can also be used to describe the behavior - of an object (its methods and attributes), but unless they choose - to, :mod:`repoze.bfg` programmers do not need to understand or use - this feature of interfaces. + :term:`event` system. Fundamentally, :mod:`repoze.bfg` + programmers can think of an interface as something that they can + attach to an object that stamps it with a "type" unrelated to its + underlying Python type. Interfaces can also be used to describe + the behavior of an object (its methods and attributes), but + unless they choose to, :mod:`repoze.bfg` programmers do not need + to understand or use this feature of interfaces. event An object broadcast to zero or more :term:`subscriber` callables diff --git a/docs/narr/MyProject/myproject/configure.zcml b/docs/narr/MyProject/myproject/configure.zcml index fe9633fe1..95b7355b1 100644 --- a/docs/narr/MyProject/myproject/configure.zcml +++ b/docs/narr/MyProject/myproject/configure.zcml @@ -3,7 +3,7 @@ diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst index 0f9bc433d..0b2d5a876 100644 --- a/docs/narr/extending.rst +++ b/docs/narr/extending.rst @@ -181,7 +181,7 @@ Overriding Views ~~~~~~~~~~~~~~~~~ The ZCML ```` declarations you make which *override* application -behavior will usually have the same ``for`` and ``name`` (and +behavior will usually have the same ``context`` and ``name`` (and :term:`predicate` attributes, if used) as the original. These ```` declarations will point at "new" view code. The new view code itself will usually be cut-n-paste copies of view callables from @@ -190,7 +190,7 @@ the original application with slight tweaks. For example: .. code-block:: xml :linenos: - diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 990290744..47495b68c 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -225,11 +225,11 @@ a class that implements the following interface: More than one traversal algorithm can be active at the same time. For instance, if your :term:`root factory` returns more than one type of -object conditionally, you could claim that an alternate traverser is -``for`` only one particular class or interface. When the root factory -returned an object that implemented that class or interface, a custom -traverser would be used. Otherwise, the default traverser would be -used. For example: +object conditionally, you could claim that an alternate traverser +adapter is ``for`` only one particular class or interface. When the +root factory returned an object that implemented that class or +interface, a custom traverser would be used. Otherwise, the default +traverser would be used. For example: .. code-block:: xml :linenos: diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst index 14cb1d4ab..5c3775e59 100644 --- a/docs/narr/hybrid.rst +++ b/docs/narr/hybrid.rst @@ -361,12 +361,13 @@ then both the request type and the context type are "more specific" for the view registration). What it all boils down to is: if a request that matches a route -resolves to a view you don't expect it to, use the ``view_for`` -attribute of the ``route`` statement (*or* the ``for`` attribute of -the ZCML statement that also has a ``route_name`` *or* the equivalent -``for_`` parameter to the :class:`repoze.bfg.view.bfg_view` decorator -that also has a ``route_name`` parameter) to name the specific context -interface you want the route-related view to match. +resolves to a view you don't expect it to, use the ``view_context`` +attribute of the ``route`` statement (*or* the ``context`` attribute +of the ZCML statement that also has a ``route_name`` *or* the +equivalent ``context`` parameter to the +:class:`repoze.bfg.view.bfg_view` decorator that also has a +``route_name`` parameter) to name the specific context interface you +want the route-related view to match. Yes, that was as painful for me to write as it was for you to read. diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 41b0bce02..02d9e30ba 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -603,12 +603,13 @@ the :term:`application registry`. It looks like so: in this file. #. Lines 6-10 register a "default view" (a view that has no ``name`` - attribute). It is ``for`` model objects that are instances of the + attribute). It is registered so that it will be found when the + :term:`context` of the request is an instance of the :class:`myproject.models.MyModel` class. The ``view`` attribute points at a Python function that does all the work for this view. - Note that the values of both the ``for`` attribute and the ``view`` - attribute begin with a single period. Names that begin with a - period are "shortcuts" which point at files relative to the + Note that the values of both the ``context`` attribute and the + ``view`` attribute begin with a single period. Names that begin + with a period are "shortcuts" which point at files relative to the :term:`package` in which the ``configure.zcml`` file lives. In this case, since the ``configure.zcml`` file lives within the :mod:`myproject` package, the shortcut ``.models.MyModel`` could diff --git a/docs/narr/security.rst b/docs/narr/security.rst index e83e2f8b8..4c86c7f5e 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -125,7 +125,7 @@ when invoked against a ``Blog`` context with the ``add`` permission: :linenos: @@ -320,18 +320,18 @@ The above maps the ``.views.hello_world`` view function to Python class represented by ``.models.Hello`` when the *view name* is ``hello.html``. -.. note:: Values prefixed with a period (``.``) for the ``for`` and - ``view`` attributes of a ``view`` (such as those above) mean +.. note:: Values prefixed with a period (``.``) for the ``context`` + and ``view`` attributes of a ``view`` (such as those above) mean "relative to the Python package directory in which this - :term:`ZCML` file is stored". So if the above ``view`` - declaration was made inside a ``configure.zcml`` file that lived in - the ``hello`` package, you could replace the relative - ``.models.Hello`` with the absolute ``hello.models.Hello``; - likewise you could replace the relative ``.views.hello_world`` with - the absolute ``hello.views.hello_world``. Either the relative or - absolute form is functionally equivalent. It's often useful to use - the relative form, in case your package's name changes. It's also - shorter to type. + :term:`ZCML` file is stored". So if the above ``view`` declaration + was made inside a ``configure.zcml`` file that lived in the + ``hello`` package, you could replace the relative ``.models.Hello`` + with the absolute ``hello.models.Hello``; likewise you could + replace the relative ``.views.hello_world`` with the absolute + ``hello.views.hello_world``. Either the relative or absolute form + is functionally equivalent. It's often useful to use the relative + form, in case your package's name changes. It's also shorter to + type. You can also declare a *default view* for a model type: @@ -339,7 +339,7 @@ You can also declare a *default view* for a model type: :linenos: @@ -348,13 +348,13 @@ found and there is no *view name* associated with the result of :term:`traversal`, the *default view* is the view that is used. You can also declare that a view is good for any model type by using -the special ``*`` character in the ``for`` attribute: +the special ``*`` character in the ``context`` attribute: .. code-block:: xml :linenos: @@ -381,7 +381,7 @@ For better locality of reference, use the :class:`repoze.bfg.view.bfg_view` decorator to associate your view functions with URLs instead of using :term:`ZCML` for the same purpose. :class:`repoze.bfg.view.bfg_view` can be used to associate -``for``, ``name``, ``permission`` and ``request_method``, +``context``, ``name``, ``permission`` and ``request_method``, ``containment``, ``request_param`` and ``request_type``, ``attr``, ``renderer``, ``wrapper``, ``xhr``, ``accept``, and ``header`` information -- as done via the equivalent ZCML -- with a function that @@ -449,7 +449,7 @@ An example might reside in a bfg application module ``views.py``: from repoze.bfg.view import bfg_view from repoze.bfg.chameleon_zpt import render_template_to_response - @bfg_view(name='my_view', request_method='POST', for_=MyModel, + @bfg_view(name='my_view', request_method='POST', context=MyModel, permission='read', renderer='templates/my.pt') def my_view(request): return {'a':1} @@ -461,7 +461,7 @@ your application registry: :linenos: @@ -922,7 +924,7 @@ You can configure a view to use the JSON renderer in ZCML by naming :linenos: @@ -1469,11 +1471,11 @@ object. For example (ZCML): In this case, ``.models.Root`` refers to the class of which your :mod:`repoze.bfg` application's root object is an instance. -.. note:: You can also give a ``for`` of ``*`` if you want the name - ``static`` to be accessible as the static view against any model. - This will also allow ``/static/foo.js`` to work, but it will allow - for ``/anything/static/foo.js`` too, as long as ``anything`` itself - is resolvable. +.. note:: You can also give a ``context`` of ``*`` if you want the + name ``static`` to be accessible as the static view against any + model. This will also allow ``/static/foo.js`` to work, but it + will allow for ``/anything/static/foo.js`` too, as long as + ``anything`` itself is resolvable. .. note:: To ensure that model objects contained in the root don't "shadow" your static view (model objects take precedence during diff --git a/docs/tutorials/bfgwiki/basiclayout.rst b/docs/tutorials/bfgwiki/basiclayout.rst index 5934799b9..f0bf8ced8 100644 --- a/docs/tutorials/bfgwiki/basiclayout.rst +++ b/docs/tutorials/bfgwiki/basiclayout.rst @@ -30,12 +30,13 @@ following: #. *Line 4*. Boilerplate, the comment explains. -#. *Lines 6-10*. Register a ```` that is ``for`` a class. - ``.views.my_view`` is a *function* we write (generated by the - ``bfg_zodb`` template) that is given a ``context`` and a - ``request`` and which returns a dictionary. The ``renderer`` tag - indicates that the ``templates/mytemplate.pt`` template should be - used to turn the dictionary returned by the view into a response. +#. *Lines 6-10*. Register a ```` that names a ``context`` type + that is a class. ``.views.my_view`` is a *function* we write + (generated by the ``bfg_zodb`` template) that is given a + ``context`` object and a ``request`` and which returns a + dictionary. The ``renderer`` tag indicates that the + ``templates/mytemplate.pt`` template should be used to turn the + dictionary returned by the view into a response. ``templates/mytemplate.pt`` is a *relative* path: it names the ``mytemplate.pt`` file which lives in the ``templates`` subdirectory of the directory in which this ``configure.zcml`` diff --git a/docs/tutorials/bfgwiki/src/authorization/tutorial/login.py b/docs/tutorials/bfgwiki/src/authorization/tutorial/login.py index d9d65bdca..08b3db359 100644 --- a/docs/tutorials/bfgwiki/src/authorization/tutorial/login.py +++ b/docs/tutorials/bfgwiki/src/authorization/tutorial/login.py @@ -9,7 +9,7 @@ from repoze.bfg.security import forget from tutorial.models import Wiki from tutorial.security import USERS -@bfg_view(for_=Wiki, name='login', renderer='templates/login.pt') +@bfg_view(context=Wiki, name='login', renderer='templates/login.pt') def login(context, request): login_url = model_url(context, request, 'login') referrer = request.url @@ -36,7 +36,7 @@ def login(context, request): password = password, ) -@bfg_view(for_=Wiki, name='logout') +@bfg_view(context=Wiki, name='logout') def logout(context, request): headers = forget(request) return HTTPFound(location = model_url(context, request), diff --git a/docs/tutorials/bfgwiki/src/authorization/tutorial/views.py b/docs/tutorials/bfgwiki/src/authorization/tutorial/views.py index 26a44fcda..17ca01566 100644 --- a/docs/tutorials/bfgwiki/src/authorization/tutorial/views.py +++ b/docs/tutorials/bfgwiki/src/authorization/tutorial/views.py @@ -14,11 +14,11 @@ from tutorial.models import Wiki # regular expression used to find WikiWords wikiwords = re.compile(r"\b([A-Z]\w+[A-Z]+\w+)") -@bfg_view(for_=Wiki, permission='view') +@bfg_view(context=Wiki, permission='view') def view_wiki(context, request): return HTTPFound(location = model_url(context, request, 'FrontPage')) -@bfg_view(for_=Page, renderer='templates/view.pt', permission='view') +@bfg_view(context=Page, renderer='templates/view.pt', permission='view') def view_page(context, request): wiki = context.__parent__ @@ -41,7 +41,7 @@ def view_page(context, request): return dict(page = context, content = content, edit_url = edit_url, logged_in = logged_in) -@bfg_view(for_=Wiki, name='add_page', renderer='templates/edit.pt', +@bfg_view(context=Wiki, name='add_page', renderer='templates/edit.pt', permission='edit') def add_page(context, request): name = request.subpath[0] @@ -61,7 +61,7 @@ def add_page(context, request): return dict(page = page, save_url = save_url, logged_in = logged_in) -@bfg_view(for_=Page, name='edit_page', renderer='templates/edit.pt', +@bfg_view(context=Page, name='edit_page', renderer='templates/edit.pt', permission='edit') def edit_page(context, request): if 'form.submitted' in request.params: diff --git a/docs/tutorials/bfgwiki/src/basiclayout/tutorial/configure.zcml b/docs/tutorials/bfgwiki/src/basiclayout/tutorial/configure.zcml index e15d3a65d..04e7d908d 100644 --- a/docs/tutorials/bfgwiki/src/basiclayout/tutorial/configure.zcml +++ b/docs/tutorials/bfgwiki/src/basiclayout/tutorial/configure.zcml @@ -4,7 +4,7 @@ diff --git a/docs/tutorials/bfgwiki/src/models/tutorial/configure.zcml b/docs/tutorials/bfgwiki/src/models/tutorial/configure.zcml index 867b9020c..149eff13d 100644 --- a/docs/tutorials/bfgwiki/src/models/tutorial/configure.zcml +++ b/docs/tutorials/bfgwiki/src/models/tutorial/configure.zcml @@ -4,7 +4,7 @@ diff --git a/docs/tutorials/bfgwiki/src/viewdecorators/tutorial/views.py b/docs/tutorials/bfgwiki/src/viewdecorators/tutorial/views.py index a5d8f6b6a..08489f4ef 100644 --- a/docs/tutorials/bfgwiki/src/viewdecorators/tutorial/views.py +++ b/docs/tutorials/bfgwiki/src/viewdecorators/tutorial/views.py @@ -11,11 +11,11 @@ from tutorial.models import Wiki # regular expression used to find WikiWords wikiwords = re.compile(r"\b([A-Z]\w+[A-Z]+\w+)") -@bfg_view(for_=Wiki) +@bfg_view(context=Wiki) def view_wiki(context, request): return HTTPFound(location = model_url(context, request, 'FrontPage')) -@bfg_view(for_=Page, renderer='templates/view.pt') +@bfg_view(context=Page, renderer='templates/view.pt') def view_page(context, request): wiki = context.__parent__ @@ -34,7 +34,7 @@ def view_page(context, request): edit_url = model_url(context, request, 'edit_page') return dict(page = context, content = content, edit_url = edit_url) -@bfg_view(for_=Wiki, name='add_page', renderer='templates/edit.pt') +@bfg_view(context=Wiki, name='add_page', renderer='templates/edit.pt') def add_page(context, request): name = request.subpath[0] if 'form.submitted' in request.params: @@ -50,7 +50,7 @@ def add_page(context, request): page.__parent__ = context return dict(page = page, save_url = save_url) -@bfg_view(for_=Page, name='edit_page', renderer='templates/edit.pt') +@bfg_view(context=Page, name='edit_page', renderer='templates/edit.pt') def edit_page(context, request): if 'form.submitted' in request.params: context.data = request.params['body'] diff --git a/docs/tutorials/bfgwiki/src/views/tutorial/configure.zcml b/docs/tutorials/bfgwiki/src/views/tutorial/configure.zcml index 038677bfc..d265d63e4 100644 --- a/docs/tutorials/bfgwiki/src/views/tutorial/configure.zcml +++ b/docs/tutorials/bfgwiki/src/views/tutorial/configure.zcml @@ -9,25 +9,25 @@ /> @@ -75,18 +76,18 @@ The decorator above the ``view_page`` function will be: .. code-block:: python :linenos: - @bfg_view(for_=Page, renderer='templates/view.pt') + @bfg_view(context=Page, renderer='templates/view.pt') -This indicates that the view is "for" the Page class and has the -*empty* view_name (indicating the :term:`default view` for the Page -class). After injecting this decorator, we can now *remove* the -following from our ``configure.zcml`` file: +This indicates that the view is for the Page class and has the *empty* +view_name (indicating the :term:`default view` for the Page class). +After injecting this decorator, we can now *remove* the following from +our ``configure.zcml`` file: .. code-block:: xml :linenos: @@ -102,9 +103,9 @@ The decorator above the ``add_page`` function will be: .. code-block:: python :linenos: - @bfg_view(for_=Wiki, name='add_page', renderer='templates/edit.pt') + @bfg_view(context=Wiki, name='add_page', renderer='templates/edit.pt') -This indicates that the view is "for" the Wiki class and has the +This indicates that the view is for the Wiki class and has the ``add_page`` view_name. After injecting this decorator, we can now *remove* the following from our ``configure.zcml`` file: @@ -112,7 +113,7 @@ This indicates that the view is "for" the Wiki class and has the :linenos: @@ -453,7 +455,7 @@ Examples :linenos: @@ -602,7 +604,7 @@ Attributes .. note:: This feature is new as of :mod:`repoze.bfg` 1.2. -``view_for`` +``view_context`` The :term:`dotted Python name` to a class or an interface that the :term:`context` of the view should match for the view named by the @@ -613,7 +615,8 @@ Attributes If the ``view`` attribute is not provided, this attribute has no effect. - This attribute can also be spelled as ``for``. + This attribute can also be spelled as ``view_for`` or ``for_``; + these are valid older spellings. ``view_permission`` -- cgit v1.2.3