Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 225 lines (167 sloc) 11.365 kb
fcc4fff @phiggins42 monster commit from moinconverter, which is always done prior to the svn...
phiggins42 authored
1 .. _dojo/io/iframe:
48c37d8 copy/paste from the Dojo book
MarcusReimann authored
2
0c3cdfe @phiggins42 no message
phiggins42 authored
3 dojo.io.iframe
4 ==============
48c37d8 copy/paste from the Dojo book
MarcusReimann authored
5
6 :Status: Contributed, Draft
7 :Version: 1.0
8 :Available: since V0.9
9
10 .. contents::
11 :depth: 2
12
7bf73d9 no message
MarcusReimann authored
13 dojo.io.frame sends an AJAX I/O call using an IFrame (for instance, to upload files).
48c37d8 copy/paste from the Dojo book
MarcusReimann authored
14
4aff885 no message
jaredj authored
15 ============
16 Introduction
17 ============
18
91634e7 no message
jaredj authored
19 The iframe IO functions are intended to handle complex IO operations that cannot be done through a basic dojo.xhr*() call. These situations are fairly common and include the following:
4aff885 no message
jaredj authored
20
30cfdfa no message
jaredj authored
21 * Calling a service on a server other than the one that originated the calling page (cross-domain request). Note that in this case, the response body cannot be read. So you can send stuff, but not get any replies.
4aff885 no message
jaredj authored
22 * Uploading files from a form (File Input controls). The normal XHR mechanism cannot access file data referenced by file selection tags as a security measure. An iframe, however, can, so by proxying those calls through an iframe make it possible to still do file uploads in an asynchronous manner.
48c37d8 copy/paste from the Dojo book
MarcusReimann authored
23
fcc4fff @phiggins42 monster commit from moinconverter, which is always done prior to the svn...
phiggins42 authored
24 It also retains much of the same operating semantics as dojo.xhrGet with regards to how you get the response from the service. All results are response data is returned through callbacks. There is a caveat to this; it requires the server to send the responese back in a very specific format, please refer to the :ref:`Additional Information <dojo/io/iframe>` section.
5ad6a34 no message
jaredj authored
25
48c37d8 copy/paste from the Dojo book
MarcusReimann authored
26 =====
27 Usage
28 =====
29
fcc4fff @phiggins42 monster commit from moinconverter, which is always done prior to the svn...
phiggins42 authored
30 Usage is similar to :ref:`dojo.xhrGet <dojo/xhrGet>` and :ref:`dojo.xhrPost <dojo/xhrPost>`. Please see below for information on specific properties that are accepted by the dojo.io.iframe functions and what they control.
75120f8 no message
jaredj authored
31
4aff885 no message
jaredj authored
32 dojo.io.iframe supported object properties
33 -------------------------------------------
3ef39e9 no message
jaredj authored
34
35 +------------------+----------------------------------------------------------------------------------------------------------------------------+
36 |**url** |The URL to make the iframe request to. This URL can refer to servers other than the one that originated the calling page. |
37 +------------------+----------------------------------------------------------------------------------------------------------------------------+
38 |**handleAs** |This parameter specifies how to handle the data returned from the server. It usually takes values of 'text', 'xml', or |
39 | |'json'. What those values do is instruct it to try and hand the data to the asynchronous callback functions in that format.|
40 | |Naturally if you specify a format that doesn't match what the server sends you will likely get an error. |
41 | | |
42 | |The currently supported options are: |
43 | | |
44 | |* text (default) |
45 | |* json |
46 | |* xml |
47 | |* html |
aeefb03 no message
jaredj authored
48 | |* javascript |
3ef39e9 no message
jaredj authored
49 | | |
50 | |**This parameter is optional** |
51 +------------------+----------------------------------------------------------------------------------------------------------------------------+
52 |**method** |The HTTP method to use when sending the iframe IO request. It can be either **GET** or **POST** with the value of POST as |
53 | |the default. |
54 | | |
55 | |**This parameter is optional** |
56 +------------------+----------------------------------------------------------------------------------------------------------------------------+
e2b395c no message
jaredj authored
57 |**form** |For posting FORM data, you can provide a either the DOM node of your form or the ID of the form. The dojo.io.iframe call |
0cb9f30 no message
jaredj authored
58 | |will convert this into proper POST format (query params or form content) and send it via the iframe |
e2b395c no message
jaredj authored
59 | | |
60 | |**This parameter is optional** |
61 +------------------+----------------------------------------------------------------------------------------------------------------------------+
3ef39e9 no message
jaredj authored
62 |**content** |A JavaScript object of name/string value pairs. These items are normally converted to query parameters and passed on as |
63 | |part of the url. The caveat to this is if you also specify a 'form' argument. If a form argument was also provided, then |
64 | |then the parameters of 'content' are merged into the values from the form and the whole thing is send as a multi-part form |
f03d4a9 no message
jaredj authored
65 | |post. |
3ef39e9 no message
jaredj authored
66 | | |
67 | |**This parameter is optional** |
68 +------------------+----------------------------------------------------------------------------------------------------------------------------+
69
70
d34a66b no message
jaredj authored
71 Additional Information
72 ----------------------
e735e00 no message
MarcusReimann authored
73
75120f8 no message
jaredj authored
74 dojo.io.iframe calls cannot be made synchronous; therefore trying to set the 'sync' parameter (as shown in dojo.xhrGet()) will do nothing.
75
30f5905 no message
jaredj authored
76 **IMPORTANT:** For all values EXCEPT html and xml, The server response should be an HTML file with a textarea element. The response data should be inside the textarea element. Using an HTML document is the only reliable, cross-browser way this transport can know when the response has loaded. For the text/html (Or XML) mimetype, just return a normal HTML/XML document. In other words, your services for JSON and Text formats should return the data wrapped as the following:
3fe0caf no message
jaredj authored
77
73dbfc6 no message
jaredj authored
78 .. code-block :: javascript
79 :linenos:
80
3fe0caf no message
jaredj authored
81 <html>
75bdf14 no message
jaredj authored
82 <body>
83 <textarea>
84 payload
85 </textarea>
86 </body>
3fe0caf no message
jaredj authored
87 </html>
88
33bfa30 no message
jaredj authored
89
89c9013 @savoyboy Removed a trailing comma from one of the examples, and fixed a spelling ...
savoyboy authored
90 Other than the reason noted above about reliability (getting proper events indicating data retrieved), the choice of using textarea was because a textarea provides a fixed container that dojo can locate in the iframe DOM and extract the contents from. And since it is a text area, it can contain JSON, XML, Text, etc. Once the data is obtained, the usual data handlers from dojo process it and pass it back through the callbacks specified by the user.
48c37d8 copy/paste from the Dojo book
MarcusReimann authored
91
92
93 ========
94 Examples
95 ========
96
2257db0 @slightlyoff no message
slightlyoff authored
97
48c37d8 copy/paste from the Dojo book
MarcusReimann authored
98 Gather all parameters from a form
99 ---------------------------------
100
101 .. code-block :: javascript
102 :linenos:
103
104 <script type="text/javascript">
105 dojo.require("dojo.io.iframe");
106
107 // gather all parameters from a form:
108 dojo.io.iframe.send({
2257db0 @slightlyoff no message
slightlyoff authored
109 // The form node, which contains the
110 // data. We also pull the URL and METHOD from it:
111 form: "myForm",
112
113 // The used data format:
114 handleAs: "json",
115
116 // Callback on successful call:
117 load: function(response, ioArgs) {
118 // do something
119 // ...
120
121 // return the response for succeeding callbacks
122 return response;
123 }
124 });
125 </script>
126
127
128 Gather all parameters from a form, over-riding some
129 ----------------------------------------------------
130
131 .. code-block :: javascript
132 :linenos:
133
134 <script type="text/javascript">
135 dojo.require("dojo.io.iframe");
136
137 // gather all parameters from a form:
138 dojo.io.iframe.send({
bcd3681 inline comments
MarcusReimann authored
139 // The target URL on your webserver:
140 url: "iframeHandler.php",
141
2257db0 @slightlyoff no message
slightlyoff authored
142 // The HTTP method to use, form specified POST:
bcd3681 inline comments
MarcusReimann authored
143 method: "GET",
144
145 // The form node, which contains the
146 // to be transfered form elements:
147 form: "myForm",
148
149 // The used data format:
150 handleAs: "json",
151
152 // Callback on successful call:
153 load: function(response, ioArgs) {
154 // do something
155 // ...
156
157 // return the response for succeeding callbacks
158 return response;
159 },
48c37d8 copy/paste from the Dojo book
MarcusReimann authored
160
bcd3681 inline comments
MarcusReimann authored
161 // Callback on errors:
162 error: function(response, ioArgs){
163 debug.dir(response);
164
165 // return the response for succeeding callbacks
166 return response;
48c37d8 copy/paste from the Dojo book
MarcusReimann authored
167 }
168 });
169 </script>
170
171
e735e00 no message
MarcusReimann authored
172 Pass in parameters manually
48c37d8 copy/paste from the Dojo book
MarcusReimann authored
173 ---------------------------
174
175 .. code-block :: javascript
176 :linenos:
177
178 <script type="text/javascript">
179 dojo.require("dojo.io.iframe");
180
181 // pass in all of the parameters manually:
182 dojo.io.iframe.send({
bcd3681 inline comments
MarcusReimann authored
183 // The target URL on your webserver:
48c37d8 copy/paste from the Dojo book
MarcusReimann authored
184 url: "iframeHandler.php",
185
bcd3681 inline comments
MarcusReimann authored
186 // The HTTP method to use:
187 method: "GET",
188
48c37d8 copy/paste from the Dojo book
MarcusReimann authored
189 // the content to submit:
190 content: {
191 param1: "la dee dah",
89c9013 @savoyboy Removed a trailing comma from one of the examples, and fixed a spelling ...
savoyboy authored
192 param2: "my poor electrons!"
48c37d8 copy/paste from the Dojo book
MarcusReimann authored
193 },
194
bcd3681 inline comments
MarcusReimann authored
195 // The used data format:
196 handleAs: "json",
197
198 // Callback on successful call:
199 load: function(response, ioArgs) {
200 // do something
201 // ...
202
203 // return the response for succeeding callbacks
204 return response;
205 },
206
207 // Callback on errors:
208 error: function(response, ioArgs){
209 debug.dir(response);
210
211 // return the response for succeeding callbacks
212 return response;
48c37d8 copy/paste from the Dojo book
MarcusReimann authored
213 }
214 });
215 </script>
72cb60f @phiggins42 no message
phiggins42 authored
216
217 ========
218 See Also
219 ========
220
221 A common use of dojo.io.iframe is for uploading files in an Ajax-like manner. There are prefabricated widgets to do this as well, some using iframe transports, some using flash 9+
222
fcc4fff @phiggins42 monster commit from moinconverter, which is always done prior to the svn...
phiggins42 authored
223 * :ref:`File Uploader <dojox/form/FileUploader>`
224 * :ref:`File Input <dojox/form/FileInput>`
Something went wrong with that request. Please try again.