jQuery reqsCheck Plugin
What it does
This lightweight, flexible jQuery plugin simplifies the process of testing whether the end user's browser meets (a subset of) your app's requirements and loading polyfills to provide a little help to browsers that need it. Even if not every requirement has a polyfill, even if you want to test different sets of requirements to enable different parts of your app, even if polyfilling a requirement entails something besides loading a script, this plugin can help you!
Modernizr can test many aspects of browsers' functionality and makes a great companion to this plugin, and its wiki features a guide to polyfills you could load.
Table of contents
API
Parts of the jQuery Namespace
$.reqsCheck() - Parameter: (array) reqs
Each element in reqs is a requirement that must be met either by the browser or an available polyfill. Requirements are represented as either:
- A string, which will be prepended with
"return "and passed tonew Function - A function, optionally with a
toStringmethod returning a property name of$.reqsCheckPolyfills
The requirement is considered to be met by the browser if the resulting function returns a truthy value without throwing an exception.
Returns a results object.
// Basic usage
var results = $.reqsCheck(["Modernizr.flexbox", "Object.assign"]);
// If you have a Content Security Policy that lacks unsafe-eval, you must use functions instead
// Consider a factory like this one to make it easier
function makeModernizrReq(req) {
var test = function() { return Modernizr[req]; };
test.toString = function() { return "Modernizr." + req; };
return test;
}
// You could then use your factory with reqsCheck like so
var results = $.reqsCheck([ makeModernizrReq("flexbox"), makeModernizrReq("promises") ])
$.reqsCheckPolyfills - Object
The name of each property is the string representation of a requirement passed to $.reqsCheck(). The value is either the URL of a polyfill script that can meet that requirement, or the name of an appropriate property of $.reqsCheckPolyfillPromises. A value may be used as many times as necessary. Note that this object has no properties by default, leaving the decision of which polyfills are suitable to you.
$.reqsCheckPolyfills = {
"Element.prototype.prepend": "/polyfills/dom4.js",
"Object.assign": "/polyfills/ecmascript6.js",
"Map": "/polyfills/ecmascript6.js" // used twice but will only be loaded once
};
$.reqsCheckPolyfillPromises - Object
The name of each property is one of the polyfills specified in $.reqsCheckPolyfills. Each value is a Deferred (or any Promise/thenable, for jQuery 3+) that must be resolved when the polyfill is ready to use, or rejected if attempting to prepare the polyfill failed.
The .getPolyfills method of results objects assumes that any polyfill with no property here is a script, and will automatically create a property with the value returned by $.ajax(polyfill, $.reqsCheckAjaxOptions). Such auto-created properties are also auto-deleted if loading the script fails, allowing another .getPolyfills call to try $.ajax again.
$.reqsCheckAjaxOptions - Object
These options are passed to $.ajax whenever reqsCheck attempts to load a polyfill. It defaults to {dataType: "script", cache: true}.
Properties of the Results Object
.canMeetReqs - Boolean
If true, indicates that the browser can theoretically meet the specified requirements, assuming any needed polyfills load.
.polyfillsNeeded - Object
The name of each property is a polyfill that must be loaded for the requirements to be met, as specified in the values of $.reqsCheckPolyfills. All values are true. If .canMeetReqs is false, not every helpful polyfill may be included.
You may add/remove properties from this object before calling .getPolyfills() to alter its behavior.
// Sometimes a polyfill's API isn't quite the same as the standard it enables support for.
// After .getPolyfills() does its thing, you can work around that like so.
if (results.polyfillsNeeded[urlOfPolyfill]) {
// Use the polyfill's API
} else {
// Use the standard API
}
.getPolyfills() - No parameters
Begins loading any needed polyfills, and returns a jQuery Promise that is resolved when the requirements are satisfied with any needed polyfills loaded successfully. The Promise is rejected if any polyfills fail to load, or if .canMeetReqs is false (no polyfills are loaded in the latter case).
results.getPolyfills().then( function done() {
// Use required features as you please!
}, function fail() {
if (results.canMeetReqs) {
// Polyfills failed to load.
} else {
// The browser is unable to meet the requirements.
}
} );
.promise() - No parameters
An alias for .getPolyfills. This lets you use undocumented behavior of $.when to treat the results object as if it were a Deferred.
// Proceed when the document is loaded and requirements are met
// For more info about $.ready:
// https://jquery.com/upgrade-guide/3.0/#feature-jquery-ready-promise-is-formally-supported
$.when($.ready, results).then(myFunc);License (MIT)
This plugin is made available for use under the MIT License, the text of which is below. To summarize, the answer to "Can I do x?" is "yes", unless x is "remove the opening comment" or "sue the author".
Copyright (c) 2016, Pikadude No. 1
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.