jQuery.getScript.xml

<?xml version="1.0"?>
<entry type="method" name="jQuery.getScript" return="jqXHR">
	<title>jQuery.getScript()</title>
	<signature>
		<added>1.12</added>
		<argument name="settings" type="PlainObject">
				<desc>A set of key/value pairs that configure the Ajax request. All settings are optional except for <code>url</code>. See <a href="/jQuery.ajax/#jQuery-ajax-settings">jQuery.ajax( settings )</a> for a complete list of all settings.</desc>
		</argument>
		<argument name="success" optional="true" type="Function">
			<argument name="script" type="String" />
			<argument name="textStatus" type="String"/>
			<argument name="jqXHR" type="jqXHR"/>
			<desc>A callback function that is executed if the request succeeds.</desc>
		</argument>
	</signature>
	<signature>
		<added>1.0</added>
		<argument name="url" type="String">
			<desc>A string containing the URL to which the request is sent.</desc>
		</argument>
		<argument name="success" optional="true" type="Function">
			<argument name="script" type="String" />
			<argument name="textStatus" type="String"/>
			<argument name="jqXHR" type="jqXHR"/>
			<desc>A callback function that is executed if the request succeeds.</desc>
		</argument>
	</signature>
	<desc>Load a JavaScript file from the server using a GET HTTP request, then execute it.</desc>
	<longdesc>
		<p>This is a shorthand Ajax function, which is equivalent to:</p>
		<pre><code>
$.ajax({
	url: url,
	dataType: "script",
	success: success
});
		</code></pre>
		<p>The script is executed in the global context, so it can refer to other variables and use jQuery functions. Included scripts can have some impact on the current page.</p>
		<h4 id="success-callback">Success Callback</h4>
		<p>The callback is fired once the script has been loaded but not necessarily executed.</p>
		<p>Scripts are included and run by referencing the file name:</p>
		<pre><code>
$.getScript( "ajax/test.js", function( data, textStatus, jqxhr ) {
	console.log( data ); // Data returned
	console.log( textStatus ); // Success
	console.log( jqxhr.status ); // 200
	console.log( "Load was performed." );
});
		</code></pre>
		<h4 id="handling-errors">Handling Errors</h4>
		<p>As of jQuery 1.5, you may use <a href="/deferred.fail/"><code>.fail()</code></a> to account for errors:</p>
		<pre><code>
$.getScript( "ajax/test.js" )
	.done( function( script, textStatus ) {
		console.log( textStatus );
	} )
	.fail( function( jqxhr, settings, exception ) {
		$( "div.log" ).text( "Triggered ajaxError handler." );
	} );
		</code></pre>
		<p>Prior to jQuery 1.5, the global <code>.ajaxError()</code> callback event had to be used in order to handle <code>$.getScript()</code> errors:</p>
		<pre><code>
$( "div.log" )
	.ajaxError( function( e, jqxhr, settings, exception ) {
		if ( settings.dataType === "script" ) {
			$( this ).text( "Triggered ajaxError handler." );
		}
	} );
		</code></pre>
		<h4 id="caching-requests">Caching Responses</h4>
		<p>By default, <code>$.getScript()</code> sets the cache setting to <code>false</code>. This appends a timestamped query parameter to the request URL to ensure that the browser downloads the script each time it is requested. 
			You can override this feature by using a settings object, as of jQuery 1.12:</p>
			<pre><code>
$.getScript( {
	url: "foo.js",
	cache: true
} );
	</code></pre>
	
	<p>You can also override this feature by setting the cache property globally using <a href="/jquery.ajaxsetup/"><code>$.ajaxSetup()</code></a>:</p>
	<pre><code>
$.ajaxSetup( {
	cache: true
} );
$.getScript( "foo.js" );
	</code></pre>
		
	<p></p>
	</longdesc>
	<example>
		<desc>Load the <a href="https://github.com/jquery/jquery-color">official jQuery Color Animation plugin</a> dynamically and bind some color animations to occur once the new functionality is loaded. Enable browser caching.</desc>
		<code><![CDATA[
var settings = {
		url: "https://code.jquery.com/color/jquery.color.js",

		// Enable browser caching. Cache is highly recommended when loading static scripts such as plugins.
		cache: true 
	};

	// Override toString for backward compatibility with jQuery prior to 1.12 (though it will prevent browser caching)
	settings.toString = function() {
		return this.url;
	};
$.getScript( settings, function() {
	$( "body,div" )
		.css( "background", "" )
		.animate( {
			backgroundColor: "rgb(255, 180, 180)"
		}, 500 )
		.delay( 500 )
		.animate( {
			backgroundColor: "olive"
		}, 500 )
		.delay( 500 )
		.animate( {
			backgroundColor: "#00f"
		}, 500 );
});
]]></code>
		<html><![CDATA[
<button id="go">&raquo; Run</button>
<div class="block"></div>
]]></html>
		<css><![CDATA[
	.block {
		background-color: blue;
		width: 150px;
		height: 70px;
		margin: 10px;
	}
]]></css>
	</example>
	<category slug="ajax/shorthand-methods"/>
	<category slug="version/1.0"/>
	<category slug="version/1.5"/>
</entry>