https://github.com/brantburnett/jquery.themescript
Document theming helper plugin
https://github.com/brantburnett/jquery.themescript
Last synced: 3 months ago
JSON representation
Document theming helper plugin
- Host: GitHub
- URL: https://github.com/brantburnett/jquery.themescript
- Owner: brantburnett
- Created: 2009-02-27T20:05:47.000Z (over 16 years ago)
- Default Branch: master
- Last Pushed: 2010-02-20T14:36:47.000Z (over 15 years ago)
- Last Synced: 2025-01-14T10:17:57.569Z (5 months ago)
- Language: JavaScript
- Homepage: http://btburnett3.github.com/jquery.themescript
- Size: 89.8 KB
- Stars: 2
- Watchers: 4
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README
Awesome Lists containing this project
README
/**
* jQuery.themescript - document theming helper plugin
* Written by Brant Burnett (http://www.btburnett.com/).
* Licensed under the GPL (http://www.gnu.org/licenses/gpl.html).
* Date: 2010/02/09
*
* @author Brant Burnett
* @version 1.1.0
*
**/
For better or for worse, a significant amount of the look and feel of our web sites
is now being controlled through Javascript. There's simply so much we can do with
Javascript, especially jQuery and it's plugins, that can't be done with CSS. This
presents two complications. First, you need to apply your theming to any HTML loaded
via AJAX. Secondly, we sometimes want to create a common theme, but then allow
subthemes to override certain functionality. With CSS this is easy, but with Javascript
it's more difficult. That's where jQuery.themescript comes in.
jQuery.themeScript allows you to register collections of functions against specific
CSS selectors or specific names. A subtheme can then add to or replace these functions
via their CSS selector or name. You can then execute all of these functions against
the entire document during $(document).ready, or against a subset of elements using
$(selector).themescript(). Finally, $(selector).themescript(url, [data], [callback])
works like the jQuery load function, loading the result of an AJAX request into the
inner HTML of the element, but additionally executes the themescripts against the
result once it's complete.
Function Collections
---------------------
You access a function collection by calling $.themeScript(sel) (or jQuery.themeScript(sel)).
sel can be either a standard jQuery CSS selector, or can be a custom string beginning with
a dash (-). Depending on which type of string it is, it will be handled differently when the
functions in the collection are called.
The object that is returned works much like a jQuery object, allowing you to make modifications
and chain calls together. Here are the functions supplied:
size() - returns the number of functions in the collection
get( [index] ) - With no parameters returns an array made from the collection. With parameters
returns the item that index. i.e. get(0) returns the first item.
each( callback, [args] ) - iterates through the collection like jQuery.each
exec( [context] ) - executes the functions in the collection in order. Context optionally
supplies a context to jQuery during selectin of the elements, and is also passed to
the called functions as the third parameter. Context can be a DOM element, document,
or a jQuery object.
add( callback, [index] ) - adds a function to the collection. index is the zero-based index to
insert the function before. index can also be the name of the function to insert the callback
before. By default it will add the function to the end of the array. callback can also be
an array of functions to insert.
clear() - removes all functions from the collection
remove( index, [count] ) - removes a function from the collection. index can be either the string
name of the function to remove, or the zero-based index of the function to remove. If using
an index then you can also specify the number of items to remove using count.
index( funcName ) - returns the zero-based index of a function in the collection based upon
it's name. Returns -1 if the function is not found.
Global Functions
-----------------
$.themescript( sel ) - Retrieves a function collection based upon a selector
$.themescript.clear() - removes all theming collections
$.themescript.exec( [context] ) - executes all theme registered themescript collections,
with the supplied optional context. Context can be a DOM element, document, or
jQuery object.
$.themescript.extend - extend the themescript library, like $.extend
$.themescript.fn.extend - extend the themescript collection functions, like $.fn.extend
$.themescript.bind() - binds $.themescript.exec to $(document).ready.
$.themescript.unbind() - unbinds $.themescript.exec from $(document).ready
$.fn Functions
---------------
$.fn.themescript([url], [data], [callback])
If called with no parameters, executes all theme functions against all of the elements in
the jQuery object. A common usage would be to call this during an AJAX success callback
on all items inserted into the DOM.
Usage:
$('#selector').themescript();
Equivalent To:
$.themescript.exec( $('#selector') );
If called with parameters, performs a jQuery AJAX load(), and then executes all theme functions
against all of the elements in the jQuery object on success only.
Usage:
$('#selector').themescript( 'test.php', { 'choices[]': ['Jon', 'Susan'] } );
Equivalent To:
$('#selector').load( 'test.php', { 'choices[]': ['Jon', 'Susan'] }, function(responseText, res, status) {
if (status === "success" || status === "notmodified")
$.themescript.exec( this );
});
Function Parameters
--------------------
The callback functions you add to a themeScript collection have two possible formats, depending
on what type of selector was used to create the collection. The second parameter is always
the jQuery object, in case you need it to avoid namespace conflicts. The third parameter is
always the context supplied to exec(), if any.
If the selector was a jQuery CSS selector, then the first parameter is a jQuery object made
by using that selector. Therefore, if you use:
$.themescript(".my-class").add( function( selector, $, context ) {...} );
selector will be the result of $(".my-class", context). Note that if the jQuery selector returns
an empty jQuery object (there are no results), the callback functions are never called. This is
to help improve performance.
If the selector was a custom string beginning with a dash (-) character, then the first parameter
is instead the selector string itself. Therefore if you use:
$.themescript("-my-theme").add( function( str, $, context ) {...} );
str will be "-my-theme". These functions will always be called during exec, and never skipped.
Example Usage
--------------
In main theme, hide all DIVs with the my-class class name.
$.themescript("div.my-class").add( function( selector ) { selector.hide(); } );
Override in sub theme, instead setting the background color to white:
$.themescript("div.my-class").clear().add( function ( selector ) { selector.css("background-color", "#fff"); } );
Or insert something else before it:
$.themescript("div.my-class").add( function(selectors ) { selector.parent().appendTo("body"); }, 0);
Function Naming
----------------
You have the ability to access a function in themescript collection by using the function's name.
While function names are not required, you can provide them as follows:
$.themescript(".my-class").add( [ function doSomething( $s, $ ) {...}, function doSomethingElse ( $s, $ ) {...} ] );
And then replace it later in a subtheme by adding before it and then removing it:
$.themescript(".my-class").add( function doSomethingHere( $s, $ ) {...}, "doSomething" ).remove("doSomething");
Using With ASP.Net AJAX Update Panels
--------------------------------------
jQuery.themescript can be used with ASP.Net AJAX update panels very easily. Just add the following script code, and
any updated panels will automatically have the defined scripts executed against them, restricted to their context.
var prm = Sys.WebForms.PageRequestManager.getInstance();
prm.add_pageLoaded(function(sender, args) {
var updated = args.get_panelsUpdated();
if (updated && updated.length) {
$.themescript.exec($(updated));
}
});
Changelog
----------
1.1.0 - 2010/02/08
Added $.fn.themescript
$.exec and $.fn.exec now accept a context
Added $.themescript to eventually replace the harder to type $.themeScript. Both are currently supported. though
$.themeScript should be considered deprecated.
1.0.1 - 2010/01/28
No longer automatically executes $.themeScript.bind() when the script is loaded. This was causeing problems if
loading asynchronously using a loader like LABjs
Switched to using Google Closure for minification
1.0.0 - 2009/02/02
Initial release