diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/glossary.rst | 46 | ||||
| -rw-r--r-- | docs/narr/introduction.rst | 71 | ||||
| -rw-r--r-- | docs/narr/views.rst | 4 |
3 files changed, 81 insertions, 40 deletions
diff --git a/docs/glossary.rst b/docs/glossary.rst index b045a1232..528522e16 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -72,10 +72,15 @@ Glossary in your :mod:`repoze.bfg` application, you are using URL dispatch. See the :ref:`urldispatch_module` for more information. Context - A :term:`model` in the system that is "found" during - :term:`traversal` or :term:`URL dispatch`; it becomes the subject - of a :term:`view`. See the :ref:`traversal_chapter` chapter for - more information. + A object in the system that is found during :term:`traversal` or + :term:`URL dispatch` based on URL data; if it's found via + traversal, it's usually a :term:`model` object; if it's found via + :term:`URL dispatch`, it's a manufactured context object that + contains routing information. A context becomes the subject of a + :term:`view`, and typically has security information attached to + it. See the :ref:`traversal_chapter` chapter and the + :ref:`urldispatch_chapter` chapter for more information about how + a URL is resolved to a context. Application registry A registry which maps model types to views, as well as performing other application-specific component registrations. Every @@ -175,8 +180,14 @@ Glossary An `Apache module <http://code.google.com/p/modwsgi/>`_ for hosting Python WSGI applications. Zope - `The Z Object Publishing Framework <http://zope.org>`_. The granddaddy - of Python web frameworks. + `The Z Object Publishing Framework <http://zope.org>`_, a + full-featured Python web framework. + Grok + `A web framework based on Zope 3 <http://grok.zope.org>`_. + Django + `A full-featured Python web framework <http://djangoproject.com>`_. + Pylons + `A lightweight Python web framework <http://pylonshq.com>`_. ZODB `Zope Object Database <http://wiki.zope.org/ZODB/FrontPage>`_, a persistent Python object store. @@ -243,8 +254,9 @@ Glossary :mod:`repoze.bfg` is to perform view mappings via the ``view`` declaration. The ``configure.zcml`` file in a :mod:`repoze.bfg` application represents the application's :term:`application - registry`. See :term:`repoze.bfg.convention` for an alternative - to ZCML for application configuration. + registry`. You can also use decorators to configure views in + :mod:`repoze.bfg`; see + :ref:`mapping_views_to_urls_using_a_decorator_section`. ReStructuredText A `plain text format <http://docutils.sourceforge.net/rst.html>`_ that is the defacto standard for descriptive text shipped in @@ -259,13 +271,14 @@ Glossary or a request object in order to identify that the object is "of a type". Interfaces are used internally by :mod:`repoze.bfg` to perform view lookups and security policy lookups. Interfaces are - exposed to application programmers by the ``view`` ZCML - directive in the form of both the ``for_`` attribute and the - ``request_type`` attribute. They may be exposed to application - developers when using the :term:`event` system as - well. 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". Interfaces can also be used to describe + exposed to application programmers by the ``view`` ZCML directive + or the corresponding ``bfg_view`` decorator in the form of both + the ``for`` attribute and the ``request_type`` attribute. They + may be exposed to application developers when using the + :term:`event` system as well. 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. In other words, bfg @@ -320,4 +333,5 @@ Glossary `An add-on for repoze.bfg <http://static.repoze.org/conventiondocs>`_ which provides alternative mechanisms for common :mod:`repoze.bfg` application - configuration tasks. Useful for the :term:`ZCML` -allergic. + configuration tasks. The functionality of this package has been + merged into the :mod:`repoze.bfg` core as of version 0.6.3. diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index bf2e29be1..836f57c44 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -7,30 +7,29 @@ work. However, it simpler than any than any released version of Zope. :mod:`repoze.bfg` uses the :term:`WSGI` protocol to handle requests and responses. -Similarities with Other Frameworks ----------------------------------- - -:mod:`repoze.bfg` was inspired by Zope, Django, and Pylons. - -:mod:`repoze.bfg` traversal is inspired by Zope. :mod:`repoze.bfg` -uses the Zope Component Architecture ("CA") internally, as do Zope 2, -Zope 3, and Grok. Developers don't interact with the CA very much -during typical development, however; it's mostly used by the framework -developer rather than the application developer. :mod:`repoze.bfg` -developers use :term:`ZCML` (an XML dialect) or decorators to perform -various configuration tasks; in particular, as in Zope3, one more more -:term:`view` functions is associated with a :term:`model` type via -ZCML or a decorator. - -Like Pylons, :mod:`repoze.bfg` is mostly policy-free. It makes no -assertions about which database you should use, and its built-in -templating facilities are only for convenience. In essence, it only -supplies a mechanism to map URLs to :term:`view` code, along with a -convention for calling those views. You are free to use third-party -components in your application that fit your needs. Also like Pylons, -:mod:`repoze.bfg` is heavily dependent on WSGI. - -The Django docs state that Django is an "MTV" framework in their `FAQ +Similarities to Other Frameworks +-------------------------------- + +:mod:`repoze.bfg` was inspired by :term:`Zope`, :term:`Django`, and +:term:`Pylons`. + +The :mod:`repoze.bfg` concept of traversal is inspired by +:term:`Zope`. Additionally, :mod:`repoze.bfg` uses the Zope Component +Architecture ("CA") internally, as do Zope 2, Zope 3, and +:term:`Grok`. Application :mod:`repoze.bfg` developers use either +:term:`ZCML` (an XML dialect, used in Zope) or decorators to perform +various configuration tasks. The decorator support is provided by the +:term:`Grok` project. + +Like :term:`Pylons`, :mod:`repoze.bfg` is mostly policy-free. It +makes no assertions about which database you should use, and its +built-in templating facilities are only for convenience. In essence, +it only supplies a mechanism to map URLs to :term:`view` code, along +with a convention for calling those views. You are free to use +third-party components in your application that fit your needs. Also +like Pylons, :mod:`repoze.bfg` is heavily dependent on WSGI. + +The "Django docs state that Django is an "MTV" framework in their `FAQ <http://www.djangoproject.com/documentation/faq/>`_. This also happens to be true for :mod:`repoze.bfg`:: @@ -72,6 +71,30 @@ Django. To learn more about the concepts used by :mod:`repoze.bfg`, visit the :ref:`glossary` for a listing of definitions. +Differences from Other Frameworks +--------------------------------- + +Like :term:`Zope`, the :mod:`repoze.bfg` framework imposes slightly +more `control inversion <http://plope.com/control_inversion>`_ upon +application developers than other Python frameworks such as +:term:`Pylons`. For example :mod:`repoze.bfg` assumes that you're +wiling to resolve a URL to a :term:`context` object before passing it +to a :term:`view`. Pylons and other Python "MVC" frameworks have no +such intermediate step; they resolve a URL directly to a controller. +Another example: using the :mod:`repoze.bfg` security subsystem +assumes that you're willing to attach an :term:`ACL` to a +:term:`context` object; the ACL is checked by the framework itself +instead of by user code, and access is permitted or denied by the +framework itself rather than by user code. Such a task would +typically be performed by user-space decorators in other Python web +frameworks. + +Unlike application development using Zope, application developers +don't interact with the Zope Component Architecture ("CA") very much +during :mod:`repoze.bfg` application development. Instead, the +:mod:`repoze.bfg` framework tends to "hide" most interaction with the +CA behind special-purpose API functions. + Why? ---- diff --git a/docs/narr/views.rst b/docs/narr/views.rst index edbe03d82..6eb42a0cd 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -61,6 +61,8 @@ If a view happens to return something to the :mod:`repoze.bfg` publisher that does not implement this interface, the publisher will raise an error. +.. _mapping_views_to_urls_using_zcml_section: + Mapping Views to URLs Using ZCML -------------------------------- @@ -159,6 +161,8 @@ request_type called. See :ref:`view_request_types_section` for more information about view security and permissions. +.. _mapping_views_to_urls_using_a_decorator_section: + Mapping Views to URLs Using a Decorator --------------------------------------- |