Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 247 lines (181 sloc) 9.498 kb
7880d4f9 »
2012-04-27 dojo/request stub-out
1 .. _dojo/request/iframe:
2
3 ===================
4 dojo/request/iframe
5 ===================
6
7 :authors: Bryan Forbes
8 :since: V1.8
9
10 .. contents ::
11 :depth: 2
12
d810e2b0 »
2012-08-14 Update dojo/request reference guide.
13 **dojo/request/iframe** is a provider that uses an IFrame to provide asynchronous requests and responses.
7880d4f9 »
2012-04-27 dojo/request stub-out
14
15 Introduction
16 ============
17
d810e2b0 »
2012-08-14 Update dojo/request reference guide.
18 ``dojo/request/iframe`` deprecates :ref:`dojo/io/iframe <dojo/io/iframe>` and is part of Dojo's Request API. It is
19 designed to handle complex request/response scenarios which cannot be handled by the standard
20 :ref:`dojo/request/xhr <dojo/request/xhr>`. The two main scenarios are:
06f1388c »
2012-05-01 Complete dojo/request/iframe
21
d810e2b0 »
2012-08-14 Update dojo/request reference guide.
22 * Calling a service on a server other than the one that originated the calling page (cross-domain request).
23 Note that in this case, the response body cannot be read: you can send data, but not get any replies. If you
24 need access to the return data, see :ref:`dojo/request/script <dojo/request/script>`.
06f1388c »
2012-05-01 Complete dojo/request/iframe
25
d810e2b0 »
2012-08-14 Update dojo/request reference guide.
26 * Uploading files from a form (e.g. file input controls). The normal XHR mechanism cannot access file data
27 referenced by file selection tags as a security measure. ``dojo/request/iframe`` can by proxying those calls
28 through an IFrame, making it possible to still do file uploads in an asynchronous manner.
06f1388c »
2012-05-01 Complete dojo/request/iframe
29
d810e2b0 »
2012-08-14 Update dojo/request reference guide.
30 ``dojo/request/iframe`` works similar to other providers, but it has some specific caveats because of the nature of
31 the iframe mechanism.
06f1388c »
2012-05-01 Complete dojo/request/iframe
32
7880d4f9 »
2012-04-27 dojo/request stub-out
33 Usage
34 =====
35
06f1388c »
2012-05-01 Complete dojo/request/iframe
36 An example of making a request to retrieve some XML would look like:
37
38 .. js ::
39
40 require(["dojo/request/iframe"], function(iframe){
41 iframe("something.xml", {
42 handleAs: "xml"
d810e2b0 »
2012-08-14 Update dojo/request reference guide.
43 }).then(function(xmldoc){
44 // Do something with the XML document
06f1388c »
2012-05-01 Complete dojo/request/iframe
45 }, function(err){
46 // Handle the error condition
47 });
d810e2b0 »
2012-08-14 Update dojo/request reference guide.
48 // Progress events are not supported using the iframe provider
06f1388c »
2012-05-01 Complete dojo/request/iframe
49 });
50
51 ``dojo/request/iframe`` takes two arguments:
52
53 ======== ======= ===========================================
54 Argument Type Description
55 ======== ======= ===========================================
56 url String The URL that the request should be made to.
57 options Object? *Optional* A hash of options.
58 ======== ======= ===========================================
59
60 The ``options`` argument supports the following:
61
d810e2b0 »
2012-08-14 Update dojo/request reference guide.
62 ============ ============== ========= =============================================================================
06f1388c »
2012-05-01 Complete dojo/request/iframe
63 Property Type Default Description
d810e2b0 »
2012-08-14 Update dojo/request reference guide.
64 ============ ============== ========= =============================================================================
06f1388c »
2012-05-01 Complete dojo/request/iframe
65 data String|Object ``null`` Data, if any, that should be sent with the request.
66 query String|Object ``null`` The query string, if any, that should be sent with the request.
67 form String|DomNode ``null`` The form, if any, that should be sent with the request.
68 preventCache Boolean ``false`` If ``true`` will send an extra query parameter to ensure the browser and the
69 server won't supply cached values.
d810e2b0 »
2012-08-14 Update dojo/request reference guide.
70 timeout Integer ``null`` The number of milliseconds to wait for the response. If this time passes the
71 request is canceled and the promise rejected.
72 handleAs String ``html`` The content handler to process the response payload with. By default, the
73 HTML document of the iframe is returned as the response's data.
74 method String ``POST`` The HTTP method that should be used to send the request.
75 ``dojo/request/iframe`` only supports ``POST`` and ``GET`` methods.
76 ============ ============== ========= =============================================================================
06f1388c »
2012-05-01 Complete dojo/request/iframe
77
d810e2b0 »
2012-08-14 Update dojo/request reference guide.
78 ``dojo/request/iframe()`` returns a promise that is fulfilled with the handled data of the response. Errors will be
79 directed to the errback if supplied. Progress events are not supported by iframe.
06f1388c »
2012-05-01 Complete dojo/request/iframe
80
81 get()
82 -----
83
84 Same as the base function, but the ``method`` is set to ``GET``.
85
86 post()
87 ------
88
89 Same as the base function, but the ``method`` is set to ``POST``.
90
91 create()
92 --------
93
d810e2b0 »
2012-08-14 Update dojo/request reference guide.
94 Creates an IFrame for handling requests and returns a reference to the IFrame. This function is used internally
95 and provided for backwards compatibility reasons.
06f1388c »
2012-05-01 Complete dojo/request/iframe
96
97 doc()
98 -----
99
d810e2b0 »
2012-08-14 Update dojo/request reference guide.
100 Returns a reference to the document for the supplied ``iframeNode``. This function is used internally and provided
101 for backwards compatibility reasons.
06f1388c »
2012-05-01 Complete dojo/request/iframe
102
103 setSrc()
104 --------
105
106 Sets the source of an IFrame. The function takes three arguments:
107
108 ======== ======== ==================================================================
109 Argument Type Description
110 ======== ======== ==================================================================
111 iframe DomNode The reference to the IFrame node.
112 src String The new source.
113 replace Boolean? Should the new source be set our replaced. Defaults to ``false``.
114 ======== ======== ==================================================================
115
d810e2b0 »
2012-08-14 Update dojo/request reference guide.
116 This function is used internally and provided for backwards compatibility reasons.
06f1388c »
2012-05-01 Complete dojo/request/iframe
117
118 Content Handling
119 ----------------
120
d810e2b0 »
2012-08-14 Update dojo/request reference guide.
121 **Important** If your payload is something other than *html* or *xml* (e.g. *text*, *JSON*) the server response
122 needs to enclose the content in a ``<textarea>`` tag. This is because this is the only cross-browser way for this
123 provider to know when the content has been successfully loaded. Therefore the server response should look something
124 like this:
06f1388c »
2012-05-01 Complete dojo/request/iframe
125
126 .. html ::
127
128 <html>
129 <body>
130 <textarea>
131 payload
132 </textarea>
133 </body>
134 </html>
135
136 Where ``payload`` would be the content that you are actually attempting to load.
137
7880d4f9 »
2012-04-27 dojo/request stub-out
138 Examples
139 ========
140
06f1388c »
2012-05-01 Complete dojo/request/iframe
141 .. code-example ::
3073895d »
2012-06-05 Set djConfig async: true and parseOnLoad: false
142 :djConfig: async: true, parseOnLoad: false
06f1388c »
2012-05-01 Complete dojo/request/iframe
143
144 This example retrieves some JSON from the server and then outputs the data that is returned.
145
146 .. js ::
147
148 require(["dojo/request/iframe", "dojo/dom", "dojo/dom-construct", "dojo/json", "dojo/on", "dojo/domReady!"],
149 function(iframe, dom, domConst, JSON, on){
150 on(dom.byId("startButton"), "click", function(){
151 domConst.place("<p>Requesting...</p>", "output");
152 iframe.get("helloworld.json.html", {
153 handleAs: "json"
d810e2b0 »
2012-08-14 Update dojo/request reference guide.
154 }).then(function(data){
155 domConst.place("<p>data: <code>" + JSON.stringify(data) + "</code></p>", "output");
06f1388c »
2012-05-01 Complete dojo/request/iframe
156 });
157 });
158 });
159
160 .. html ::
161
162 <h1>Output:</h1>
163 <div id="output"></div>
164 <button type="button" id="startButton">Start</button>
165
166 .. code-example ::
3073895d »
2012-06-05 Set djConfig async: true and parseOnLoad: false
167 :djConfig: async: true, parseOnLoad: false
06f1388c »
2012-05-01 Complete dojo/request/iframe
168
d810e2b0 »
2012-08-14 Update dojo/request reference guide.
169 This example intentionally attempts to retrieve a resource that doesn't exist in order to demonstrate how the
170 error handling works.
06f1388c »
2012-05-01 Complete dojo/request/iframe
171
172 .. js ::
173
174 require(["dojo/request/iframe", "dojo/dom", "dojo/dom-construct", "dojo/json", "dojo/on", "dojo/domReady!"],
175 function(iframe, dom, domConst, JSON, on){
176 on(dom.byId("startButton"), "click", function(){
177 domConst.place("<p>Requesting...</p>", "output");
d810e2b0 »
2012-08-14 Update dojo/request reference guide.
178 iframe("nothing.xml").then(function(data){
179 domConst.place("<p>data: <code>" + JSON.stringify(data) + "</code></p>", "output");
06f1388c »
2012-05-01 Complete dojo/request/iframe
180 }, function(err){
181 domConst.place("<p>error: <p>" + err.response.text + "</p></p>", "output");
182 });
183 });
184 });
185
186 .. html ::
187
188 <h1>Output:</h1>
189 <div id="output"></div>
190 <button type="button" id="startButton">Start</button>
191
192 .. code-example ::
3073895d »
2012-06-05 Set djConfig async: true and parseOnLoad: false
193 :djConfig: async: true, parseOnLoad: false
06f1388c »
2012-05-01 Complete dojo/request/iframe
194
195 The following example demonstrates how to have the provider automatically post a form.
196
197 .. js ::
198
199 require(["dojo/request/iframe", "dojo/dom", "dojo/dom-construct", "dojo/json", "dojo/on", "dojo/domReady!"],
200 function(iframe, dom, domConst, JSON, on){
201 on(dom.byId("startButton"), "click", function(){
202 domConst.place("<p>Requesting...</p>", "output");
203 iframe("helloworld.json.html",{
204 form: "theForm",
205 handleAs: "json"
d810e2b0 »
2012-08-14 Update dojo/request reference guide.
206 }).then(function(data){
207 domConst.place("<p>data: <code>" + JSON.stringify(data) + "</code></p>", "output");
06f1388c »
2012-05-01 Complete dojo/request/iframe
208 });
209 });
210 });
211
212 .. html ::
213
214 <form id="theForm" method="post" enctype="multipart/form-data">
215 <label for="field1">Field1</label><input type="text" name="field1" value="Hello" /><br />
216 <label for="field1">Field1</label><input type="text" name="field1" value="World" /><br />
217 </form>
218 <h1>Output:</h1>
219 <div id="output"></div>
220 <button type="button" id="startButton">Start</button>
221
7880d4f9 »
2012-04-27 dojo/request stub-out
222 See also
223 ========
224
06f1388c »
2012-05-01 Complete dojo/request/iframe
225 * :ref:`dojo/request <dojo/request>` - The whole Dojo Request API
226
d229c8ba »
2012-05-17 Complete dojo/request/script
227 * :ref:`dojo/request/xhr <dojo/request/xhr>` - The default provider for a browser based platform
06f1388c »
2012-05-01 Complete dojo/request/iframe
228
d229c8ba »
2012-05-17 Complete dojo/request/script
229 * :ref:`dojo/request/node <dojo/request/node>` - The default provider for the node.js platform
06f1388c »
2012-05-01 Complete dojo/request/iframe
230
231 * :ref:`dojo/request/script <dojo/request/script>` - A provider that expects the response to be embedded in a
232 ``<script>`` tag.
233
234 * :ref:`dojo/request/handlers <dojo/request/handlers>` - Handles the data from a response as designated in the
235 ``handleAs`` request option. Also provides the ability to register additional types of handlers.
236
237 * :ref:`dojo/request/registry <dojo/request/registry>` - Allows for registration of different providers against
238 different URIs.
239
240 * :ref:`dojo/request/notify <dojo/request/notify>` - Publishes the ``dojo/request`` topics for requests.
241
242 * :ref:`dojo/request/watch <dojo/request/watch>` - Allows the watching of inflight requests.
243
244 * :ref:`dojo/Deferred <dojo/Deferred>` - The base class for managing asynchronous processes.
245
246 * :ref:`dojo/promise <dojo/promise>` - The package that provides the Dojo Promise API.
Something went wrong with that request. Please try again.