jQuery Core & Internals JQ Home << JQ Basics << jQuery Core & Internals

In this lesson we look at the methods and properties that make up the jQuery Core and Internals.

Core Methods	Internal Methods and Properties
`jQuery()`	`.context DEPRECATED`
`jQuery.holdReady() DEPRECATED`	`.jquery`
`jQuery.noConflict()`	`jQuery.error`
`jQuery.readyException()`	`.length`
`jQuery.sub() REMOVED`	`.pushStack()`
`jQuery.when()`

jQuery Core Methods

In this section we look at the methods that make up the jQuery core. The basic premise of jQuery is to retrieve elements from our HTML and perform some sort of action upon those elements. The matched set of elements retrieved are returned, as a special type of array-like Javascript Object, which contains the selected DOM nodes stored within an array. The returned object contains numerous methods we can use on our matched set, these methods are in essence what makes up the jQuery library. So our returned object acts as a wrapper (a collection of elements that have extended functionality) for our matched (wrapped) set of elements.

The `jQuery()` Method Top

The jQuery() method selects an entity to wrap and has nine signatures.

So how do we select a group of elements to wrap? Well we use the jQuery() function for this purpose. The primary formulation of this function matches a set of elements via a string containing a CSS or custom jQuery selector. As mentioned in the last lesson we can use the &() alias for jQuery:


// Formal syntax
jQuery(ourSelector)

// Shorthand version (we will use this from now on)
$(ourSelector)

Ok, lets see this in practice by showing an example that turns all paragraph text to indigo on a button press:



$(function(){                      // jQuery(document).ready(function(){
  $("#btn1").on('click', function(){     // Here we select relevant click event
    alert("To indigo");
    $("p").css('color', 'indigo'); // Here we select paragraphs
  });
});

As you can see when you press the button all paragraph text is changed to the colour indigo. We are returning all 'p' nodes from the DOM as our wrapped set and then chaining the .css() function to our wrapped set to change the styling. The .css() function is covered in detail in: jQuery Basics - Lesson 10: Working With General CSS Properties so don't worry about it for now.

There are other formulations available for the jQuery() / &() method which are all covered in the reference section.

The `jQuery.holdReady()` Method Top

The jQuery.holdReady() method holds or releases the execution of the jQuery ready event.

As mentioned in the last lesson jQuery allows us to fire off events as soon as the DOM is ready by using the ready() method. There are also situations where we may want to delay execution of the jQuery ready event, for example to load plugins. We can then release the jQuery ready event after our conditions are met giving us complete control. We use the jQuery.holdReady() method to achieve this. When using this method it's best to ensure it's called early within the HTML document and before the ready event has already fired.

A good place to put this method is in the <head></head> HTML element after the import of the jQuery library and before any other JavaScript and jQuery that is to be executed. Calling this method after the ready event has already fired will have no effect.

When you entered this page an alert box was shown informing you that the jQuery ready event is about to fire. When you closed the alert box we released the jQuery ready event. Simplified HTML code is shown below so you can see its placement:


<!DOCTYPE html 
<html lang="en">
<head>
  <title>jQuery Core & Internals</title>
	
  <!-- This is where we import the minified jQuery library -->
  <script type="text/javascript" src="jquery-3.5.1.min.js"></script>

  <!-- Our jQuery to hold and release ready event-->
  <script type="text/javascript">
    $.holdReady(true);
    alert('jQuery ready event being released);
    $.holdReady(false);
    $(function(){ // jQuery(document).ready(function(){
      // Other jQuery stuff for after ready()
    });
  </script>
</head>
<body>
</body>
</html>

All we see on page entry is the alert box as we haven't released the ready event which is the first code in the <head> </head> HTML element after all the imports. Therefore at this point no <body> </body>HTML elements have been rendered to the page.

The `jQuery.noConflict()` Method Top

The jQuery.noConflict() method allows us to free up the jQuery library control of the $ variable and optionally the jQuery namespace as well.

There are other JavaScript libraries such as Prototype that also use the $ symbol as a global identifier. To address this conflict and optionally remove the jQuery namespace as well we can use the jQuery.noConflict() Method.

The following code just highlights how to use the jQuery.noConflict() method. We don't want to deactivate the $ symbol or remove the jQuery namespace on this page as we are using them to highlight usage of other methods. For working examples look at the jQuery.noConflict() method usage in the reference section.


// EXAMPLE 1: Relinquish jQuery control of the $ alias
$.noConflict()
// The $ alias can now be used for other libraries
  ...   
	
// EXAMPLE 2: Relinquish jQuery control of the $ alias
jQuery.noConflict()
// The $ alias can now be used for other libraries
  ...
	   
// EXAMPLE 3: Relinquish jQuery control of the $ alias and 
// move the jQuery namespace to a new object
var newNamespace = {};
newNamespace.query = jQuery.noConflict(true)
// The $ alias can now be used for other libraries
  ...   
// Use the new jQuery namespace
newNamespace.query('p').css('color', 'indigo'); 
  ...

The `jQuery.readyException()` MethodTop

The jQuery.readyException() method fires when an Error JavaScript object is thrown synchronously from a jQuery() or jQuery( document ).ready() function or equivalent.

In the following example when we press the button the first time the jQuery.readyException() method gets fired.


$(function(){
  $('#btn18').one('click', function() { 
    var context = $('*').context; 
    jQuery.readyException = function( error ) {
      window.setTimeout( function() {
        throw error; 
      });
    };
  });
});

The `jQuery.sub()` Method REMOVEDTop

Create a new copy of jQuery whose values can be altered without affecting the original jQuery object.

This method was deprecated in jQuery 1.7 and removed in 1.9 and so we are just showing it for completeness. As the major use for this method is for plugins to work on a copy of jQuery, without modifying the original jQuery object, this method was moved to a plugin in jQuery 1.8 for this purpose.

The `jQuery.when()` Method Top

The jQuery.when() method allows provision to execute callback functions, on Deferred or plain JavaScript objects, based on one or more objects representing asynchronous events.


$(function(){
  $('#btn12').on('click', function(){
    $.when({ 
      propA: 'Hello World' 
    })
    .done(function(x){
      alert(x.propA); 
    });
  });
});

jQuery Internals Methods

In this section we look at the methods and properties that make up the jQuery internals.

The `.context` Property DEPRECATEDTop

The .context property holds the original context passed to jQuery() which could be a DOM node context, or generally the document context, if no node was passed.


$(function(){
  $('#btn13').on('click', function(){
    alert($('*').context); 
  });
});

The `.jquery` Property Top

The .jquery property holds the jQuery version number in string format.


$(function(){
  $('#btn14').on('click', function(){
    alert('Running version ' + $().jquery + ' of jQuery'); 
  });
});

The `jQuery.error` Method Top

The jQuery.error method enables us to throw an exception from a passed string.

This method isn't much use outside of plugins as we can use the try....catch....finally construct for much better error handling. It does however give plugin developers the opportunity to override it with more meaningful error messages.


$(function(){
  $('#btn15').on('click', function(){
    try {
      var anError = 3;
      if (anError < 5) {
        jQuery.error('ERROR: Value less then 5');
      } 
    } catch(e) {
      alert(' Our Message: ' + e.message);
    }
  });
});

The `.length` Property Top

The .length property holds the number of elements in the jQuery object.


$(function(){
  $('#btn16').on('click', function(){
    alert('There are ' + $('p').length + ' p nodes in the DOM'); 
  });
});

The `.pushStack()` Method Top

Put a collection of DOM elements onto the jQuery stack.

In the following example we just create a new jQuery object by pushing all 'p' nodes from this page onto the stack. We then display our object on the Firefox firebug console for checking and alert it.


$(function(){
  $('#btn17').on('click', function(){
    var $hold = $().pushStack( document.getElementsByTagName('p') );
    alert('Our object: ' + JSON.stringify($hold));
  });
});

Lesson 2 Complete

In this lesson we looked at the methods and properties that make up the jQuery Core and Internals.

Reference

Methods

Properties

jQuery Reference - Internals - .context property
jQuery Reference - Internals - .jquery property
jQuery Reference - Internals - .length property