Child pages
  • Guide to cPanel Interface Customization - jQuery
Skip to end of metadata
Go to start of metadata

Introduction

You can use the jQuery JavaScript library in your cPanel interface customizations.

  • Because of the way in which cPanel & WHM ships and uses jQuery, your custom interfaces must also handle jQuery in specific ways.
  • In cPanel & WHM version 54, we reduced the cPanel interface's jQuery needs. cPanel & WHM now only uses one cPanel-provided version of jQuery. For more information, read our Release Notes documentation for your cPanel & WHM version.
  • In cPanel & WHM version 58 and higher, we do not use or ship jQuery 1.7 or the jQueryUI and jQuery-UI-Themes libraries.

Warning:

This document only provides information about jQuery in cPanel & WHM version 54 and higher. Many of these restrictions do not apply to cPanel & WHM version 11.52 and earlier.

Notes:

Use jQuery in files that use cPanel's master template, header, or footer

cPanel & WHM interfaces use the RequireJS module loader to load the cPanel-provided jQuery library asynchronously. Files that use the cPanel master template or cPanel's header or footer include files must wrap jQuery code in require() blocks that execute after the RequireJS library loads.

The method to use for jQuery depends on the type of interface file and whether you wish to use jQuery in inline or external JavaScript code.

Inline

 The following inline JavaScript code uses an event listener and chained require() blocks to wrap code that uses jQuery:

<script type="text/javascript">
    // Wait for require.js to load using the new event, then load JQuery
    window.addEventListener("library-loaded", function(e) 
		if (e.detail.library.match(/requirejs/) ) {
    		require(["jquery"], function($) {
				// Use jquery via $, example:
				$(".navbar-header").css('background-color', 'green');
			});
		}
	});
</script>

 The following inline JavaScript code uses an event listener and chained require() blocks to wrap code that uses jQuery:

<script type="text/javascript">
    // Wait for require.js to load
    document.addEventListener("DOMContentLoaded", function() {
        // Load the frameworks bundle, which contains the jQuery library and is used by the rest of cPanel
        require(["frameworksBuild"], function() {
            // Require the jQuery module from the bundle
            require(["jquery"], function($) {
                //--> script content here
                $("#sidebar").css({ background: "red" });
            });
        });
    });
</script>

External

The following external example.min.js file uses an event listener and chained require() blocks to wrap code that uses jQuery:

<script type="text/javascript">
    // Wait for require.js to load using the new event, then load JQuery
    window.addEventListener("library-loaded", function(e) 
		if (e.detail.library.match(/requirejs/) ) {
    		require(["jquery"], function($) {
				// Use jquery via $, example:
				$(".navbar-header").css('background-color', 'green');
			});
		}
	});
</script>

The following external example.min.js file uses an event listener and chained require() blocks to wrap code that uses jQuery:

// Wait for require.js to load
document.addEventListener("DOMContentLoaded", function() {
    // Load the frameworks bundle, which contains the jQuery library and is used by the rest of cPanel
    require(["frameworksBuild"], function() {
        // Require the jQuery module from the bundle
        require(["jquery"], function($) {
            //--> script content here
            $("#content").css({ background: "red" });
        });
    });
});

Notes:

  • When you include jQuery in an external file, you can call it normally via Template Toolkit's page_scripts attribute. For example, the following code calls the example.min.js file:

    page_scripts = [                 # Scripts.
        'custom/example.js',         # The system transforms this file to custom/example.min.js,
                                     # which requires jQuery in a delayed RequireJS block.
    ]

    For more information about how to use the page_scripts attribute, read our Create a New Paper Lantern Interface tutorial.

  • If you use the page_scripts attribute to load exernal files, the external files must use the .min.js file extension. However, the filename that you specify to the page_scripts attribute will only use the .js file extension. cPanel's master template automatically transforms the .js extension in the page_scripts attribute to the .min.js extension.

Use jQuery in custom files

To use jQuery in custom interface files that do not use cPanel's master template, header, or footer, include the following script tag in your markup file:

<script src="3rdparty/jquery/1.11.3/jquery-1.11.3.min.js"></script> 

Note:

Replace 3rdparty/jquery/1.11.3/jquery-1.11.3.min.js with the appropriate jQuery version file for your version of cPanel & WHM. For more information, read the Release Notes documentation for your version of cPanel & WHM.