.. _zcml_directives: ZCML Directives ---------------- :term:`ZCML` is an XML dialect that may be used by a :mod:`repoze.bfg` application to perform :term:`declarative configuration`. Each :term:`ZCML directive` supplied by :mod:`repoze.bfg` is documented in this chapter. .. _configure_directive: ``configure`` ------------- Because :term:`ZCML` is XML, and because XML requires a single root tag for each document, every ZCML file used by :mod:`repoze.bfg` must contain a ``configure`` container directive, which acts as the root XML tag. It is a "container" directive because its only job is to contain other directives. Attributes ~~~~~~~~~~ ``xmlns`` The default XML namespace used for subdirectives. Example ~~~~~~~ .. code-block:: xml :linenos: .. _word_on_xml_namespaces: A Word On XML Namespaces ~~~~~~~~~~~~~~~~~~~~~~~~ Usually, the start tag of the ```` container tag has a default *XML namespace* associated with it. This is usually ``http://namespaces.repoze.org/bfg``, named by the ``xmlns`` attribute of the ``configure`` start tag. Using the ``http://namespaces.repoze.org/bfg`` namespace as the default XML namespace isn't strictly necessary; you can use a different default namespace as the default. However, if you do, the declaration tags which are defined by :mod:`repoze.bfg` such as the ``view`` declaration tag will need to be defined in such a way that the XML parser that :mod:`repoze.bfg` uses knows which namespace the :mod:`repoze.bfg` tags are associated with. For example, the following files are all completely equivalent: .. topic:: Use of A Non-Default XML Namespace .. code-block:: xml :linenos: .. topic:: Use of A Per-Tag XML Namespace Without A Default XML Namespace .. code-block:: xml :linenos: For more information about XML namespaces, see `this older, but simple XML.com article `_. The conventions in this document assume that the default XML namespace is ``http://namespaces.repoze.org/bfg``. Alternatives ~~~~~~~~~~~~ None. See Also ~~~~~~~~ See also :ref:`helloworld_declarative`. .. _include_directive: ``include`` ----------- The ``include`` directive includes configuration from an external ZCML file. Use of the ``include`` tag allows a user to split configuration across multiple ZCML files, and allows package distributors to provide default ZCML configuration for specific purposes which can be included by the integrator of the package as necessary. Attributes ~~~~~~~~~~ ``package`` A :term:`dotted Python name` which references a Python :term:`package`. ``filename`` An absolute or relative filename which references a ZCML file. The ``package`` and ``filename`` attributes can be used together or separately as necessary. Examples ~~~~~~~~ .. topic:: Loading the File Named ``configure.zcml`` from a Package Implicitly .. code-block:: xml :linenos: .. topic:: Loading the File Named ``other.zcml`` From the Current Package .. code-block:: xml :linenos: .. topic:: Loading a File From a Subdirectory of the Current Package .. code-block:: xml :linenos: .. topic:: Loading the File Named ``/absolute/path/other.zcml`` .. code-block:: xml :linenos: .. topic:: Loading the File Named ``other.zcml`` From a Package Explicitly .. code-block:: xml :linenos: Alternatives ~~~~~~~~~~~~ None. See Also ~~~~~~~~ See also :ref:`helloworld_declarative`. .. _view_directive: ``view`` -------- A ``view`` declaration directs :mod:`repoze.bfg` to create a single :term:`view configuration` registration in the current :term:`application registry`. The ``view`` ZCML directive has many possible attributes. Some of the attributes are descriptive or influence rendering. Other attributes are :term:`predicate` attributes, meaning that they imply an evaluation to true or false when view lookup is performed. *All* predicates named in a view configuration must evaluate to true in order for the view callable it names to be considered "invokable" for a given request. See :ref:`view_lookup_ordering` for a description of how a view configuration matches (or doesn't match) during a request. The possible attributes of the ``view`` ZCML directive are described below. They are divided into predicate and non-predicate categories. Attributes ~~~~~~~~~~ Non-Predicate Attributes ######################## ``view`` The :term:`dotted Python name` to a :term:`view callable`. This attribute is required unless a ``renderer`` attribute also exists. If a ``renderer`` attribute exists on the directive, this attribute defaults to a view that returns an empty dictionary (see :ref:`views_which_use_a_renderer`). ``permission`` The name of a *permission* that the user must possess in order to call the view. See :ref:`view_security_section` for more information about view security and permissions. ``attr`` The view machinery defaults to using the ``__call__`` method of the view callable (or the function itself, if the view callable is a function) to obtain a response dictionary. The ``attr`` value allows you to vary the method attribute used to obtain the response. For example, if your view was a class, and the class has a method named ``index`` and you wanted to use this method instead of the class' ``__call__`` method to return the response, you'd say ``attr="index"`` in the view configuration for the view. This is most useful when the view definition is a class. .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``renderer`` This is either a single string term (e.g. ``json``) or a string implying a path or :term:`resource specification` (e.g. ``templates/views.pt``). If the renderer value is a single term (does not contain a dot ``.``), the specified term will be used to look up a renderer implementation, and that renderer implementation will be used to construct a response from the view return value. If the renderer term contains a dot (``.``), the specified term will be treated as a path, and the filename extension of the last element in the path will be used to look up the renderer implementation, which will be passed the full path. The renderer implementation will be used to construct a response from the view return value. Note that if the view itself returns a response (see :ref:`the_response`), the specified renderer implementation is never called. When the renderer is a path, although a path is usually just a simple relative pathname (e.g. ``templates/foo.pt``, implying that a template named "foo.pt" is in the "templates" directory relative to the directory in which the ZCML file is defined), a path can be absolute, starting with a slash on UNIX or a drive letter prefix on Windows. The path can alternately be a :term:`resource specification` in the form ``some.dotted.package_name:relative/path``, making it possible to address template resources which live in a separate package. The ``renderer`` attribute is optional. If it is not defined, the "null" renderer is assumed (no rendering is performed and the value is passed back to the upstream BFG machinery unmolested). .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``wrapper`` The :term:`view name` (*not* an object dotted name) of another view declared elsewhere in ZCML (or via the ``@bfg_view`` decorator) which will receive the response body of this view as the ``request.wrapped_body`` attribute of its own request, and the response returned by this view as the ``request.wrapped_response`` attribute of its own request. Using a wrapper makes it possible to "chain" views together to form a composite response. The response of the outermost wrapper view will be returned to the user. The wrapper view will be found as any view is found: see :ref:`view_lookup_ordering`. The "best" wrapper view will be found based on the lookup ordering: "under the hood" this wrapper view is looked up via ``repoze.bfg.view.render_view_to_response(context, request, 'wrapper_viewname')``. The context and request of a wrapper view is the same context and request of the inner view. If this attribute is unspecified, no view wrapping is done. .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. Predicate Attributes #################### ``name`` The *view name*. Read the :ref:`traversal_chapter` to understand the concept of a view name. ``for`` A :term:`dotted Python name` representing the Python class that the :term:`context` must be an instance of, *or* the :term:`interface` that the :term:`context` must provide in order for this view to be found and called. This predicate is true when the :term:`context` is an instance of the represented class or if the :term:`context` provides the represented interface; it is otherwise false. ``route_name`` *This attribute services an advanced feature that isn't often used unless you want to perform traversal after a route has matched.* This value must match the ``name`` of a ```` declaration (see :ref:`urldispatch_chapter`) that must match before this view will be called. Note that the ``route`` configuration referred to by ``route_name`` usually has a ``*traverse`` token in the value of its ``path``, representing a part of the path that will be used by traversal against the result of the route's :term:`root factory`. See :ref:`hybrid_chapter` for more information on using this advanced feature. ``request_type`` This value should be a :term:`dotted Python name` string representing the :term:`interface` that the :term:`request` must have in order for this view to be found and called. The presence of this attribute is largely for backwards compatibility with applications written for :mod:`repoze.bfg` version 1.0. This value may be an HTTP ``REQUEST_METHOD`` string, e.g. ('GET', 'HEAD', 'PUT', 'POST', or 'DELETE'). Passing request method strings as a ``request_type`` is deprecated. Use the ``request_method`` attribute instead for maximum forward compatibility. ``request_method`` This value can either be one of the strings 'GET', 'POST', 'PUT', 'DELETE', or 'HEAD' representing an HTTP ``REQUEST_METHOD``. A view declaration with this attribute ensures that the view will only be called when the request's ``method`` (aka ``REQUEST_METHOD``) string matches the supplied value. .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``request_param`` This value can be any string. A view declaration with this attribute ensures that the view will only be called when the request has a key in the ``request.params`` dictionary (an HTTP ``GET`` or ``POST`` variable) that has a name which matches the supplied value. If the value supplied to the attribute has a ``=`` sign in it, e.g. ``request_params="foo=123"``, then the key (``foo``) must both exist in the ``request.params`` dictionary, and the value must match the right hand side of the expression (``123``) for the view to "match" the current request. .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``containment`` This value should be a :term:`dotted Python name` string representing the class that a graph traversal parent object of the :term:`context` must be an instance of (or :term:`interface` that a parent object must provide) in order for this view to be found and called. Your models must be "location-aware" to use this feature. See :ref:`location_aware` for more information about location-awareness. .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``xhr`` This value should be either ``True`` or ``False``. If this value is specified and is ``True``, the :term:`request` must possess an ``HTTP_X_REQUESTED_WITH`` (aka ``X-Requested-With``) header that has the value ``XMLHttpRequest`` for this view to be found and called. This is useful for detecting AJAX requests issued from jQuery, Prototype and other Javascript libraries. .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``accept`` The value of this attribute represents a match query for one or more mimetypes in the ``Accept`` HTTP request header. If this value is specified, it must be in one of the following forms: a mimetype match token in the form ``text/plain``, a wildcard mimetype match token in the form ``text/*`` or a match-all wildcard mimetype match token in the form ``*/*``. If any of the forms matches the ``Accept`` header of the request, this predicate will be true. .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``header`` The value of this attribute represents an HTTP header name or a header name/value pair. If the value contains a ``:`` (colon), it will be considered a name/value pair (e.g. ``User-Agent:Mozilla/.*`` or ``Host:localhost``). The *value* of an attribute that represent a name/value pair should be a regular expression. If the value does not contain a colon, the entire value will be considered to be the header name (e.g. ``If-Modified-Since``). If the value evaluates to a header name only without a value, the header specified by the name must be present in the request for this predicate to be true. If the value evaluates to a header name/value pair, the header specified by the name must be present in the request *and* the regular expression specified as the value must match the header value. Whether or not the value represents a header name or a header name/value pair, the case of the header name is not significant. .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``path_info`` The value of this attribute represents a regular expression pattern that will be tested against the ``PATH_INFO`` WSGI environment variable. If the regex matches, this predicate will be true. .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``custom_predicates`` This value should be a sequence of references to custom predicate callables (e.g. ``dotted.name.one dotted.name.two``, if used in ZCML; a :term:`dotted Python name` to each callable separated by a space). Use custom predicates when no set of predefined predicates do what you need. Custom predicates can be combined with predefined predicates as necessary. Each custom predicate callable should accept two arguments: ``context`` and ``request`` and should return either ``True`` or ``False`` after doing arbitrary evaluation of the context and/or the request. If all callables return ``True``, the associated view callable will be considered viable for a given request. .. note:: This feature is new as of :mod:`repoze.bfg` 1.2. Examples ~~~~~~~~ .. topic:: Registering A Default View for a Class .. code-block:: xml :linenos: .. topic:: Registering A View With a Predicate .. code-block:: xml :linenos: Alternatives ~~~~~~~~~~~~ You can also add a :term:`view configuration` via: - Using the :class:`repoze.bfg.view.bfg_view` class as a decorator. - Using the :meth:`repoze.bfg.configuration.Configurator.add_view` method. See Also ~~~~~~~~ See also :ref:`views_chapter`. .. _route_directive: ``route`` --------- The ``route`` directive adds a single :term:`route configuration` to the :term:`application registry`. Attributes ~~~~~~~~~~ ``path`` The path of the route e.g. ``ideas/:idea``. This attribute is required. See :ref:`route_path_pattern_syntax` for information about the syntax of route paths. ``name`` The name of the route, e.g. ``myroute``. This attribute is required. It must be unique among all defined routes in a given configuration. ``factory`` The :term:`dotted Python name` to a function that will generate a :mod:`repoze.bfg` context object when this route matches. e.g. ``mypackage.models.MyFactoryClass``. If this argument is not specified, a default root factory will be used. ``view`` The :term:`dotted Python name` to a function that will be used as a view callable when this route matches. e.g. ``mypackage.views.my_view``. ``xhr`` This value should be either ``True`` or ``False``. If this value is specified and is ``True``, the :term:`request` must possess an ``HTTP_X_REQUESTED_WITH`` (aka ``X-Requested-With``) header for this route to match. This is useful for detecting AJAX requests issued from jQuery, Prototype and other Javascript libraries. If this predicate returns false, route matching continues. .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``request_method`` A string representing an HTTP method name, e.g. ``GET``, ``POST``, ``HEAD``, ``DELETE``, ``PUT``. If this argument is not specified, this route will match if the request has *any* request method. If this predicate returns false, route matching continues. .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``path_info`` The value of this attribute represents a regular expression pattern that will be tested against the ``PATH_INFO`` WSGI environment variable. If the regex matches, this predicate will be true. If this predicate returns false, route matching continues. .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``request_param`` This value can be any string. A view declaration with this attribute ensures that the associated route will only match when the request has a key in the ``request.params`` dictionary (an HTTP ``GET`` or ``POST`` variable) that has a name which matches the supplied value. If the value supplied to the attribute has a ``=`` sign in it, e.g. ``request_params="foo=123"``, then the key (``foo``) must both exist in the ``request.params`` dictionary, and the value must match the right hand side of the expression (``123``) for the route to "match" the current request. If this predicate returns false, route matching continues. .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``header`` The value of this attribute represents an HTTP header name or a header name/value pair. If the value contains a ``:`` (colon), it will be considered a name/value pair (e.g. ``User-Agent:Mozilla/.*`` or ``Host:localhost``). The *value* of an attribute that represent a name/value pair should be a regular expression. If the value does not contain a colon, the entire value will be considered to be the header name (e.g. ``If-Modified-Since``). If the value evaluates to a header name only without a value, the header specified by the name must be present in the request for this predicate to be true. If the value evaluates to a header name/value pair, the header specified by the name must be present in the request *and* the regular expression specified as the value must match the header value. Whether or not the value represents a header name or a header name/value pair, the case of the header name is not significant. If this predicate returns false, route matching continues. .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``accept`` The value of this attribute represents a match query for one or more mimetypes in the ``Accept`` HTTP request header. If this value is specified, it must be in one of the following forms: a mimetype match token in the form ``text/plain``, a wildcard mimetype match token in the form ``text/*`` or a match-all wildcard mimetype match token in the form ``*/*``. If any of the forms matches the ``Accept`` header of the request, this predicate will be true. If this predicate returns false, route matching continues. .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``custom_predicates`` This value should be a sequence of references to custom predicate callables. Use custom predicates when no set of predefined predicates does what you need. Custom predicates can be combined with predefined predicates as necessary. Each custom predicate callable should accept two arguments: ``context`` and ``request`` and should return either ``True`` or ``False`` after doing arbitrary evaluation of the context and/or the request. If all callables return ``True``, the associated route will be considered viable for a given request. If any custom predicate returns ``False``, route matching continues. Note that the value ``context`` will always be ``None`` when passed to a custom route predicate. .. note:: This feature is new as of :mod:`repoze.bfg` 1.2. ``view_for`` 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 route to be used. This attribute is only useful if the ``view`` attribute is used. If this attribute is not specified, the default (``None``) will be used. If the ``view`` attribute is not provided, this attribute has no effect. This attribute can also be spelled as ``for``. ``view_permission`` The permission name required to invoke the view associated with this route. e.g. ``edit``. (see :ref:`using_security_with_urldispatch` for more information about permissions). If the ``view`` attribute is not provided, this attribute has no effect. This attribute can also be spelled as ``permission``. ``view_renderer`` This is either a single string term (e.g. ``json``) or a string implying a path or :term:`resource specification` (e.g. ``templates/views.pt``). If the renderer value is a single term (does not contain a dot ``.``), the specified term will be used to look up a renderer implementation, and that renderer implementation will be used to construct a response from the view return value. If the renderer term contains a dot (``.``), the specified term will be treated as a path, and the filename extension of the last element in the path will be used to look up the renderer implementation, which will be passed the full path. The renderer implementation will be used to construct a response from the view return value. See :ref:`views_which_use_a_renderer` for more information. If the ``view`` attribute is not provided, this attribute has no effect. This attribute can also be spelled as ``renderer``. .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``view_request_type`` A :term:`dotted Python name` to an interface representing a :term:`request type`. If this argument is not specified, any request type will be considered a match for the view associated with this route. If the ``view`` attribute is not provided, this attribute has no effect. This attribute can also be spelled as ``request_type``. ``view_containment`` This value should be a :term:`dotted Python name` string representing the class that a graph traversal parent object of the :term:`context` must be an instance of (or :term:`interface` that a parent object must provide) in order for this view to be found and called. Your models must be "location-aware" to use this feature. See :ref:`location_aware` for more information about location-awareness. If the ``view`` attribute is not provided, this attribute has no effect. .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``view_attr`` The view machinery defaults to using the ``__call__`` method of the view callable (or the function itself, if the view callable is a function) to obtain a response dictionary. The ``attr`` value allows you to vary the method attribute used to obtain the response. For example, if your view was a class, and the class has a method named ``index`` and you wanted to use this method instead of the class' ``__call__`` method to return the response, you'd say ``attr="index"`` in the view configuration for the view. This is most useful when the view definition is a class. If the ``view`` attribute is not provided, this attribute has no effect. .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. Alternatives ~~~~~~~~~~~~ You can also add a :term:`route configuration` via: - Using the :meth:`repoze.bfg.configuration.Configurator.add_route` method. See Also ~~~~~~~~ See also :ref:`urldispatch_chapter`. .. _subscriber_directive: ``subscriber`` -------------- The ``subscriber`` ZCML directive configures an :term:`subscriber` callable to listen for events broadcast by the :mod:`repoze.bfg` web framework. Attributes ~~~~~~~~~~ ``for`` The class or :term:`interface` that you are subscribing the listener for, e.g. :class:`repoze.bfg.interfaces.INewRequest`. Registering a subscriber for a specific class or interface limits the event types that the subscriber will receive to those specified by the interface or class. Default: ``zope.interface.Interface`` (implying *any* event type). ``handler`` A :term:`dotted Python name` which references an event handler callable. The callable should accept a single argument: ``event``. The return value of the callable is ignored. Examples ~~~~~~~~ .. code-block:: xml :linenos: Alternatives ~~~~~~~~~~~~ You can also register an event listener by using the :meth:`repoze.bfg.configuration.Configurator.add_subscriber` method. See Also ~~~~~~~~ See also :ref:`events_chapter`. .. _notfound_directive: ``notfound`` ------------ When :mod:`repoze.bfg` can't map a URL to view code, it invokes a :term:`not found view`. The default not found view is very plain, but the view callable used can be configured via the ``notfound`` ZCML tag. Attributes ~~~~~~~~~~ ``view`` The :term:`dotted Python name` to a :term:`view callable`. This attribute is required unless a ``renderer`` attribute also exists. If a ``renderer`` attribute exists on the directive, this attribute defaults to a view that returns an empty dictionary (see :ref:`views_which_use_a_renderer`). ``attr`` The attribute of the view callable to use if ``__call__`` is not correct (has the same meaning as in the context of :ref:`view_directive`; see the description of ``attr`` there). .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``renderer`` This is either a single string term (e.g. ``json``) or a string implying a path or :term:`resource specification` (e.g. ``templates/views.pt``) used when the view returns a non-:term:`response` object. This attribute has the same meaning as it would in the context of :ref:`view_directive`; see the description of ``renderer`` there). .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``wrapper`` The :term:`view name` (*not* an object dotted name) of another view declared elsewhere in ZCML (or via the ``@bfg_view`` decorator) which will receive the response body of this view as the ``request.wrapped_body`` attribute of its own request, and the response returned by this view as the ``request.wrapped_response`` attribute of its own request. This attribute has the same meaning as it would in the context of :ref:`view_directive`; see the description of ``wrapper`` there). Note that the wrapper view *should not* be protected by any permission; behavior is undefined if it does. .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. Example ~~~~~~~ .. code-block:: xml :linenos: Alternatives ~~~~~~~~~~~~ The :meth:`repoze.bfg.configuration.Configurator.set_notfound_view` method performs the same job as the ``notfound`` ZCML directive. See Also ~~~~~~~~ See also :ref:`changing_the_notfound_view`. .. _forbidden_directive: ``forbidden`` ------------- When :mod:`repoze.bfg` can't authorize execution of a view based on the :term:`authorization policy` in use, it invokes a :term:`forbidden view`. The default forbidden response has a 401 status code and is very plain, but it can be overridden as necessary using the ``forbidden`` ZCML directive. Attributes ~~~~~~~~~~ ``view`` The :term:`dotted Python name` to a :term:`view callable`. This attribute is required unless a ``renderer`` attribute also exists. If a ``renderer`` attribute exists on the directive, this attribute defaults to a view that returns an empty dictionary (see :ref:`views_which_use_a_renderer`). ``attr`` The attribute of the view callable to use if ``__call__`` is not correct (has the same meaning as in the context of :ref:`view_directive`; see the description of ``attr`` there). .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``renderer`` This is either a single string term (e.g. ``json``) or a string implying a path or :term:`resource specification` (e.g. ``templates/views.pt``) used when the view returns a non-:term:`response` object. This attribute has the same meaning as it would in the context of :ref:`view_directive`; see the description of ``renderer`` there). .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. ``wrapper`` The :term:`view name` (*not* an object dotted name) of another view declared elsewhere in ZCML (or via the ``@bfg_view`` decorator) which will receive the response body of this view as the ``request.wrapped_body`` attribute of its own request, and the response returned by this view as the ``request.wrapped_response`` attribute of its own request. This attribute has the same meaning as it would in the context of :ref:`view_directive`; see the description of ``wrapper`` there). Note that the wrapper view *should not* be protected by any permission; behavior is undefined if it does. .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. Example ~~~~~~~ .. code-block:: xml :linenos: Alternatives ~~~~~~~~~~~~ The :meth:`repoze.bfg.configuration.Configurator.set_forbidden_view` method performs the same job as the ``forbidden`` ZCML directive. See Also ~~~~~~~~ See also :ref:`changing_the_forbidden_view`. .. _scan_directive: ``scan`` -------- To make use of :term:`configuration decoration` decorators, you must perform a :term:`scan`. A scan finds these decorators in code. The ``scan`` ZCML directive tells :mod:`repoze.bfg` to begin such a scan. Attributes ~~~~~~~~~~ ``package`` The package to scan or the single dot (``.``), meaning the "current" package (the package in which the ZCML file lives). Example ~~~~~~~ .. code-block:: xml :linenos: Alternatives ~~~~~~~~~~~~ The :meth:`repoze.bfg.configuration.Configurator.scan` method performs the same job as the ``scan`` ZCML directive. See Also ~~~~~~~~ See also :ref:`mapping_views_to_urls_using_a_decorator_section`. .. _resource_directive: ``resource`` ------------ The ``resource`` directive adds a resource override for a single resource. Attributes ~~~~~~~~~~ ``to_override`` A :term:`resource specification` specifying the resource to be overridden. ``override_with`` A :term:`resource specification` specifying the resource which is used as the override. Examples ~~~~~~~~ .. topic:: Overriding a Single Resource File .. code-block:: xml :linenos: .. topic:: Overriding all Resources in a Package .. code-block:: xml :linenos: .. topic:: Overriding all Resources in a Subdirectory of a Package .. code-block:: xml :linenos: Alternatives ~~~~~~~~~~~~ The :meth:`repoze.bfg.configuration.Configurator.override_resource` method can be used instead of the ``resource`` ZCML directive. See Also ~~~~~~~~ See also :ref:`resource_zcml_directive`. .. _static_directive: ``static`` ---------- Use of the ``static`` ZCML directive or allows you to serve static resources (such as JavaScript and CSS files) within a :mod:`repoze.bfg` application. This mechanism makes static files available at a name relative to the application root URL. Attributes ~~~~~~~~~~ ``name`` The (application-root-relative) URL prefix of the static directory. For example, to serve static files from ``/static`` in most applications, you would provide a ``name`` of ``static``. ``path`` A path to a directory on disk where the static files live. This path may either be 1) absolute (e.g. ``/foo/bar/baz``) 2) Python-package-relative (e.g. (``packagename:foo/bar/baz``) or 3) relative to the package directory in which the ZCML file which contains the directive (e.g. ``foo/bar/baz``). ``cache_max_age`` The number of seconds that the static resource can be cached, as represented in the returned response's ``Expires`` and/or ``Cache-Control`` headers, when any static file is served from this directive. This defaults to 3600 (5 minutes). Optional. Examples ~~~~~~~~ .. topic:: Serving Static Files from an Absolute Path .. code-block:: xml :linenos: .. topic:: Serving Static Files from a Package-Relative Path .. code-block:: xml :linenos: .. topic:: Serving Static Files from a Current-Package-Relative Path .. code-block:: xml :linenos: Alternatives ~~~~~~~~~~~~ :meth:`repoze.bfg.configuration.configurator.add_static_view` can also be used to add a static view. See Also ~~~~~~~~ See also :ref:`static_resources_section` and :ref:`generating_static_resource_urls`. .. _renderer_directive: ``renderer`` ------------ The ``renderer`` ZCML directive can be used to override an existing existing :term:`renderer` or to add a new renderer. Attributes ~~~~~~~~~~ ``factory`` A :term:`dotted Python name` referencing a callable object that accepts a renderer name and returns a :term:`renderer` object. ``name`` The renderer name, which is a string. Examples ~~~~~~~~ .. topic:: Registering a Non-Template Renderer .. code-block:: xml :linenos: .. topic:: Registering a Template Renderer .. code-block:: xml :linenos: Alternatives ~~~~~~~~~~~~ The :meth:`repoze.bfg.configuration.Configurator.add_renderer` method is equivalent to the ``renderer`` ZCML directive. See Also ~~~~~~~~ See also :ref:`adding_and_overriding_renderers`. .. _authtktauthenticationpolicy_directive: ``authtktauthenticationpolicy`` ------------------------------- When this directive is used, authentication information is obtained from an :mod:`paste.auth.auth_tkt` cookie value, assumed to be set by a custom login form. Attributes ~~~~~~~~~~ ``secret`` The ``secret`` is a string that will be used to encrypt the data stored by the cookie. It is required and has no default. ``callback`` The ``callback`` is a Python dotted name to a function passed the string representing the userid stored in the cookie and the request as positional arguments. The callback is expected to return None if the user represented by the string doesn't exist or a sequence of group identifiers (possibly empty) if the user does exist. If ``callback`` is None, the userid will be assumed to exist with no groups. It defaults to ``None``. ``cookie_name`` The ``cookie_name`` is the name used for the cookie that contains the user information. It defaults to ``repoze.bfg.auth_tkt``. ``secure`` ``secure`` is a boolean value. If it's set to "true", the cookie will only be sent back by the browser over a secure (HTTPS) connection. It defaults to "false". ``include_ip`` ``include_ip`` is a boolean value. If it's set to true, the requesting IP address is made part of the authentication data in the cookie; if the IP encoded in the cookie differs from the IP of the requesting user agent, the cookie is considered invalid. It defaults to "false". ``timeout`` ``timeout`` is an integer value. It represents the maximum age in seconds which the auth_tkt ticket will be considered valid. If ``timeout`` is specified, and ``reissue_time`` is also specified, ``reissue_time`` must be a smaller value than ``timeout``. It defaults to ``None``, meaning that the ticket will be considered valid forever. ``reissue_time`` ``reissue_time`` is an integer value. If ``reissue_time`` is specified, when we encounter a cookie that is older than the reissue time (in seconds), but younger that the ``timeout``, a new cookie will be issued. It defaults to ``None``, meaning that authentication cookies are never reissued. A value of ``0`` means reissue a cookie in the response to every request that requires authentication. ``max_age`` ``max_age`` is the maximum age of the auth_tkt *cookie*, in seconds. This differs from ``timeout`` inasmuch as ``timeout`` represents the lifetime of the ticket contained in the cookie, while this value represents the lifetime of the cookie itself. When this value is set, the cookie's ``Max-Age`` and ``Expires`` settings will be set, allowing the auth_tkt cookie to last between browser sessions. It is typically nonsensical to set this to a value that is lower than ``timeout`` or ``reissue_time``, although it is not explicitly prevented. It defaults to ``None``, meaning (on all major browser platforms) that auth_tkt cookies will last for the lifetime of the user's browser session. Example ~~~~~~~ .. code-block:: xml :linenos: Alternatives ~~~~~~~~~~~~ You may create an instance of the :class:`repoze.bfg.authentication.AuthTktAuthenticationPolicy` and pass it to the :class:`repoze.bfg.configuration.Configurator` constructor as the ``authentication_policy`` argument during initial application configuration. See Also ~~~~~~~~ See also :ref:`authentication_policies_directives_section` and :class:`repoze.bfg.authentication.AuthTktAuthenticationPolicy`. .. _remoteuserauthenticationpolicy_directive: ``remoteuserauthenticationpolicy`` ---------------------------------- When this directive is used, authentication information is obtained from a ``REMOTE_USER`` key in the WSGI environment, assumed to be set by a WSGI server or an upstream middleware component. Attributes ~~~~~~~~~~ ``environ_key`` The ``environ_key`` is the name that will be used to obtain the remote user value from the WSGI environment. It defaults to ``REMOTE_USER``. ``callback`` The ``callback`` is a Python dotted name to a function passed the string representing the remote user and the request as positional arguments. The callback is expected to return None if the user represented by the string doesn't exist or a sequence of group identifiers (possibly empty) if the user does exist. If ``callback`` is None, the userid will be assumed to exist with no groups. It defaults to ``None``. Example ~~~~~~~ .. code-block:: xml :linenos: Alternatives ~~~~~~~~~~~~ You may create an instance of the :class:`repoze.bfg.authentication.RemoteUserAuthenticationPolicy` and pass it to the :class:`repoze.bfg.configuration.Configurator` constructor as the ``authentication_policy`` argument during initial application configuration. See Also ~~~~~~~~ See also :ref:`authentication_policies_directives_section` and :class:`repoze.bfg.authentication.RemoteUserAuthenticationPolicy`. .. _repozewho1authenticationpolicy_directive: ``repozewho1authenticationpolicy`` ---------------------------------- When this directive is used, authentication information is obtained from a ``repoze.who.identity`` key in the WSGI environment, assumed to be set by :term:`repoze.who` middleware. Attributes ~~~~~~~~~~ ``identifier_name`` The ``identifier_name`` controls the name used to look up the :term:`repoze.who` "identifier" plugin within ``request.environ['repoze.who.plugins']`` which is used by this policy to "remember" and "forget" credentials. It defaults to ``auth_tkt``. ``callback`` The ``callback`` is a Python dotted name to a function passed the repoze.who identity and the request as positional arguments. The callback is expected to return None if the user represented by the identity doesn't exist or a sequence of group identifiers (possibly empty) if the user does exist. If ``callback`` is None, the userid will be assumed to exist with no groups. It defaults to ``None``. Example ~~~~~~~ .. code-block:: xml :linenos: Alternatives ~~~~~~~~~~~~ You may create an instance of the :class:`repoze.bfg.authentication.RepozeWho1AuthenticationPolicy` and pass it to the :class:`repoze.bfg.configuration.Configurator` constructor as the ``authentication_policy`` argument during initial application configuration. See Also ~~~~~~~~ See also :ref:`authentication_policies_directives_section` and :class:`repoze.bfg.authentication.RepozeWho1AuthenticationPolicy`. .. _aclauthorizationpolicy_directive: ``aclauthorizationpolicy`` -------------------------- When this directive is used, authorization information is obtained from :term:`ACL` objects attached to model instances. Attributes ~~~~~~~~~~ None. Example ~~~~~~~ .. code-block:: xml :linenos: Alternatives ~~~~~~~~~~~~ You may create an instance of the :class:`repoze.bfg.authorization.ACLAuthorizationPolicy` and pass it to the :class:`repoze.bfg.configuration.Configurator` constructor as the ``authorization_policy`` argument during initial application configuration. See Also ~~~~~~~~ See also :ref:`authorization_policies_directives_section` and :ref:`security_chapter`. .. _adapter_directive: ``adapter`` ----------- Register a :term:`Zope Component Architecture` "adapter". Attributes ~~~~~~~~~~ ``factory`` The adapter factory (often a class). ``provides`` The :term:`interface` that an adapter instance resulting from a lookup will provide. ``for`` Interfaces or classes to be adapted, separated by spaces, e.g. ``interfaces.IFoo interfaces.IBar``. ``name`` The adapter name. Example ~~~~~~~ .. code-block:: xml :linenos: Alternatives ~~~~~~~~~~~~ Use the ``registerAdapter`` method of the ``registry`` attribute of a :term:`Configurator` instance during initial application setup. See Also ~~~~~~~~ None. .. _utility_directive: ``utility`` ----------- Register a :term:`Zope Component Architecture` "utility". Attributes ~~~~~~~~~~ ``component`` The utility component (cannot be specified if ``factory`` is specified). ``factory`` A factory that creates a component (cannot be specified if ``component`` is specified). ``provides`` The :term:`interface` that an utility instance resulting from a lookup will provide. ``name`` The utility name. Example ~~~~~~~ .. code-block:: xml :linenos: Alternatives ~~~~~~~~~~~~ Use the ``registerUtility`` method of the ``registry`` attribute of a :term:`Configurator` instance during initial application setup. See Also ~~~~~~~~ None.