dojo/request/script

authors:Bryan Forbes since:V1.8

Contents

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

dojo/request/script is a provider that uses dynamic <script> tags to make requests and receive responses. It is typically used when cross-domain requests need to be made.

Introduction

dojo/request/script deprecates dojo/io/script and is part of Dojo’s Request API. It is typically used in the scenario where a request needs to be made cross-domain (where the target domain is different than the domain that was used to serve the requesting code). This is accomplished by dynamically inserting <script> tags into the body of the requesting document.

Because of the nature of the requests, JSONP is inherently supported (see: Wikipedia Article on JSON). This is essentially a JSON payload that is wrapped with a callback function that is set up by the provider and executed once the server has completed its response.

There are a couple of limitations to note with dojo/request/script:

• It can only make requests that are GET requests. All other HTTP methods are not supported (POST, PUT and DELETE).
• It cannot be used in synchronous mode like dojo/request/xhr. This means that code using it must handle request asynchronously (which is easily done with the dojo/promise/Promise API).

Usage

There are two main ways of retrieving data with dojo/request/script: JSONP and “check string”. To use JSONP (which is recommended), set the jsonp option to the name of the query parameter the server is expecting the name of the callback function to appear in. For instance, Yahoo! expects the name of the callback to use to appear in the “callback” query parameter, so the jsonp option would need to be set to "callback". “Check string” is a method in which a global variable will be populated with the data from the server; after injecting the dynamic <script> element, the global variable is checked to see if it has been assigned to. To use “check string”, set the checkString option to the name of the global variable that is defined in the response from the server. If either jsonp or checkString is not set, the provider will simply load and execute the script. Note that for both jsonp and checkString, data is not run through a response handler since both return JavaScript objects; this means the handleAs option is ignored.

Making a JSONP request would look like this:

require(["dojo/request/script"], function(script){
  script.get("something.js", {
    jsonp: "callback"
  }).then(function(data){
    // Do something with the response data
  }, function(err){
    // Handle the error condition
  });
  // Progress events are not supported
});

require(["dojo/request/script"], function(script){ script.get("something.js", { jsonp: "callback" }).then(function(data){ // Do something with the response data }, function(err){ // Handle the error condition }); // Progress events are not supported });

Note dojo/request/script() and dojo/request/script::get() are exactly the same function, but .get() is provided to make this provider API compatible with other providers.

The provider 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
checkString	String	null	The name of a variable that is defined in the loaded script that will determine if the request has finished.
jsonp	String	null	The name of the query parameter the server expects the name of the callback function to appear in.
query	String|Object	null	The query string, 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.

dojo/request/script() returns a promise that is fulfilled with the response. Errors will be directed to the error callack if it is supplied. Progress events are unsupported.

get()

This is a synonym for the base function of the module.

Examples

This example retrieves some JSONP from a webserver and returns the response in the data property.

require(["dojo/request/script", "dojo/dom", "dojo/dom-construct", "dojo/json", "dojo/on", "dojo/domReady!"],
function(script, dom, domConst, JSON, on){
  on(dom.byId("startButton"), "click", function(){
    domConst.place("<p>Requesting...</p>", "output");
    script.get("helloworld.jsonp.js", {
      jsonp: "callback"
    }).then(function(data){
      domConst.place("<p>response data: <code>" + JSON.stringify(data) + "</code></p>", "output");
    });
  });
});

require(["dojo/request/script", "dojo/dom", "dojo/dom-construct", "dojo/json", "dojo/on", "dojo/domReady!"], function(script, dom, domConst, JSON, on){ on(dom.byId("startButton"), "click", function(){ domConst.place("<p>Requesting...</p>", "output"); script.get("helloworld.jsonp.js", { jsonp: "callback" }).then(function(data){ domConst.place("<p>response 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>

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/iframe - A provider that uses IFrame for transport
• dojo/request/registry - Allows for registration of different providers against different URIs.
• dojo/request/notify - Publishes the dojo/request topics for 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/script
  • Introduction
  • Usage
    • get()
  • Examples
  • See also