dojo/request/iframe

authors:Bryan Forbes since:V1.8

Contents

• dojo/request/iframe
  • Introduction
  • Usage
  • Examples
  • See also

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
});

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>

<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");
    });
  });
});

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>

<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");
    });
  });
});

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>

<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");
    });
  });
});

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>

<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.

Table of Contents

• dojo/request/iframe
  • Introduction
  • Usage
    • get()
    • post()
    • create()
    • doc()
    • setSrc()
    • Content Handling
  • Examples
  • See also