Development Guides Home >> Guide to cPanel Interface Customization and Branding

Guide to cPanel Interface Customization - jQuery

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.
• cPanel & WHM only uses one cPanel-provided version of jQuery. For more information, read our Release Notes for your cPanel & WHM version.
• We do not use or ship jQuery or the jQueryUI and jQuery-UI-Themes libraries.

Create a new cPanel Interface

• To create a new cPanel interface in Template Toolkit, read our Create a New cPanel Interface tutorial.
• To create a new cPanel interface in PHP, read our Create a New cPanel Interface in PHP tutorial.

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:
                console.log("reached jquery code");
                $("#pageHeading").css('color', 'green');
            });
        }
    });
</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:
                    console.log("reached jquery code");
                    $("#pageHeading").css('color', 'green');
                });
            }
        });
</script>

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 cPanel Interface tutorial.

If you use the page_scripts attribute to load external 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="/unprotected/libraries/jquery/current/jquery.min.js"></script>

For more information, read the Release Notes documentation for your version of cPanel & WHM.