jMod
Click Here For Full Documentation
Settings Demo
jMod is a library of useful tools for userscript authors with features ranging from popup notifications, to a full settings dialog generator.
Overview
Lightweight and versatile, jMod can be loaded anywhere without having to worry about the native CSS affecting the UI. jMod loads a FULLY namespaced bootstrap stylesheet that has been trimmed down to its bare essentials. Thats it! jMod does not depend on jQuery. However, loading a copy of jQuery can enhance several of its features.
jMod can be loaded as a required script in your meta block, or as a script element.
Events
One of jMod's most useful features is handling loading events for you. When run at "document-start", scripts actually execute before the DOM exists. This prevents you from interacting with the document until it is created. jMod takes care of this for you.
jMod.CSS = 'custom css'; // Added to CSS stack until DOM exists
// Start DOM interactions
function onDOMReadyCB(){
console.log('onDOMReadyCB');
}
jMod.onDOMReady = onDOMReadyCB;
// jMod fully initialized
function onReadyCB(){
console.log('onReadyCB');
}
jMod.onReady = onReadyCB;
// Page is ready
function onPageReadyCB(){
console.log('onPageReadyCB');
}
jMod.onPageReady = onPageReadyCB;
// Page is loaded
function loadCB(){
console.log('loadCB');
}
jMod.load = loadCB;
The following four methods are all functionally equivalent:
// Execute function when jMod is fully loaded and CSS is added
jMod.onReady = function(){
console.log('onReady');
}
jMod(function(){
console.log('onReady');
});
jMod('onReady', function(){
console.log('onReady');
});
jMod.Events.addListener('onReady', function(){
console.log('onReady');
}, true);
Settings
Notifications
jQuery
Although jMod is designed to run without using jQuery, there are a few jQuery specific enhancements built in.
GM_xmlhttpRequest in jQuery Ajax Requests
jMod can extend any instance of jQuery to use GM_xmlhttpRequest as its default data transmission method. This allows you to reliably make cross-origin requests without any additionally flags. Doing this affects every ajax request made by jQuery.
if($){
$(document).ready(function() {
function test_jQueryFunctions(){
jMod.jQueryExtensions.addCrossOriginSupport($);
// Test $.ajax()
console.log('Test $.ajax("http://google.com")');
$.ajax({
url: 'http://google.com',
contentType: 'text/html',
type: 'GET',
dataType: 'html',
onprogress: function(response){
console.log('onprogress response', response);
},
onreadystatechange: function(response){
console.log('onreadystatechange response', response);
}
})
.done(function(data, textStatus, jqXHR) {
console.log("$.ajax() success: ", jqXHR);
})
.fail(function() {
console.log("$.ajax() error");
});
// Test $(element).load()
console.log('Test $(element).load("http://google.com #hplogo")');
var tmpDiv = document.createElement('div');
tmpDiv.id = 'tmpDiv';
document.body.appendChild(tmpDiv);
$('#tmpDiv').load('http://google.com #hplogo', function(responseText, textStatus, jqXHR){
console.log('$(element).load() ' + textStatus, jqXHR);
});
}
test_jQueryFunctions();
});
} else {
console.log('Test Failed! No jQuery');
}
Resources
A list of any/all resources used by jMod that I did not personally write.
Javascript
jQuery
jMod.extend():
jMod uses a modified version of jQuery's extend function for copying/cloning an object onto another. However, jMod's version takes scope and permissions into account and ensures no errors occur.
UAParser
jMod uses UAParser to identify the user's browser type/version.
CSS
jMod loads in fully namespaced versions of several popular CSS libraries. They will not interact or change the web page in any way until the namespace is added to an element.
Bootstrap 3.3.2
The bootstrap stylesheet is namespaced with the class ".jmod-na". Many of its standard components have been removed, while others have been heavily modified. For example, tooltip classes have been renamed to avoid having the content page's Bootstrap instance try and interact with it.
Font Awesome 4.3.0
The bootstrap stylesheet is namespaced with the class ".jmod-fa", and defines the font-face as "jModFontAwesome". It doesn't use the same namespace as the other libraries to avoid overriding a page's font awesome instance when doing so is undesirable.
Other
ToDo / Goals
- jMod.jQueryExtensions.addCrossOriginSupport
I need to add a version called jMod.jQueryExtensions.exportCrossOriginSupport. This would an exported function instead of adding the functions directly. This is for users that want to add cross origin support to a jQuery instance in the public scope from a privileged script. This will prevent any errors caused by an unsafe function trying to indirectly call GM_xmlhttpRequest.
This would, from the script author's perspective, work exactly the same as addCrossOriginSupport. However, a function has to be exported (via ExportFunction) to the public scope. This function is what jQuery will actually call, which itself calls the real function available inside jMod. - mCloneInto
This jMod cloning function needs a better method for cloning objects when cloneInto is unavailable / not working. I have already created a function called jMod.CloneProperties that can clone an object in a manor similar to jQuery's extend method. However, CloneProperties copies non-enumerable properties and reconstructs their property constructors manually. This is a start, but it still needs a lot of work before it can be put into production. - CSS
Trim down and clean up CSS.
License
jMod is licensed under the GNU General Public License v3. See the file /COPYING for the complete terms of this license.
Third parties are welcome to modify and redistribute jMod in entirety or parts according to the terms of this license, and welcomes patches for improvements or bug fixes.