jQuery.sub() | jQuery API Documentation

jQuery.sub()

Categories: Core | Deprecated > Deprecated 1.7 | Removed

jQuery.sub()Returns: jQueryversion deprecated: 1.7, removed: 1.9

Description: Creates a new copy of jQuery whose properties and methods can be modified without affecting the original jQuery object.

  • version added: 1.5jQuery.sub()

    • This method does not accept any arguments.

Note: This API has been removed in jQuery 1.9.

There are two specific use cases for which jQuery.sub() was created. The first was for providing a painless way of overriding jQuery methods without completely destroying the original methods and another was for helping to do encapsulation and basic namespacing for jQuery plugins.

Note that jQuery.sub() doesn't attempt to do any sort of isolation - that's not its intention. All the methods on the sub'd version of jQuery will still point to the original jQuery (events bound and triggered will still be through the main jQuery, data will be bound to elements through the main jQuery, Ajax queries and events will run through the main jQuery, etc.).

Note that if you're looking to use this for plugin development you should first strongly consider using something like the jQuery UI widget factory which manages both state and plugin sub-methods. Some examples of using the jQuery UI widget factory< to build a plugin.

The particular use cases of this method can be best described through some examples.

Examples:

Example 1



Adding a method to a jQuery sub so that it isn't exposed externally:

1
2
3
4
5
6
7
8
9
10
11
12
 
(function(){
  var sub$ = jQuery.sub();
  sub$.fn.myCustomMethod = function() {
    return "just for me";
  };
 
  sub$( document ).ready(function() {
    sub$( "body" ).myCustomMethod() // "just for me"
  });
})();
 
typeof jQuery( "body" ).myCustomMethod // undefined

Example 2

Override some jQuery methods to provide new functionality.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
 
(function() {
  var myjQuery = jQuery.sub();
 
  myjQuery.fn.remove = function() {
 
    // New functionality: Trigger a remove event
    this.trigger( "remove" );
 
    // Be sure to call the original jQuery remove method
    return jQuery.fn.remove.apply( this, arguments );
  };
 
  myjQuery(function( $ ) {
    $( ".menu" ).on( "click", function() {
      $( this ).find( ".submenu" ).remove();
    });
 
    // A new remove event is now triggered from this copy of jQuery
    $( document ).on( "remove", function( event ) {
      $( event.target ).parent().hide();
    });
  });
})();
 
// Regular jQuery doesn't trigger a remove event when removing an element
// This functionality is only contained within the modified 'myjQuery'.

Example 3

Create a plugin that returns plugin-specific methods.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
 
(function() {
 
  // Create a new copy of jQuery using sub()
  var plugin = jQuery.sub();
 
  // Extend that copy with the new plugin methods
  plugin.fn.extend({
    open: function() {
      return this.show();
    },
    close: function() {
      return this.hide();
    }
  });
 
  // Add our plugin to the original jQuery
  jQuery.fn.myplugin = function() {
    this.addClass( "plugin" );
 
    // Make sure our plugin returns our special plugin version of jQuery
    return plugin( this );
  };
})();
 
$( document ).ready(function() {
 
  // Call the plugin, open method now exists
  $( "#main" ).myplugin().open();
 
  // Note: Calling just $( "#main" ).open() won't work as open doesn't exist!
});