dojo/request/iframe¶
authors: | Bryan Forbes |
---|---|
since: | V1.8 |
Contents
dojo/request/iframe is a provider that uses an IFrame to provide asynchronous requests and responses.
Introduction¶
dojo/request/iframe
deprecates dojo/io/iframe and is part of Dojo’s Request API. It is
designed to handle complex request/response scenarios which cannot be handled by the standard
dojo/request/xhr. The two main scenarios are:
- 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: you can send data, but not get any replies. If you need access to the return data, see dojo/request/script.
- Uploading files from a form (e.g. file input controls). The normal XHR mechanism cannot access file data
referenced by file selection tags as a security measure.
dojo/request/iframe
can by proxying those calls through an IFrame, making it possible to still do file uploads in an asynchronous manner.
dojo/request/iframe
works similar to other providers, but it has some specific caveats because of the nature of
the iframe mechanism.
Usage¶
An example of making a request to retrieve some XML would look like:
require(["dojo/request/iframe"], function(iframe){
iframe("something.xml", {
handleAs: "xml"
}).then(function(xmldoc){
// Do something with the XML document
}, function(err){
// Handle the error condition
});
// Progress events are not supported using the iframe provider
});
dojo/request/iframe
takes two arguments:
Argument | Type | Description |
---|---|---|
url | String | The URL that the request should be made to. |
options | Object? | Optional A hash of options. |
The options
argument supports the following:
Property | Type | Default | Description |
---|---|---|---|
data | String|Object | null |
Data, if any, that should be sent with the request. |
query | String|Object | null |
The query string, if any, that should be sent with the request. |
form | String|DomNode | null |
The form, if any, that should be sent with the request. |
preventCache | Boolean | false |
If true will send an extra query parameter to ensure the browser and the
server won’t supply cached values. |
timeout | Integer | null |
The number of milliseconds to wait for the response. If this time passes the request is canceled and the promise rejected. |
handleAs | String | html |
The content handler to process the response payload with. By default, the HTML document of the iframe is returned as the response’s data. |
method | String | POST |
The HTTP method that should be used to send the request.
dojo/request/iframe only supports POST and GET methods. |
dojo/request/iframe()
returns a promise that is fulfilled with the handled data of the response. Errors will be
directed to the errback if supplied. Progress events are not supported by iframe.
get()¶
Same as the base function, but the method
is set to GET
.
post()¶
Same as the base function, but the method
is set to POST
.
create()¶
Creates an IFrame for handling requests and returns a reference to the IFrame. This function is used internally and provided for backwards compatibility reasons.
doc()¶
Returns a reference to the document for the supplied iframeNode
. This function is used internally and provided
for backwards compatibility reasons.
setSrc()¶
Sets the source of an IFrame. The function takes three arguments:
Argument | Type | Description |
---|---|---|
iframe | DomNode | The reference to the IFrame node. |
src | String | The new source. |
replace | Boolean? | Should the new source be set our replaced. Defaults to false . |
This function is used internally and provided for backwards compatibility reasons.
Content Handling¶
Important If your payload is something other than html or xml (e.g. text, JSON) the server response
needs to enclose the content in a <textarea>
tag. This is because this is the only cross-browser way for this
provider to know when the content has been successfully loaded. Therefore the server response should look something
like this:
<html>
<body>
<textarea>
payload
</textarea>
</body>
</html>
Where payload
would be the content that you are actually attempting to load.
Examples¶
This example retrieves some JSON from the server and then outputs the data that is returned.
require(["dojo/request/iframe", "dojo/dom", "dojo/dom-construct", "dojo/json", "dojo/on", "dojo/domReady!"],
function(iframe, dom, domConst, JSON, on){
on(dom.byId("startButton"), "click", function(){
domConst.place("<p>Requesting...</p>", "output");
iframe.get("helloworld.json.html", {
handleAs: "json"
}).then(function(data){
domConst.place("<p>data: <code>" + JSON.stringify(data) + "</code></p>", "output");
});
});
});
<h1>Output:</h1>
<div id="output"></div>
<button type="button" id="startButton">Start</button>
This example intentionally attempts to retrieve a resource that doesn’t exist in order to demonstrate how the error handling works.
require(["dojo/request/iframe", "dojo/dom", "dojo/dom-construct", "dojo/json", "dojo/on", "dojo/domReady!"],
function(iframe, dom, domConst, JSON, on){
on(dom.byId("startButton"), "click", function(){
domConst.place("<p>Requesting...</p>", "output");
iframe("nothing.xml").then(function(data){
domConst.place("<p>data: <code>" + JSON.stringify(data) + "</code></p>", "output");
}, function(err){
domConst.place("<p>error: <p>" + err.response.text + "</p></p>", "output");
});
});
});
<h1>Output:</h1>
<div id="output"></div>
<button type="button" id="startButton">Start</button>
The following example demonstrates how to have the provider automatically post a form.
require(["dojo/request/iframe", "dojo/dom", "dojo/dom-construct", "dojo/json", "dojo/on", "dojo/domReady!"],
function(iframe, dom, domConst, JSON, on){
on(dom.byId("startButton"), "click", function(){
domConst.place("<p>Requesting...</p>", "output");
iframe("helloworld.json.html",{
form: "theForm",
handleAs: "json"
}).then(function(data){
domConst.place("<p>data: <code>" + JSON.stringify(data) + "</code></p>", "output");
});
});
});
<form id="theForm" method="post" enctype="multipart/form-data">
<label for="field1">Field1</label><input type="text" name="field1" value="Hello" /><br />
<label for="field1">Field1</label><input type="text" name="field1" value="World" /><br />
</form>
<h1>Output:</h1>
<div id="output"></div>
<button type="button" id="startButton">Start</button>
See also¶
- dojo/request - The whole Dojo Request API
- dojo/request/xhr - The default provider for a browser based platform
- dojo/request/node - The default provider for the node.js platform
- dojo/request/script - A provider that expects the response to be embedded in a
<script>
tag. - dojo/request/handlers - Handles the data from a response as designated in the
handleAs
request option. Also provides the ability to register additional types of handlers. - dojo/request/registry - Allows for registration of different providers against different URIs.
- dojo/request/notify - Publishes the
dojo/request
topics for requests. - dojo/request/watch - Allows the watching of inflight requests.
- dojo/Deferred - The base class for managing asynchronous processes.
- dojo/promise - The package that provides the Dojo Promise API.