repoze.bfg.convention
=====================

Optional "convention over configuration" for ``repoze.bfg``.
``repoze.bfg.convention`` allows developers to make application
registry registrations within their application's Python instead of
using ZCML for the same purpose.

To make use of any convention declarations, you must insert the
following boilerplate into your application's ``configure.zcml``::

  <include package="repoze.bfg.convention" file="meta.zcml"/>
  <bfg:convention package="."/>

After you do so, you will not need to use any other ZCML to configure
most ``repoze.bfg`` application registry directives in your
application.  Instead, you will use decorators to do this work.

Note that this package tends to slows down application startup, as the
application registry is not capable of being cached within a
``.cache`` file when this package is in use, and more work is
performed at startup to scan for registrations.

``bfg_view`` Declaration Decorator
----------------------------------

``repoze.bfg.convention.bfg_view`` is a decorator which allows Python
code to make view registrations instead of using ZCML for the same
purpose.

E.g. in a bfg application module ``views.py``::

  from models import IMyModel
  from repoze.bfg.interfaces import IRequest
  from repoze.bfg.convention import bfg_view

  @bfg_view(name='my_view', request_type=IRequest, for_=IMyModel,
            permission='read'))
  def my_view(context, request):
      return render_template_to_response('templates/my.pt')

Using this decorator as above replaces the need to add this ZCML to
your application registry::

  <view
   for='.models.IMyModel'
   view='.views.my_view'
   name='my_view'
   permission='read'
   />

If ``name`` is not supplied, the empty string is used (implying
the default view).

If ``request_type`` is not supplied, the interface
``repoze.bfg.interfaces.IRequest`` is used.

If ``for_`` is not supplied, the interface
``zope.interface.Interface`` (which matches any model) is used.
``for_`` can also name a class, like its ZCML brother.

If ``permission`` is not supplied, no permission is registered for
this view (it's accessible by any caller).

Any individual or all parameters can be omitted.  The simplest
bfg_view declaration then becomes::

    @bfg_view()
    def my_view(...):
        ...

Such a registration implies that the view name will be ``my_view``,
registered for models with the ``zope.interface.Interface`` interface
(which matches anything), using no permission, registered against
requests which implement the default IRequest interface.

Installation
------------

Install using setuptools, e.g. (within a virtualenv)::

  $ easy_install -i http://dist.repoze.org/lemonade/dev/simple \
     repoze.bfg.convention

Reporting Bugs / Development Versions
-------------------------------------

Visit http://bugs.repoze.org to report bugs.  Visit
http://svn.repoze.org to download development or tagged versions.

Indices and tables
------------------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`