1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
.. _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_context``
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 ``view_for`` or ``for_``;
these are valid older spellings.
``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`.
|
