Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 269 lines (224 sloc) 11.94 kB
5046ea4 @mcdonc first cut (one test still fails)
mcdonc authored
1 .. _view_directive:
2
3 ``view``
4 --------
5
6 A ``view`` declaration directs Pyramid to create a single
7 :term:`view configuration` registration in the current
8 :term:`application registry`.
9
10 The ``view`` ZCML directive has many possible attributes. Some of the
11 attributes are descriptive or influence rendering. Other attributes
12 are :term:`predicate` attributes, meaning that they imply an
13 evaluation to true or false when view lookup is performed.
14
15 *All* predicates named in a view configuration must evaluate to true
16 in order for the view callable it names to be considered "invokable"
17 for a given request. See :ref:`view_lookup` for a description of how
18 a view configuration matches (or doesn't match) during a request.
19
20 The possible attributes of the ``view`` ZCML directive are described
21 below. They are divided into predicate and non-predicate categories.
22
23 Attributes
24 ~~~~~~~~~~
25
26 Non-Predicate Attributes
27 ########################
28
29 ``view``
30 The :term:`dotted Python name` to a :term:`view callable`. This
31 attribute is required unless a ``renderer`` attribute also exists.
32 If a ``renderer`` attribute exists on the directive, this attribute
33 defaults to a view that returns an empty dictionary (see
34 :ref:`views_which_use_a_renderer`).
35
36 ``permission``
37 The name of a *permission* that the user must possess in order to
38 call the view. See :ref:`view_security_section` for more
39 information about view security and permissions.
40
41 ``attr``
42 The view machinery defaults to using the ``__call__`` method of the
43 view callable (or the function itself, if the view callable is a
44 function) to obtain a response dictionary. The ``attr`` value
45 allows you to vary the method attribute used to obtain the response.
46 For example, if your view was a class, and the class has a method
47 named ``index`` and you wanted to use this method instead of the
48 class' ``__call__`` method to return the response, you'd say
49 ``attr="index"`` in the view configuration for the view. This is
50 most useful when the view definition is a class.
51
52 ``renderer``
53 This is either a single string term (e.g. ``json``) or a string
54 implying a path or :term:`asset specification`
55 (e.g. ``templates/views.pt``). If the renderer value is a single
56 term (does not contain a dot ``.``), the specified term will be used
57 to look up a renderer implementation, and that renderer
58 implementation will be used to construct a response from the view
59 return value. If the renderer term contains a dot (``.``), the
60 specified term will be treated as a path, and the filename extension
61 of the last element in the path will be used to look up the renderer
62 implementation, which will be passed the full path. The renderer
63 implementation will be used to construct a response from the view
64 return value.
65
66 Note that if the view itself returns a response (see
67 :ref:`the_response`), the specified renderer implementation is never
68 called.
69
70 When the renderer is a path, although a path is usually just a
71 simple relative pathname (e.g. ``templates/foo.pt``, implying that a
72 template named "foo.pt" is in the "templates" directory relative to
73 the directory in which the ZCML file is defined), a path can be
74 absolute, starting with a slash on UNIX or a drive letter prefix on
75 Windows. The path can alternately be a :term:`asset
76 specification` in the form
77 ``some.dotted.package_name:relative/path``, making it possible to
78 address template assets which live in a separate package.
79
80 The ``renderer`` attribute is optional. If it is not defined, the
81 "null" renderer is assumed (no rendering is performed and the value
82 is passed back to the upstream BFG machinery unmolested).
83
84 ``wrapper``
85 The :term:`view name` (*not* an object dotted name) of another view
86 declared elsewhere in ZCML (or via the ``@view_config`` decorator)
87 which will receive the response body of this view as the
88 ``request.wrapped_body`` attribute of its own request, and the
89 response returned by this view as the ``request.wrapped_response``
90 attribute of its own request. Using a wrapper makes it possible to
91 "chain" views together to form a composite response. The response
92 of the outermost wrapper view will be returned to the user. The
93 wrapper view will be found as any view is found: see
94 :ref:`view_lookup`. The "best" wrapper view will be found based on
95 the lookup ordering: "under the hood" this wrapper view is looked up
96 via ``pyramid.view.render_view_to_response(context, request,
97 'wrapper_viewname')``. The context and request of a wrapper view is
98 the same context and request of the inner view. If this attribute
99 is unspecified, no view wrapping is done.
100
101 Predicate Attributes
102 ####################
103
104 ``name``
105 The *view name*. Read the :ref:`traversal_chapter` to understand
106 the concept of a view name.
107
108 ``context``
109 A :term:`dotted Python name` representing the Python class that the
110 :term:`context` must be an instance of, *or* the :term:`interface`
111 that the :term:`context` must provide in order for this view to be
112 found and called. This predicate is true when the :term:`context`
113 is an instance of the represented class or if the :term:`context`
114 provides the represented interface; it is otherwise false. An
115 alternate name for this attribute is ``for`` (this is an older
116 spelling).
117
118 ``route_name``
119 *This attribute services an advanced feature that isn't often used
120 unless you want to perform traversal after a route has matched.*
121 This value must match the ``name`` of a ``<route>`` declaration (see
122 :ref:`urldispatch_chapter`) that must match before this view will be
123 called. Note that the ``route`` configuration referred to by
124 ``route_name`` usually has a ``*traverse`` token in the value of its
125 ``path``, representing a part of the path that will be used by
126 traversal against the result of the route's :term:`root factory`.
127 See :ref:`hybrid_chapter` for more information on using this
128 advanced feature.
129
130 ``request_type``
131 This value should be a :term:`dotted Python name` string
132 representing the :term:`interface` that the :term:`request` must
133 have in order for this view to be found and called. The presence of
134 this attribute is largely for backwards compatibility with
135 older iterations of this framework.
136
137 ``request_method``
138 This value can either be one of the strings 'GET', 'POST', 'PUT',
139 'DELETE', or 'HEAD' representing an HTTP ``REQUEST_METHOD``. A view
140 declaration with this attribute ensures that the view will only be
141 called when the request's ``method`` (aka ``REQUEST_METHOD``) string
142 matches the supplied value.
143
144 ``request_param``
145 This value can be any string. A view declaration with this
146 attribute ensures that the view will only be called when the request
147 has a key in the ``request.params`` dictionary (an HTTP ``GET`` or
148 ``POST`` variable) that has a name which matches the supplied value.
149 If the value supplied to the attribute has a ``=`` sign in it,
150 e.g. ``request_params="foo=123"``, then the key (``foo``) must both
151 exist in the ``request.params`` dictionary, and the value must match
152 the right hand side of the expression (``123``) for the view to
153 "match" the current request.
154
155 ``containment``
156 This value should be a :term:`dotted Python name` string
157 representing the class that a graph traversal parent object of the
158 :term:`context` must be an instance of (or :term:`interface` that a
159 parent object must provide) in order for this view to be found and
160 called. Your resources must be "location-aware" to use this feature.
161 See :ref:`location_aware` for more information about
162 location-awareness.
163
164 ``xhr``
165 This value should be either ``True`` or ``False``. If this value is
166 specified and is ``True``, the :term:`request` must possess an
167 ``HTTP_X_REQUESTED_WITH`` (aka ``X-Requested-With``) header that has
168 the value ``XMLHttpRequest`` for this view to be found and called.
169 This is useful for detecting AJAX requests issued from jQuery,
170 Prototype and other Javascript libraries.
171
172 ``accept``
173 The value of this attribute represents a match query for one or more
174 mimetypes in the ``Accept`` HTTP request header. If this value is
175 specified, it must be in one of the following forms: a mimetype
176 match token in the form ``text/plain``, a wildcard mimetype match
177 token in the form ``text/*`` or a match-all wildcard mimetype match
178 token in the form ``*/*``. If any of the forms matches the
179 ``Accept`` header of the request, this predicate will be true.
180
181 ``header``
182 The value of this attribute represents an HTTP header name or a
183 header name/value pair. If the value contains a ``:`` (colon), it
184 will be considered a name/value pair (e.g. ``User-Agent:Mozilla/.*``
185 or ``Host:localhost``). The *value* of an attribute that represent
186 a name/value pair should be a regular expression. If the value does
187 not contain a colon, the entire value will be considered to be the
188 header name (e.g. ``If-Modified-Since``). If the value evaluates to
189 a header name only without a value, the header specified by the name
190 must be present in the request for this predicate to be true. If
191 the value evaluates to a header name/value pair, the header
192 specified by the name must be present in the request *and* the
193 regular expression specified as the value must match the header
194 value. Whether or not the value represents a header name or a
195 header name/value pair, the case of the header name is not
196 significant.
197
198 ``path_info``
199 The value of this attribute represents a regular expression pattern
200 that will be tested against the ``PATH_INFO`` WSGI environment
201 variable. If the regex matches, this predicate will be true.
202
203 ``custom_predicates``
204 This value should be a sequence of references to custom predicate
205 callables (e.g. ``dotted.name.one dotted.name.two``, if used in
206 ZCML; a :term:`dotted Python name` to each callable separated by a
207 space). Use custom predicates when no set of predefined predicates
208 do what you need. Custom predicates can be combined with predefined
209 predicates as necessary. Each custom predicate callable should
210 accept two arguments: ``context`` and ``request`` and should return
211 either ``True`` or ``False`` after doing arbitrary evaluation of the
212 context and/or the request. If all callables return ``True``, the
213 associated view callable will be considered viable for a given
214 request.
215
2fe4032 @tseaver Note deprecation of 'custom_predicates'.
tseaver authored
216 .. note:: this argument is deprecated as of Pyramid 1.5.
217
5046ea4 @mcdonc first cut (one test still fails)
mcdonc authored
218 ``decorator``
219 A :term:`dotted Python name` to a function that will be used to decorate
220 the registered :term:`view callable`. The decorator function will be
221 called with the view callable as a single argument. The view callable it
222 is passed will accept ``(context, request)``. The decorator must return a
223 replacement view callable which also accepts ``(context, request)``.
224
225 ``mapper``
226 A :term:`dotted Python name` which refers to a :term:`view mapper`, or
227 ``None``. By default it is ``None``, which indicates that the view should
228 use the default view mapper. This plug-point is useful for Pyramid
229 extension developers, but it's not very useful for 'civilians' who are just
230 developing stock Pyramid applications.
231
232 Examples
233 ~~~~~~~~
234
235 .. topic:: Registering A Default View for a Class
236
237 .. code-block:: xml
238 :linenos:
239
240 <view
241 context=".resources.MyResource"
242 view=".views.hello_world"
243 />
244
245 .. topic:: Registering A View With a Predicate
246
247 .. code-block:: xml
248 :linenos:
249
250 <view
251 context=".resources.MyResource"
252 view=".views.hello_world_post"
253 request_method="POST"
254 />
255
256 Alternatives
257 ~~~~~~~~~~~~
258
259 You can also add a :term:`view configuration` via:
260
261 - Using the :class:`pyramid.view.view_config` class as a decorator.
262
263 - Using the :meth:`pyramid.config.Configurator.add_view` method.
264
265 See Also
266 ~~~~~~~~
267
268 See also :ref:`views_chapter`.
Something went wrong with that request. Please try again.