dojo/request/iframe

authors:Bryan Forbes
since:V1.8

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

Error in the documentation? Can’t find what you are looking for? Let us know!