1 line
6.3 KiB
JSON
1 line
6.3 KiB
JSON
{"name":"load","type":"method","title":".load()","deprecated":null,"removed":null,"desc":"Load data from the server and place the returned HTML into the matched element.","categories":["ajax/shorthand-methods","version/1.0"],"entries":[{"return":"jQuery","signatures":{"added":"1.0","argument":[{"desc":"A string containing the URL to which the request is sent.","name":"url","type":"String"},{"type":[{"name":"PlainObject"},{"name":"String"}],"desc":"A plain object or string that is sent to the server with the request.","name":"data","optional":"true"},{"desc":"A callback function that is executed when the request completes.","name":"complete(responseText, textStatus, XMLHttpRequest)","type":"Function","optional":"true"}]},"examples":[{"desc":"Load the main page's footer navigation into an ordered list.","code":"\n$( \"#new-nav\" ).load( \"/ #jq-footerNavigation li\" );\n","css":"\n body {\n font-size: 12px;\n font-family: Arial;\n }\n","html":"\n<b>Footer navigation:</b>\n<ol id=\"new-nav\"></ol>\n"},{"desc":"Display a notice if the Ajax request encounters an error.","code":"\n$( \"#success\" ).load( \"/not-here.php\", function( response, status, xhr ) {\n if ( status == \"error\" ) {\n var msg = \"Sorry but there was an error: \";\n $( \"#error\" ).html( msg + xhr.status + \" \" + xhr.statusText );\n }\n});\n","css":"\n body {\n font-size: 12px;\n font-family: Arial;\n }\n","html":"\n<b>Successful Response (should be blank):</b>\n<div id=\"success\"></div>\n<b>Error Response:</b>\n<div id=\"error\"></div>\n"},{"desc":"Load the feeds.html file into the div with the ID of feeds.","code":"\n$( \"#feeds\" ).load( \"feeds.html\" );\n","results":"\n<div id=\"feeds\"><b>45</b> feeds found.</div>\n"},{"desc":"pass arrays of data to the server.","code":"\n$( \"#objectID\" ).load( \"test.php\", { \"choices[]\": [ \"Jon\", \"Susan\" ] } );\n"},{"desc":"Same as above, but will POST the additional parameters to the server and a callback that is executed when the server is finished responding.","code":"\n$( \"#feeds\" ).load( \"feeds.php\", { limit: 25 }, function() {\n alert( \"The last 25 entries in the feed have been loaded\" );\n});\n"}],"longdesc":"\n <div class=\"warning\">\n <p>Note: The event handling suite also has a method named <code><a href=\"/load-event/\">.load()</a></code>. jQuery determines which method to fire based on the set of arguments passed to it.</p>\n </div>\n <p>This method is the simplest way to fetch data from the server. It is roughly equivalent to <code>$.get(url, data, success)</code> except that it is a method rather than global function and it has an implicit callback function. When a successful response is detected (i.e. when <code>textStatus</code> is \"success\" or \"notmodified\"), <code>.load()</code> sets the HTML contents of the matched element to the returned data. This means that most uses of the method can be quite simple:</p>\n <pre><code>\n$( \"#result\" ).load( \"ajax/test.html\" );\n </code></pre>\n <p>If no element is matched by the selector — in this case, if the document does not contain an element with id=\"result\" — the Ajax request will <em>not</em> be sent.</p>\n <h4 id=\"callback-function\">Callback Function</h4>\n <p>If a \"complete\" callback is provided, it is executed after post-processing and HTML insertion has been performed. The callback is fired once for each element in the jQuery collection, and <code>this</code> is set to each DOM element in turn.</p>\n <pre><code>\n$( \"#result\" ).load( \"ajax/test.html\", function() {\n alert( \"Load was performed.\" );\n});\n </code></pre>\n <p>In the two examples above, if the current document does not contain an element with an ID of \"result,\" the <code>.load()</code> method is not executed.</p>\n <h4 id=\"request-method\">Request Method</h4>\n <p>The POST method is used if data is provided as an object; otherwise, GET is assumed.</p>\n <h4 id=\"loading-page-fragments\">Loading Page Fragments</h4>\n <p>The <code>.load()</code> method, unlike <code><a href=\"/jQuery.get/\">$.get()</a></code>, allows us to specify a portion of the remote document to be inserted. This is achieved with a special syntax for the <code>url</code> parameter. If one or more space characters are included in the string, the portion of the string following the first space is assumed to be a jQuery selector that determines the content to be loaded. </p>\n <p>We could modify the example above to use only part of the document that is fetched:</p>\n <pre><code>\n$( \"#result\" ).load( \"ajax/test.html #container\" );\n </code></pre>\n <p>When this method executes, it retrieves the content of <code>ajax/test.html</code>, but then jQuery parses the returned document to find the element with an ID of <code>container</code>. This element, along with its contents, is inserted into the element with an ID of <code>result</code>, and the rest of the retrieved document is discarded.</p>\n <p>jQuery uses the browser's <code>.innerHTML</code> property to parse the retrieved document and insert it into the current document. During this process, browsers often filter elements from the document such as <code><html></code>, <code><title></code>, or <code><head></code> elements. As a result, the elements retrieved by <code>.load()</code> may not be exactly the same as if the document were retrieved directly by the browser.</p>\n <h4 id=\"script-execution\">Script Execution</h4>\n <p> When calling <code>.load()</code> using a URL without a suffixed selector expression, the content is passed to <code>.html()</code> prior to scripts being removed. This executes the script blocks before they are discarded. If <code>.load()</code> is called with a selector expression appended to the URL, however, the scripts are stripped out prior to the DOM being updated, and thus are <em>not</em> executed. An example of both cases can be seen below:</p>\n <p>Here, any JavaScript loaded into <code>#a</code> as a part of the document will successfully execute.</p>\n <pre><code>\n$( \"#a\" ).load( \"article.html\" );\n </code></pre>\n <p>However, in the following case, script blocks in the document being loaded into <code>#b</code> are stripped out and not executed:</p>\n <pre><code>\n$( \"#b\" ).load( \"article.html #target\" );\n </code></pre>\n "}]} |