Codex tools: Log in
Languages: English • Español • Русский • 中文(简体) • 한국어 • (Add your language)
Contents |
A safe way of adding javascripts to a WordPress generated page. Basically, include the script if it hasn't already been included, and load the one that WordPress ships.
wp_enqueue_script(
$handle
,$src
,$deps
,$ver
,$in_footer
);
Use the wp_enqueue_scripts action to call this function, or admin_enqueue_scripts to call it on the admin side.
wp_head is run, even if it will be placed in the footer. (New in WordPress 2.8)
Note: This function will not work if it is called from a wp_head or wp_print_scripts actions, as the files need to be enqueued before those actions are run. See the Usage section for the correct hooks to use.
Please Note: It is not recommended that a theme force a 3rd party served JavaScript or CSS file by default, Doing so opens the users up to reliance upon a external host which is out of their control. A much better alternative is to use/recomend a Plugin such as Plugin: Use Google Libraries which automatically uses the Google-CDN served jQuery of the same version that WordPress uses this ultimately reduces breakage caused by Themes/Plugins which hardcode the file to use.
Suppose you want to use the CDN copy of jQuery instead of WordPress’s, add this code to your functions.php file.
<?php
function my_scripts_method() {
wp_deregister_script( 'jquery' );
wp_register_script( 'jquery', 'http://ajax.googleapis.com/ajax/libs/jquery/1.6/jquery.min.js');
wp_enqueue_script( 'jquery' );
}
add_action('wp_enqueue_scripts', 'my_scripts_method');
?>
by using the wp_enqueue_scripts hook (instead of the init hook which many articles reference), we avoid registering the alternate jQuery on admin pages, which will cause post editing (amongst other things) to break after upgrades often.
<?php
function my_scripts_method() {
wp_enqueue_script('scriptaculous');
}
add_action('wp_enqueue_scripts', 'my_scripts_method'); // For use on the Front end (ie. Theme)
?>
The above example only loads the Scriptaculous library on the front end, If it was needed within the admin, you could use the admin_enqueue_scripts action instead, however this enqueues it on ALL admin pages, which often leads to plugin/core conflicts, ultimately breaking the WordPress admin experience. Instead, You should only load it on the individual pages you need it, See the Load scripts only on Plugin pages section for an example of that.
Add and load a new script that depends on scriptaculous (this will also cause it to load scriptaculous into the page as well):
<?php
function my_scripts_method() {
wp_enqueue_script('newscript',
/* WP_PLUGIN_URL . '/someplugin/js/newscript.js', // old way, not SSL compatible */
plugins_url('/js/newscript.js', __FILE__), // where the this file is in /someplugin/
array('scriptaculous'),
'1.0' );
}
add_action('wp_enqueue_scripts', 'my_scripts_method');
?>
Often JavaScript files included in Themes require another JavaScript file to be loaded before the themes JavaScript file, WordPress offers an API for marking Dependencies when registering a script, For Example, the below theme requires jQuery for the custom_script JavaScript file:
<?php
function my_scripts_method() {
// register your script location, dependencies and version
wp_register_script('custom_script',
get_template_directory_uri() . '/js/custom_script.js',
array('jquery'),
'1.0' );
// enqueue the script
wp_enqueue_script('custom_script');
}
add_action('wp_enqueue_scripts', 'my_scripts_method');
?>
<?php
add_action( 'admin_init', 'my_plugin_admin_init' );
add_action( 'admin_menu', 'my_plugin_admin_menu' );
function my_plugin_admin_init() {
/* Register our script. */
wp_register_script( 'my_plugin_script', plugins_url('/script.js', __FILE__) );
}
function my_plugin_admin_menu() {
/* Register our plugin page */
$page = add_submenu_page( 'edit.php', // The parent page of this menu
__( 'My Plugin', 'myPlugin' ), // The Menu Title
__( 'My Plugin', 'myPlugin' ), // The Page title
'manage_options', // The capability required for access to this item
'my_plugin-options', // the slug to use for the page in the URL
'my_plugin_manage_menu' // The function to call to render the page
);
/* Using registered $page handle to hook script load */
add_action('admin_print_styles-' . $page, 'my_plugin_admin_styles');
}
function my_plugin_admin_styles() {
/*
* It will be called only on your plugin admin page, enqueue our script here
*/
wp_enqueue_script( 'my_plugin_script' );
}
function my_plugin_manage_menu() {
/* Output our admin page */
}
?>
Note: The jQuery library included with WordPress loads in "no conflict" mode. This is to prevent compatibility problems with other javascript libraries that WordPress can load.
In "no-confict" mode, the $ shortcut is not available and the longer jQuery is used. For example:
$(document).ready(function(){
$(#somefunction) ...
});
Becomes:
jQuery(document).ready(function(){
jQuery(#somefunction) ...
});
In order to use the default jQuery shortcut of $, you can use the following wrapper around your code:
jQuery(document).ready(function($) {
// $() will work as an alias for jQuery() inside of this function
});
That wrapper will cause your code to be executed when the page finishes loading, and the $ will work for calling jQuery. If, for some reason, you want your code to execute immediately (instead of waiting for the DOM ready event), then you can use this wrapper method instead:
(function($) {
// $() will work as an alias for jQuery() inside of this function
})(jQuery);
| Script Name | Handle |
|---|---|
| Scriptaculous Root | scriptaculous-root |
| Scriptaculous Builder | scriptaculous-builder |
| Scriptaculous Drag & Drop | scriptaculous-dragdrop |
| Scriptaculous Effects | scriptaculous-effects |
| Scriptaculous Slider | scriptaculous-slider |
| Scriptaculous Sound | scriptaculous-sound |
| Scriptaculous Controls | scriptaculous-controls |
| Scriptaculous | scriptaculous |
| Image Cropper | Image cropper (not used in core, see jcrop) |
| Jcrop | Image copper |
| SWFObject | swfobject |
| SWFUpload | swfupload |
| SWFUpload Degrade | swfupload-degrade |
| SWFUpload Queue | swfupload-queue |
| SWFUpload Handlers | swfupload-handlers |
| jQuery | jquery |
| jQuery Form | jquery-form |
| jQuery Color | jquery-color |
| jQuery UI Core | jquery-ui-core (Att.: This is not the whole core incl. all core plugins. Just the base core.) |
| jQuery UI Accordion | jquery-ui-accordion |
| jQuery UI Tabs | jquery-ui-tabs |
| jQuery UI Sortable | jquery-ui-sortable |
| jQuery UI Draggable | jquery-ui-draggable |
| jQuery UI Droppable | jquery-ui-droppable |
| jQuery UI Selectable | jquery-ui-selectable |
| jQuery UI Datepicker | jquery-ui-datepicker |
| jQuery UI Resizable | jquery-ui-resizable |
| jQuery UI Dialog | jquery-ui-dialog |
| jQuery Schedule | schedule |
| jQuery Suggest | suggest |
| ThickBox | thickbox |
| jQuery Hotkeys | jquery-hotkeys |
| Simple AJAX Code-Kit | sack |
| QuickTags | quicktags |
| Farbtastic (color picker) | farbtastic |
| ColorPicker (deprecated) | colorpicker |
| Tiny MCE | tiny_mce |
| Prototype Framework | prototype |
| Autosave | autosave |
| WordPress AJAX Response | wp-ajax-response |
| List Manipulation | wp-lists |
| WP Common | common |
| WP Editor | editor |
| WP Editor Functions | editor-functions |
| AJAX Cat | ajaxcat |
| Admin Categories | admin-categories |
| Admin Tags | admin-tags |
| Admin custom fields | admin-custom-fields |
| Password Strength Meter | password-strength-meter |
| Admin Comments | admin-comments |
| Admin Users | admin-users |
| Admin Forms | admin-forms |
| XFN | xfn |
| Upload | upload |
| PostBox | postbox |
| Slug | slug |
| Post | post |
| Page | page |
| Link | link |
| Comment | comment |
| Threaded Comments | comment-repy |
| Admin Gallery | admin-gallery |
| Media Upload | media-upload |
| Admin widgets | admin-widgets |
| Word Count | word-count |
| Theme Preview | theme-preview |
| JSON for JS | json2 |
For a detailed list of names that can be used as $handle, see Notes on wp_register_script();.
Since: 2.6 (BackPress version: r16)
wp_enqueue_script() is located in wp-includes/functions.wp-scripts.php.
wp_register_script(), wp_deregister_script(), wp_enqueue_script(), wp_dequeue_script(), (action) admin_enqueue_scripts
