Skip to content

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
7880d4f dojo/request stub-out
Kitson Kelly authored
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
d810e2b Bryan Forbes Update dojo/request reference guide.
bryanforbes authored
13 **dojo/request/iframe** is a provider that uses an IFrame to provide asynchronous requests and responses.
7880d4f dojo/request stub-out
Kitson Kelly authored
14
15 Introduction
16 ============
17
d810e2b Bryan Forbes Update dojo/request reference guide.
bryanforbes authored
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:
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
21
d810e2b Bryan Forbes Update dojo/request reference guide.
bryanforbes authored
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>`.
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
25
d810e2b Bryan Forbes Update dojo/request reference guide.
bryanforbes authored
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.
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
29
d810e2b Bryan Forbes Update dojo/request reference guide.
bryanforbes authored
30 ``dojo/request/iframe`` works similar to other providers, but it has some specific caveats because of the nature of
31 the iframe mechanism.
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
32
7880d4f dojo/request stub-out
Kitson Kelly authored
33 Usage
34 =====
35
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
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"
d810e2b Bryan Forbes Update dojo/request reference guide.
bryanforbes authored
43 }).then(function(xmldoc){
44 // Do something with the XML document
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
45 }, function(err){
46 // Handle the error condition
47 });
d810e2b Bryan Forbes Update dojo/request reference guide.
bryanforbes authored
48 // Progress events are not supported using the iframe provider
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
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
d810e2b Bryan Forbes Update dojo/request reference guide.
bryanforbes authored
62 ============ ============== ========= =============================================================================
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
63 Property Type Default Description
d810e2b Bryan Forbes Update dojo/request reference guide.
bryanforbes authored
64 ============ ============== ========= =============================================================================
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
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.
d810e2b Bryan Forbes Update dojo/request reference guide.
bryanforbes authored
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 ============ ============== ========= =============================================================================
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
77
d810e2b Bryan Forbes Update dojo/request reference guide.
bryanforbes authored
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.
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
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
d810e2b Bryan Forbes Update dojo/request reference guide.
bryanforbes authored
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.
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
96
97 doc()
98 -----
99
d810e2b Bryan Forbes Update dojo/request reference guide.
bryanforbes authored
100 Returns a reference to the document for the supplied ``iframeNode``. This function is used internally and provided
101 for backwards compatibility reasons.
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
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
d810e2b Bryan Forbes Update dojo/request reference guide.
bryanforbes authored
116 This function is used internally and provided for backwards compatibility reasons.
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
117
118 Content Handling
119 ----------------
120
d810e2b Bryan Forbes Update dojo/request reference guide.
bryanforbes authored
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:
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
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
7880d4f dojo/request stub-out
Kitson Kelly authored
138 Examples
139 ========
140
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
141 .. code-example ::
3073895 Bill Keese Set djConfig async: true and parseOnLoad: false
wkeese authored
142 :djConfig: async: true, parseOnLoad: false
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
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"
d810e2b Bryan Forbes Update dojo/request reference guide.
bryanforbes authored
154 }).then(function(data){
155 domConst.place("<p>data: <code>" + JSON.stringify(data) + "</code></p>", "output");
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
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 ::
3073895 Bill Keese Set djConfig async: true and parseOnLoad: false
wkeese authored
167 :djConfig: async: true, parseOnLoad: false
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
168
d810e2b Bryan Forbes Update dojo/request reference guide.
bryanforbes authored
169 This example intentionally attempts to retrieve a resource that doesn't exist in order to demonstrate how the
170 error handling works.
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
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");
d810e2b Bryan Forbes Update dojo/request reference guide.
bryanforbes authored
178 iframe("nothing.xml").then(function(data){
179 domConst.place("<p>data: <code>" + JSON.stringify(data) + "</code></p>", "output");
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
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 ::
3073895 Bill Keese Set djConfig async: true and parseOnLoad: false
wkeese authored
193 :djConfig: async: true, parseOnLoad: false
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
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"
d810e2b Bryan Forbes Update dojo/request reference guide.
bryanforbes authored
206 }).then(function(data){
207 domConst.place("<p>data: <code>" + JSON.stringify(data) + "</code></p>", "output");
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
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
7880d4f dojo/request stub-out
Kitson Kelly authored
222 See also
223 ========
224
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
225 * :ref:`dojo/request <dojo/request>` - The whole Dojo Request API
226
d229c8b Complete dojo/request/script
Kitson Kelly authored
227 * :ref:`dojo/request/xhr <dojo/request/xhr>` - The default provider for a browser based platform
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
228
d229c8b Complete dojo/request/script
Kitson Kelly authored
229 * :ref:`dojo/request/node <dojo/request/node>` - The default provider for the node.js platform
06f1388 Complete dojo/request/iframe
Kitson Kelly authored
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.