|
1 The `Request` class (`cubicweb.web.request`) |
|
2 -------------------------------------------- |
|
3 |
|
4 Overview |
|
5 ```````` |
|
6 |
|
7 A request instance is created when an HTTP request is sent to the web |
|
8 server. It contains informations such as form parameters, |
|
9 authenticated user, etc. It is a very prevalent object and is used |
|
10 throughout all of the framework and applications, as you'll access to |
|
11 almost every resources through it. |
|
12 |
|
13 **A request represents a user query, either through HTTP or not (we |
|
14 also talk about RQL queries on the server side for example).** |
|
15 |
|
16 Here is a non-exhaustive list of attributes and methods available on |
|
17 request objects (grouped by category): |
|
18 |
|
19 * `Browser control`: |
|
20 |
|
21 * `ie_browser`: tells if the browser belong to the Internet Explorer |
|
22 family |
|
23 |
|
24 * `User and identification`: |
|
25 |
|
26 * `user`, instance of `cubicweb.entities.authobjs.CWUser` corresponding to the |
|
27 authenticated user |
|
28 |
|
29 * `Session data handling` |
|
30 |
|
31 * `session.data` is the dictionary of the session data; it can be |
|
32 manipulated like an ordinary Python dictionary |
|
33 |
|
34 * `Edition` (utilities for edition control): |
|
35 |
|
36 * `cancel_edition`: resets error url and cleans up pending operations |
|
37 * `create_entity`: utility to create an entity (from an etype, |
|
38 attributes and relation values) |
|
39 * `datadir_url`: returns the url to the merged external resources |
|
40 (|cubicweb|'s `web/data` directory plus all `data` directories of |
|
41 used cubes) |
|
42 * `edited_eids`: returns the list of eids of entities that are |
|
43 edited under the current http request |
|
44 * `eid_rset(eid)`: utility which returns a result set from an eid |
|
45 * `entity_from_eid(eid)`: returns an entity instance from the given eid |
|
46 * `encoding`: returns the encoding of the current HTTP request |
|
47 * `ensure_ro_rql(rql)`: ensure some rql query is a data request |
|
48 * etype_rset |
|
49 * `form`, dictionary containing the values of a web form |
|
50 * `encoding`, character encoding to use in the response |
|
51 * `next_tabindex()`: returns a monotonically growing integer used to |
|
52 build the html tab index of forms |
|
53 |
|
54 * `HTTP` |
|
55 |
|
56 * `authmode`: returns a string describing the authentication mode |
|
57 (http, cookie, ...) |
|
58 * `lang`: returns the user agents/browser's language as carried by |
|
59 the http request |
|
60 * `demote_to_html()`: in the context of an XHTML compliant browser, |
|
61 this will force emission of the response as an HTML document |
|
62 (using the http content negociation) |
|
63 |
|
64 * `Cookies handling` |
|
65 |
|
66 * `get_cookie()`, returns a dictionary containing the value of the header |
|
67 HTTP 'Cookie' |
|
68 * `set_cookie(cookie, key, maxage=300)`, adds a header HTTP `Set-Cookie`, |
|
69 with a minimal 5 minutes length of duration by default (`maxage` = None |
|
70 returns a *session* cookie which will expire when the user closes the browser |
|
71 window) |
|
72 * `remove_cookie(cookie, key)`, forces a value to expire |
|
73 |
|
74 * `URL handling` |
|
75 |
|
76 * `build_url(__vid, *args, **kwargs)`: return an absolute URL using |
|
77 params dictionary key/values as URL parameters. Values are |
|
78 automatically URL quoted, and the publishing method to use may be |
|
79 specified or will be guessed. |
|
80 * `build_url_params(**kwargs)`: returns a properly prepared (quoted, |
|
81 separators, ...) string from the given parameters |
|
82 * `url()`, returns the full URL of the HTTP request |
|
83 * `base_url()`, returns the root URL of the web application |
|
84 * `relative_path()`, returns the relative path of the request |
|
85 |
|
86 * `Web resource (.css, .js files, etc.) handling`: |
|
87 |
|
88 * `add_css(cssfiles)`: adds the given list of css resources to the current |
|
89 html headers |
|
90 * `add_js(jsfiles)`: adds the given list of javascript resources to the |
|
91 current html headers |
|
92 * `add_onload(jscode)`: inject the given jscode fragment (a unicode |
|
93 string) into the current html headers, wrapped inside a |
|
94 document.ready(...) or another ajax-friendly one-time trigger event |
|
95 * `add_header(header, values)`: adds the header/value pair to the |
|
96 current html headers |
|
97 * `status_out`: control the HTTP status of the response |
|
98 |
|
99 * `And more...` |
|
100 |
|
101 * `set_content_type(content_type, filename=None)`, adds the header HTTP |
|
102 'Content-Type' |
|
103 * `get_header(header)`, returns the value associated to an arbitrary header |
|
104 of the HTTP request |
|
105 * `set_header(header, value)`, adds an arbitrary header in the response |
|
106 * `execute(*args, **kwargs)`, executes an RQL query and return the result set |
|
107 * `property_value(key)`, properties management (`CWProperty`) |
|
108 * dictionary `data` to store data to share informations between components |
|
109 *while a request is executed* |
|
110 |
|
111 Please note that this class is abstract and that a concrete implementation |
|
112 will be provided by the *frontend* web used (in particular *twisted* as of |
|
113 today). For the views or others that are executed on the server side, |
|
114 most of the interface of `Request` is defined in the session associated |
|
115 to the client. |
|
116 |
|
117 API |
|
118 ``` |
|
119 |
|
120 The elements we gave in overview for above are built in three layers, |
|
121 from ``cubicweb.req.RequestSessionBase``, ``cubicweb.repoapi.Connection`` and |
|
122 ``cubicweb.web.ConnectionCubicWebRequestBase``. |
|
123 |
|
124 .. autoclass:: cubicweb.req.RequestSessionBase |
|
125 :members: |
|
126 |
|
127 .. autoclass:: cubicweb.repoapi.Connection |
|
128 :members: |
|
129 |
|
130 .. autoclass:: cubicweb.web.request.ConnectionCubicWebRequestBase |
|
131 :members: |