Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Updated cache:true instructions for $.getScript #1054

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Updated cache:true instructions for $.getScript #1054

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8ac6b75
Add missing signature
oriadam Jul 5, 2017
7165cd0
Add missing signature
oriadam Jul 5, 2017
2fd585d
JavaScript Style Guide
oriadam Feb 10, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
232 changes: 120 additions & 112 deletions entries/jQuery.getScript.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,128 +1,136 @@
<?xml version="1.0"?>
<entry type="method" name="jQuery.getScript" return="jqXHR">
<title>jQuery.getScript()</title>
<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>
<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
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>
</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." );
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>
</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 setting the cache property globally using <a href="/jquery.ajaxsetup/"><code>$.ajaxSetup()</code></a>: </p>
<pre><code>
$.ajaxSetup({
cache: true
});
</code></pre>
<p>Alternatively, you could define a new method that uses the more flexible <code>$.ajax()</code> method.</p>
</longdesc>
<example>
<desc>Define a $.cachedScript() method that allows fetching a cached script:</desc>
<code><![CDATA[
jQuery.cachedScript = function( url, options ) {
.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>
oriadam marked this conversation as resolved.
Show resolved Hide resolved
<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",

// Allow user to set any option except for dataType, cache, and url
options = $.extend( options || {}, {
dataType: "script",
cache: true,
url: url
});
// Enable browser caching. Cache is highly recommended when loading static scripts such as plugins.
cache: true
};

// Use $.ajax() since it is more flexible than $.getScript
// Return the jqXHR object so we can chain callbacks
return jQuery.ajax( options );
};

// Usage
$.cachedScript( "ajax/test.js" ).done(function( script, textStatus ) {
console.log( textStatus );
});
]]></code>
</example>
<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.</desc>
<code><![CDATA[
var url = "https://code.jquery.com/color/jquery.color.js";
$.getScript( url, function() {
$( "#go" ).click(function() {
$( ".block" )
.animate({
backgroundColor: "rgb(255, 180, 180)"
}, 1000 )
.delay( 500 )
.animate({
backgroundColor: "olive"
}, 1000 )
.delay( 500 )
.animate({
backgroundColor: "#00f"
}, 1000 );
});
// Override toString for backward compatibility with jQuery prior to 1.12 (though it will prevent browser caching)
settings.toString = function() {
oriadam marked this conversation as resolved.
Show resolved Hide resolved
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[
<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><![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"/>
</example>
<category slug="ajax/shorthand-methods"/>
<category slug="version/1.0"/>
<category slug="version/1.5"/>
</entry>