WordPress.org

Ready to get started?Download WordPress

Codex

User:T31os/wp enqueue script-draft

Contents

Description

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.

Usage

<?php wp_enqueue_script$handle$src$deps$ver$in_footer ); ?>

It is recommended you call wp_enqueue_script() from within a function hooked onto the wp_enqueue_scripts action, or admin_enqueue_scripts if you want to enqueue a script on an administration page. Usage outside of these actions can be problematic in some cases, see: #11526 for details.

Parameters

$handle
(string) (required) Name of the script. Lowercase string.
Default: None
$src
(string) (optional) A complete URL to the script you wish to load. This parameter is only required for scripts not included with WordPress.
Default: None
$deps
(array) (optional) Array of handles of any script that this script depends on; scripts that must be registered before this script. False if there are no dependencies.
Default: array()
$ver
(string) (optional) String specifying the script version number, if it has one, which is concatenated to the end of the path as a query string. Defaults to false. If no version is specified or set to false then wordpress automatically adds a version number equal to the current version of wordpress you are running. This parameter is used to ensure that the correct version is sent to the client regardless of caching, and so should be included if a version number is available and makes sense for the script. If you do not want any version number, you must pass in NULL to this parameter. Passing in NULL is not recommended unless you know what you are doing.
Default: false
$in_footer
(boolean) (optional) Normally scripts are placed in the <head> section. If this parameter is true the script is placed at the bottom of the <body>. This requires the theme to have the wp_footer() hook in the appropriate place. Note that you have to enqueue your script before wp_head is run, even if it will be placed in the footer. (New in WordPress 2.8)
Default: false

Return Values

(void) 
This function does not return a value.

Examples

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.

Choosing the right hook

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.

Administration pages

The following action is recommended for loading Javascript on administration pages.

add_action( 'admin_enqueue_scripts', 'my_enqueue_scripts' );
Front-facing pages

The following action is recommended for loading Javascript on front-facing pages.

add_action( 'wp_enqueue_scripts', 'my_enqueue_scripts' );

Loading your own Javascript

Now you are ready to call to your script, simply call the enqueue function inside your callback function.

Script locations

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
It is recommended that you use the 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__ ) );            
}    
?>
Parent themes
It is recommended that you use the 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' );            
}    
?>
Child themes
It is recommended that you use the 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' );            
}    
?>

Scripts for plugins

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.

Plugin administration pages
<?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 */
}
?>
Content areas

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.

Using the included Javascript libraries

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.

Loading jQuery on front-facing pages

<?php
function my_enqueue_scripts() {
    wp_enqueue_script( 'jquery' );            
}
add_action( 'wp_enqueue_scripts', 'my_enqueue_scripts' );
?>

Scripts that require jQuery

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.

Using jQuery functions in WordPress

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();
});

Default scripts included with WordPress

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

Notes

  • See WP_Scripts::add_data(), WP_Scripts::enqueue()
  • Uses global: (unknown type) $wp_scripts
  • jQuery UI Effects is NOT included with the jquery-ui-core

Change Log

Since: 2.6 (BackPress version: r16)

Source File

wp_enqueue_script() is located in wp-includes/functions.wp-scripts.php.

Resources

Related

wp_register_script(), wp_deregister_script(), wp_enqueue_script(), wp_dequeue_script()

See also index of Function Reference and index of Template Tags.
This article is marked as in need of editing. You can help Codex by editing it.