Languages: English • Español • Русский • (Add your language)
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.
<?php wp_enqueue_script( $handle, $src, $deps, $ver, $in_footer ); ?>
NULL to this parameter. Passing in NULL is not recommended unless you know what you are doing.
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 action, as the <script> tags are output before wp_head runs.
When loading a script inside WordPress first think about where you need the script, do you want to load the script on front facing pages or for an administration page, where you need the script will determine the appropriate action to load a script on.
Once you have determined the type of page you wish to load the script, you can then proceed and attach your own function to the appropriate action.
The following action is recommended for loading Javascript on administration pages.
add_action( 'admin_enqueue_scripts', 'my_enqueue_scripts' );
The following action is recommended for loading Javascript on front-facing pages.
add_action( 'wp_enqueue_scripts', 'my_enqueue_scripts' );
Now you are ready to call to your script, simply call the enqueue function inside your callback function.
When loading scripts inside WordPress you should try to never hardcode the locations of your scripts, there are several helper functions available to help create URLs to typical locations, such as the current theme directory or a custom plugin directory.
plugins_url() function to generate the URL to plugin scripts.
<?php
function my_enqueue_scripts() {
wp_enqueue_script( 'example-handle', plugins_url( '/example.js', __FILE__ ) );
}
?>
get_template_directory_uri() function to generate the URL to parent theme scripts.
<?php
function my_enqueue_scripts() {
wp_enqueue_script( 'example-handle', get_template_directory_uri() . '/example.js' );
}
?>
get_styelsheet_directory_uri() function to generate the URL to child theme scripts.
<?php
function my_enqueue_scripts() {
wp_enqueue_script( 'example-handle', get_stylesheet_directory_uri() . '/example.js' );
}
?>
There may be times when you want to load a script for a plugin page you would not necessarily want that script to load on every page, so how is it possible to load that script for a particular page.
The admin action for enqueuing scripts passes the name of the current page to the function that hooks on, this data tells us the hook name for the current page. To selectively load the Javascript, we use some conditional logic to load the script only when the hook matches the plugin's hook. Similarly the front facing pages have an equivalent action and some basic conditional logic can be used to determine the type of page currently being viewed.
<?php
$plugin_hook = '';
add_action( 'admin_menu', 'example_plugin_admin_menu' );
function example_plugin_admin_menu() {
global $plugin_hook;
$plugin_hook = add_management_page( 'My Example Plugin', 'My Example Plugin', 'manage_options', 'example_plugin_handle', 'example_plugin_manage_menu' );
add_action( 'admin_enqueue_scripts', 'example_admin_enqueue_scripts' );
}
function example_admin_enqueue_scripts( $current_hook ) {
global $plugin_hook;
// If the current hook matches
if( $plugin_hook == $current_hook )
// Load the script
wp_enqueue_script( 'your-script-handle', plugins_url( '/your-script-name.js', __FILE__ ) );
}
function example_plugin_manage_menu() {
/* Output for admin page */
}
?>
For content areas, ie. front facing pages the task is actually a little easier, the callback function can make use the conditional tags provided by WordPress, allowing you to selectively load scripts based on page, category, and various other factors.
add_action( 'wp_enqueue_scripts', 'example_wp_enqueue_scripts' );
function example_wp_enqueue_scripts() {
if( is_page( 'special-page' ) )
wp_enqueue_script( 'your-script-handle', plugins_url( '/your-script-name.js', __FILE__ ) );
}
NOTE: If you are using this code inside the functions file of a theme you cannot use plugins_url to build the URL, refer to the Loading your own Javascript for information on how to generate URLs to theme files.
WordPress comes with various Javascript libraries included, you are not required to register or define the URL to these files, because they have already been registered internally for you.
<?php
function my_enqueue_scripts() {
wp_enqueue_script( 'jquery' );
}
add_action( 'wp_enqueue_scripts', 'my_enqueue_scripts' );
?>
If you are writing your own jQuery, or simply have a script that depends upon jQuery, you can make use of the dependancy argument to ensure the required script is included before your custom script.
<?php
function my_enqueue_scripts() {
wp_enqueue_script( 'example-handle', 'path', array( 'jquery' ) );
}
add_action( 'wp_enqueue_scripts', 'my_enqueue_scripts' );
?>
Refer to the Loading your own Javascript section for information on how to set the file 'path' appropriately.
The jQuery library included with WordPress loads in "noConflict" mode. This is to prevent compatibility problems with other javascript libraries that WordPress can load.
In "noConflict" mode, the $ shortcut is not available and the longer jQuery is used. In order to use the default jQuery shortcut $, you should use a "noConflict", like so:
jQuery(document).ready(function($){
// Example
$('#myel').hide();
});
Or
jQuery(document).ready(function(){
// Example
jQuery('#myel').hide();
});
| 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 Degarade | 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 |
| 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 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 |
| 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 |
| XFN | xfn |
| Media Upload | media-upload |
| PostBox | postbox |
| Post | post |
| Link | link |
| Comment | comment |
| Admin Gallery | admin-gallery |
| Admin widgets | admin-widgets |
| Word Count | word-count |
| Theme Preview | theme-preview |
| JSON for JS | json2 |
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()