Skip to content
This package provides means of hooking into the Zope (ZCML) configuration process.
Python
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs
src/z3c
COPYRIGHT.txt
LICENSE.txt
README.txt
bootstrap.py
buildout.cfg
setup.py

README.txt

Introduction
============

This package provides means of hooking into the Zope (ZCML) configuration
process.

Custom ZCML actions
-------------------

It is sometimes useful to execute a function during the execution of 
configuration actions, for example to perform one-off configuration that does
not warrant a new directive. The ``<zcml:customAction />`` directive is
provided for this purpose.

For example, you may want to call a function called
``my.package.finalConfiguration()`` "late" in the configuration action
execution cycle. This can be achieved with the following ZCML statements::

    <configure
        xmlns="http://namespaces.zope.org/zope"
        xmlns:zcml="http://namespaces.zope.org/zcml"
        i18n_domain="my.package">
        
        <include package="z3c.zcmlhook" file="meta.zcml" />
        
        <zcml:customAction
            handler="my.package.finalConfiguration"
            order="9999"
            />
        
    </configure>

The ``handler`` attribute gives the name of a function to execute. The
function should take no arguments. The ``order`` attribute is optional, and
can be used to influence when in the configuration cycle the function is
executed. The default value for this, as for most Zope configuration actions,
is ``0``.

Overriding custom actions
-------------------------

If you want to override the invocation of a custom handler in an
``overrides.zcml``, you need to tell ``zope.configuration`` which handler to
override. You can do that by setting the *discriminator* explicitly. A
discriminator is used to uniquely identify a configuration action. In the
case of the ``<zcml:customAction />`` directive, the discriminator is based
on the full dotted name to the function by default. Thus, you could override
the function call above like so::

        <zcml:customAction
            handler="my.otherpackage.overrideFinalConfiguration"
            discriminator="my.package.finalConfiguration"
            order="9999"
            />

Using a handler more than once
------------------------------

The ``discriminator`` attribute can also be used to explicitly allow using
the same handler more than once. If you wanted to call
``my.package.finalConfiguration`` again, you would normally get a
configuration conflict. However, with a (unique) custom discriminator, the
second call is allowed::

        <zcml:customAction
            handler="my.package.finalConfiguration"
            discriminator="my.package.finalConfiguration:early"
            order="-9999"
            />

        <zcml:customAction
            handler="my.package.finalConfiguration"
            discriminator="my.package.finalConfiguration:late"
            order="9999"
            />

Here, we are attempting to call our configuration action "very early" as
well as "very late" in the configuration process.
You can’t perform that action at this time.