Configuring a Handler via ZCML¶
Instead of using the imperative
pyramid.config.Configurator.add_handler()
method to add a new
route, you can alternately use ZCML.
Warning
ZCML works under Python 2.6 and 2.7; it, however, does not work under Python 3.2 or any other version of Python 3.
Using The handler ZCML Directive statements in a ZCML file used by your application is a sign that you’re using URL dispatch. For example, the following ZCML declaration causes a route to be added to the application.
1 2 3 4 5 | <handler
route_name="myroute"
pattern="/prefix/{action}"
handler=".handlers.MyHandler"
/>
|
Note
Values prefixed with a period (.
) within the values of ZCML attributes
such as the handler
attribute of a handler
directive mean
“relative to the Python package directory in which this ZCML file
is stored”. So if the above handler
declaration was made inside a
configure.zcml
file that lived in the hello
package, you could
replace the relative .views.MyHandler
with the absolute
hello.views.MyHandler
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.
The order that the routes attached to handlers are evaluated when declarative configuration is used is the order that they appear relative to each other in the ZCML file.
See Using The handler ZCML Directive for full handler
ZCML directive
documentation.
Using The handler
ZCML Directive¶
The handler
directive adds the configuration of a view handler to
the application registry. It is a declarative analogue of the
pyramid_handlers.add_handler()
directive.
Example¶
Do the following from within a Pyramid application to use the handler
ZCML directive.
1 2 3 4 5 6 | <include package="pyramid_handlers" file="meta.zcml"/>
<handler
route_name="foo"
pattern="/foo/{action}"
handler="some.module.SomeClass"/>
|
Attributes¶
route_name
- The name of the route, e.g.
myroute
. This attribute is required. It must be unique among all defined handler and route names in a given configuration. pattern
- The pattern of the route e.g.
ideas/{idea}
. This attribute is required. See route_pattern_syntax for information about the syntax of route patterns. The name{action}
is treated specially in handler patterns. See Handler Registration Using add_handler() for a discussion of how{action}
in handler patterns is treated. handler
- A dotted Python name to the handler class.
action
- If the action name is not specified in the
pattern
, use this name as the handler action (method name). factory
- The dotted Python name to a function that will generate a
Pyramid context object when the associated route matches.
e.g.
mypackage.resources.MyResource
. If this argument is not specified, a default root factory will be used. xhr
- This value should be either
True
orFalse
. If this value is specified and isTrue
, the request must possess anHTTP_X_REQUESTED_WITH
(akaX-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. traverse
If you would like to cause the context to be something other than the root object when this route matches, you can spell a traversal pattern as the
traverse
argument. This traversal pattern will be used as the traversal path: traversal will begin at the root object implied by this route (either the global root, or the object returned by thefactory
associated with this route).The syntax of the
traverse
argument is the same as it is forpattern
. For example, if thepattern
provided to theroute
directive isarticles/{article}/edit
, and thetraverse
argument provided to theroute
directive is/{article}
, when a request comes in that causes the route to match in such a way that thearticle
match value is ‘1’ (when the request URI is/articles/1/edit
), the traversal path will be generated as/1
. This means that the root object’s__getitem__
will be called with the name1
during the traversal phase. If the1
object exists, it will become the context of the request. traversal_chapter has more information about traversal.If the traversal path contains segment marker names which are not present in the
pattern
argument, a runtime error will occur. Thetraverse
pattern should not contain segment markers that do not exist in thepattern
.A similar combining of routing and traversal is available when a route is matched which contains a
*traverse
remainder marker in itspattern
(see using_traverse_in_a_route_pattern). Thetraverse
argument to theroute
directive allows you to associate route patterns with an arbitrary traversal path without using a a*traverse
remainder marker; instead you can use other match information.Note that the
traverse
argument to thehandler
directive is ignored when attached to a route that has a*traverse
remainder marker in its pattern.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. 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. 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 HTTPGET
orPOST
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 therequest.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. 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/.*
orHost: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. 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 formtext/plain
, a wildcard mimetype match token in the formtext/*
or a match-all wildcard mimetype match token in the form*/*
. If any of the forms matches theAccept
header of the request, this predicate will be true. If this predicate returns false, route matching continues. 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:
info
andrequest
and should return eitherTrue
orFalse
after doing arbitrary evaluation of the info and/or the request. If all custom and non-custom predicate callables returnTrue
the associated route will be considered viable for a given request. If any predicate callable returnsFalse
, route matching continues. Note that the valueinfo
passed to a custom route predicate is a dictionary containing matching information; see custom_route_predicates for more information aboutinfo
.
Alternatives¶
You can also add a route configuration via:
- Using the
pyramid.config.Configurator.add_handler()
method.
See Also¶
See also views_chapter.