Home

Awesome

<p align="center"><a href="http://fallback.io/" target="_blank"><img alt="Fallback JS" height="128" src="http://fallback.io/img/logo.png" /></a></p> <h1 align="center">Fallback JS v2.0.0</h1> <h6 align="center">14.98 KB Compressed / 97.82 KB Uncompressed</h6> <p align="center"> <a href="https://raw.githubusercontent.com/dolox/fallback/v2.0.0/dist/fallback.min.js"><img src="https://img.shields.io/badge/production-14.98KB-brightgreen.svg" /></a> <a href="https://raw.githubusercontent.com/dolox/fallback/v2.0.0/dist/fallback.js"><img src="https://img.shields.io/badge/development-97.82KB-brightgreen.svg" /></a> <a href="http://badge.fury.io/gh/dolox%2Ffallback" target="_blank"><img src="https://badge.fury.io/gh/dolox%2Ffallback.svg" /></a> <a href="http://badge.fury.io/bo/fallback" target="_blank"><img src="https://badge.fury.io/bo/fallback.svg" /></a> <a href="https://github.com/dolox/fallback/blob/master/LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-brightgreen.svg" /></a>
<br />

<a href="https://travis-ci.org/dolox/fallback" target="_blank"><img src="https://travis-ci.org/dolox/fallback.svg" /></a>
<a href="https://codeclimate.com/github/dolox/fallback" target="_blank"><img src="https://codeclimate.com/github/dolox/fallback/badges/gpa.svg" /></a>
<a href="https://codeclimate.com/github/dolox/fallback" target="_blank"><img src="https://codeclimate.com/github/dolox/fallback/badges/coverage.svg" /></a>
<a href="https://david-dm.org/dolox/fallback" target="_blank"><img src="https://david-dm.org/dolox/fallback/status.svg" /></a>
<a href="https://david-dm.org/dolox/fallback#info=devDependencies" target="_blank"><img src="https://david-dm.org/dolox/fallback/dev-status.svg" /></a>

<br />
<br />

<a href="https://saucelabs.com/u/fallback" target="_blank"><img src="https://saucelabs.com/browser-matrix/fallback.svg" /></a>

<br />
</p>

THIS BRANCH IS UNSTABLE! USE THE v1 BRANCH!


Getting Started

To let you dive right in, we're going to provide you with the sample of code below. You can view the full API Documentation along with other complex examples listed further down in this document.

index.html

<html>
<head>
	<!-- The `data-main` attribute tells the library to load `main.js` -->
	<script async data-main="main" src="fallback.min.js" type="text/javascript"></script>
</head>

<body class="text-center">
	<h1>Libraries Loaded</h1>
</body>
</html>

main.js

cfg({
	// The list of libraries that we want use for our project.
	"libs": {
		// Include `Twitter Bootstrap`.
		// We explicity prefix `css to the beginning of our key so Fallback JS
		// knows to load this library as a Cascading Stylesheet (CSS).
		"css$bootstrap": {
			// Fallback JS will check to see if this style currently exists on the
			// page. If it does exist, the library will not attempt to load the file
			// as it will assume it's already been loaded on the page.
			"exports": ".col-xs-12",

			// The URLs to load `Twitter Bootstrap`.
			"urls": "//maxcdn.bootstrapcdn.com/bootstrap/3.3.0/css/bootstrap.min"
		},

		// Include `jQuery`.
		"jQuery": {
			// The URLs to load `jQuery`.
			"urls": [
				"//.....some-bad-cdn...../.....FAIL-ON-PURPOSE.....",
				"//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min",
				"//cdnjs.cloudflare.com/ajax/libs/jquery/2.1.1/jquery.min"
			]
		},

		// Include `jQuery UI`.
		"jQueryUI": {
			// The global vaiable that is set by `jQuery UI` when it's loaded on the
			// page. If this variable is defined we won't attempt to load it.
			"exports": "jQuery.ui",

			// Load `jQuery` first before loading `jQuery UI`.
			"deps": "jQuery",

			// The URLs to load `jQuery UI`.
			"urls": [
				"//ajax.googleapis.com/ajax/libs/jqueryui/1.11.2/jquery.min",
				"//cdnjs.cloudflare.com/ajax/libs/jqueryui/1.11.2/jquery-ui.min"
			]
		}
	}
});

// Load jQuery!
req(function(jQuery) {
	jQuery("body").append("<h3 class='alert-success'>Loaded jQuery!</h3>");
});

// Load jQuery UI!
req(function(jQueryUI, jQuery) {
	jQuery("body").append("<h3 class='alert-success'>Loaded jQuery UI!</h3>");
});

// Load Twitter Bootstrap!
req(function(css$bootstrap, jQuery) {
	jQuery("body").append("<h3 class='alert-success'>Loaded Twitter Bootstrap!</h3>");
});

// Load All!
req(function(css$bootstrap, jQueryUI, jQuery) {
	jQuery("body").append("<h3 class='alert-success'>Loaded All!</h3>");
});

Open Source Examples

If you happen to stumble upon any helpful open source examples which aren't listed here, please let us know and we'll add them to the list! Let us know here!


Tools

If you happen to stumble upon any helpful tools which aren't listed here, please let us know and we'll add them to the list! Let us know here!


Special HTML Attributes

The following attributes serve as short-hand which you can add to your HTML <script> elements.

AttributeDescription
baseIf the attribute base exists on a <script> element on the page, then Fallback JS will automatically set this as the base configuraton for the project. This attribute is explicitly configured prior to the main attribute so that the value of main will use this value as it's base path. Alias: data-base
mainIf the attribute main exists on a <script> element on the page, then Fallback JS will automatically require this file. Alias: data-main

Example:

<html>
<head>
	<!-- This will automatically load `/js/main.js` -->
	<script data-base="/js/" data-main="main" src="fallback.min.js"></script>
</head>

<body class="text-center">
	<h1>Libraries Loaded</h1>
</body>
</html>

API Documentation

A technical overview with in depth explanations of the libraries functionality.

Overview

FunctionAliasesDescription
configcfg, conf, config, fallback.cfg, fallback.conf, fallback.config, fbk.cfg, fbk.conf, fbk.configConfigures the libraries you want to load for your project.
definedef, define, fallback.def, fallback.define, fbk.def, fbk.defineDefine your JavaScript files so they can be easily loaded and referenced.
requirefallback.req, fallback.require, fbk.req, fbk.require, req, requireLoads your libraries asynchronously the page.
statsfallback.stats, fbk.statsExports statistics for any libraries that were loaded.
versionfallback.version, fbk.versionGet the current version number of Fallback JS.

===

fallback.config(input)

Aliases: cfg, conf, config, fallback.cfg, fallback.conf, fallback.config, fbk.cfg, fbk.conf, fbk.config

This function allows you to configure the defaults for your project along with the libraries that you want to load with Fallback JS.

===

<h4 align="center">Parameters</h4>
ParameterTypeDefaultRequiredDescription
inputObjectnullYesKey/Value pair Object which contains the configuration for the Fallback JS library.

===

<h4 align="center">fallback.config -> input</h4>
TypeDefaultRequired
ObjectnullYes

The following parameters are allowed for the first level of our input Object. The Object itself has multiple levels which are listed further down in this document.

ParameterTypeDefaultRequiredDescription
amdBooleanfalseNoWhere or not to enforce the use of AMD on the page.
baseObject/StringnullNoSpecific paths that you want to prefix all of your libraries with.
debugBoolean/StringfalseNoToggle debugging mode. Only work in browsers which support console.
delimiterString$NoThe String delimiter to be used when loading non-JavaScript files.
globalsObjecttrueNoWhether or not to leverage the window global when loading libraries.
libsObjectnullNoAn Object containing the configuration for a specific library.

Example:

fallback.config({
	"amd": false,
	"base": "/js/",
	"debug": true,
	"delimiter": "$",
	"globals": true,

	"libs": {
		"angular": "//ajax.googleapis.com/ajax/libs/angularjs/1.3.2/angular.min",
		"css$bootstrap": "//maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min",
		"img$logo": "http://fallback.io/img/logo.png"
	}
});

===

<h4 align="center">fallback.config -> input -> amd</h4>
TypeDefaultRequired
BooleanfalseNo

This configuration parameter allows you to enforce AMD (Asynchronous Module Definitions) for the Fallback JS library.

AMD for the library is enabled, but it's not enforced by default. In other words, if a library that supports AMD attempts loads on the page, it will not be be used as a module, it instead will be retained in the window global on the page, untethered by the Fallback JS library.

By enabling AMD, any JavaScript libraries that support it will no longer be available in the window global on your page. The reasoning behind this is to encapsulate JavaScript libraries so that they're contained and not dirtying up the global scope. This has been proven to be useful when used at an advanced level.

Reality Check: In practice the level of complexitiy and time required to invest just to make this work properly isn't practical for most projects seeking a simplified solution of lazy loading libraries. Therefore this feature is disabled by default. Use this feature at your own discretion.

Example:

// Enable AMD.
fallback.config({
	"amd": true
});

===

<h4 align="center">fallback.config -> input -> base</h4>
TypeDefaultRequired
Object/StringnullNo

If the base value is a String, each of your libraries URLs will be prefixed with this path regardless of their file type. If you specify an Object, you can explicity set different paths for each of your file types. Any URL that starts with /, data:, http:// or https:// will not be prefixed with the base value.

Each URL for a library is prefixed immediately when it's configured. If you were add a library to your configuration and then set the base value afterwards, the URLs for that library wouldn't be prefixed with the newly set base value.

The following table below reflects acceptable parameters when the value of base is an Object.

ParameterTypeDefaultRequiredDescription
cssStringnullNoThe path to prefix all of your CSS files with.
imgStringnullNoThe path to prefix all of your images with.
jsStringnullNoThe path to prefix all of your JS files with.

Example:

// Set base URLs for all of our file types.
fallback.config({
	"base": "/js/"
});
// Set different base URLs for each of our file types.
fallback.config({
	"base": {
		"css": "/css/",
		"img": "/img/",
		"js": "/js/"
	}
});

===

<h4 align="center">fallback.config -> input -> debug</h4>
TypeDefaultRequired
Boolean/StringfalseNo

This configuration parameter allows you toggle debugging for the library. If turned on, this feature will log useful debugging information to the console, if the browser supports window.console.

This feature is only available in the non-minified version of the library. For better compression, all logging messages have been stripped out of the minified version.

The following table below reflects acceptable values for the debug parameter.

ValueDescription
falseDisabled logging.
trueLog everything. This includes errors, warnings and info notices.
errorLog all only error notices.
warnLog all only warning notices.
infoLog all only info notices.

Example:

// Turn debugging on.
fallback.config({
	"debug": true
});

===

<h4 align="center">fallback.config -> input -> delimiter</h4>
TypeDefaultRequired
String$No

Allows you to change the string that's used to specify different file types for the Fallback JS library to load. By default the value is a "$", so if you wanted to load a CSS file you'd need to prefix that library's key with "css$". You need to do this so that Fallback JS knows to load that library as a Cascading Stylesheet (CSS) and not a JavaScript file.

See fallback.config -> input -> libs -> keys for a list of prefixes you can use.

Example:

// This example uses our default.
fallback.config({
	"libs": {
		"css$bootstrap": "//maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min"
	}
});

// Load up our CSS file.
fallback.require(function(css$bootstrap) {
	// Execute my code here...
});
// This example explicity sets the delimiter value.
fallback.config({
	"delimiter": "_",

	"libs": {
		"css_bootstrap": "//maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min"
	}
});

// Load up our CSS file.
fallback.require(function(css_bootstrap) {
	// Execute my code here...
});

===

<h4 align="center">fallback.config -> input -> globals</h4>
TypeDefaultRequired
BooleantrueNo

This parameter directly affects how libraries are loaded and referenced by the Fallback JS library. It specifically tells the library to check the window global to determine if a library has loaded properly and how to reference that library when using the define and require functions.

Any value(s) which are set as exports for a library will directly correlate as references to the window global. For example if you were set the exports to ["jQuery", "$"] for the library jQuery, Fallback JS would check for window.jQuery and window. to determine whether or not the library was loaded. If Fallback JS saw either of those windowvariables asdefined, it would then reference those windowvariables wheneverjQuery` is used with the define and require functions.

Example:

// Configure the Fallback JS library.
fallback.config({
	"urls": {
		"jQuery": {
			// Tell the library to look for these variables in the `window` `global`.
			"exports": ["jQuery", "$"],
			"urls": "//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min"
		}
	}
});

// `jQuery` within this `Function` is simply pointing to `window.jQuery`.
fallback.define("test", function(jQuery) {
	// Execute my code here...
});

// `jQuery` within this `Function` is simply pointing to `window.jQuery`.
fallback.require(function(jQuery) {
	// Execute my code here...
});

Note: If you set the globals parameter to false, you'll be forfeiting the following functionality:

Example:

fallback.config({
	"globals": false
});

===

<h4 align="center">fallback.config -> input -> libs</h4>
TypeDefaultRequired
ObjectnullNo

This parameter allows you to set the libraries that want Fallback JS to load. You don't need to specify AMD, the library will automatically load them by default.

===

<h4 align="center">fallback.config -> input -> libs -> keys</h4>
TypeDefaultRequired
StringnullYes

The keys of this Object are what you'll use to reference the library in question. For example if we added the key test, when we use the require function, we would specify test to load that library even though it may differ from the name of the actual library itself. Another example would be jQuery, but instead we want to use jquery so we don't have to capitalize the Q.

If the exports parameter is not specified for a library, then the key will be treated as it's exports.

Any keys of the libs Object which have any of the following prefixes (listed in the table below) followed by the libraries delimiter will be handled in their own special way.

PrefixDescription
cssAll files listed for the library in question would be loaded as Cascading Style Sheets.
imgAll files listed for the library in question would be loaded as images.
jsAll files listed for the library in question would be loaded as JavaScript files.

Example

// The following example illustrates how we'd load CSS, Image and JavaScript files.
fallback.config({
	"libs": {
		// Load this file as a stylesheet.
		"css$bootstrap": "//maxcdn.bootstrapcdn.com/bootstrap/3.3.0/css/bootstrap.min",

		// This will load our logo image.
		"img$logo": "http://fallback.io/img/logo.png",

		// You don't have to specify `js, it's prefixed by default.
		"js$angular": "//ajax.googleapis.com/ajax/libs/angularjs/1.2.20/angular.min"
	}
});

// Load our stylesheet, image and JavaScript files.
fallback.require(function(css$bootstrap, img$logo, js$angular) {
	// Execute my code here...
});

===

<h4 align="center">fallback.config -> input -> libs -> key -> values</h4>
TypeDefaultRequired
Array/Object/StringnullYes

The values of our keys are acceptable in the following forms:

If the value of our key is an Object, then the following parameters are acceptable:

ParameterTypeDefaultRequiredDescription
aliasArray/StringnullNoAliases to be used to directly reference the library in question.
checkFunctionnullNoA custom Function to check whether or not a library has loaded properly.
depsArray/StringnullNoDependencies that are required to load prior to the library in question loading.
exportsArray/StringkeyNoThe window global variable(s) that reference the library.
initFunctionnullNoA function to invoke immediately after a library has loaded for the first time.
urlsArray/StringnullNoURLs that will load the library.
versionStringnullNoSet the version number of your library.

Examples:

// An example where our libraries value is a `String`.
fallback.config({
	"libs": {
		"jQuery": "//ajax.googleapis.com/ajax/libs/jqueryui/1.11.2/jquery.min"
	}
});

// Load jQuery!
fallback.require(function(jQuery) {
	// Execute my code here...
});
// An example where our libraries value is an `Array`.
fallback.config({
	"libs": {
		"jQuery": [
			"//ajax.googleapis.com/ajax/libs/jqueryui/1.11.2/jquery.min",
			"//cdnjs.cloudflare.com/ajax/libs/jqueryui/1.11.2/jquery-ui.min"
		]
	}
});

// Load jQuery!
fallback.require(function(jQuery) {
	// Execute my code here...
});
// An example where our libraries value is an `Object`.
fallback.config({
	"libs": {
		"jQuery": {
			"urls": [
				"//ajax.googleapis.com/ajax/libs/jqueryui/1.11.2/jquery.min",
				"//cdnjs.cloudflare.com/ajax/libs/jqueryui/1.11.2/jquery-ui.min"
			]
		}
	}
});

// Load `jQuery`
fallback.require(function(jQuery) {
	// Execute my code here...
});

===

<h4 align="center">fallback.config -> input -> libs -> key - > values -> alias</h4>
TypeDefaultRequired
Array/StringnullNo

This parameter allows you setup various aliases for each of your libraries. This is extremely useful when you're frequently referencing a library with a long naming convention that you'd prefer to not have to type.

Example:

// Configure the Fallback JS library.
fallback.config({
	"libs": {
		"jQuery": {
			// All of the following variables will reference `jQuery`.
			"alias": ["$", "jq", "jquery"],

			"urls": [
				"//ajax.googleapis.com/ajax/libs/jqueryui/1.11.2/jquery.min",
				"//cdnjs.cloudflare.com/ajax/libs/jqueryui/1.11.2/jquery-ui.min"
			]
		}
	}
});

// All of the following `fallback.require` references below perform the same action!

// Load `jQuery`
fallback.require(function(jQuery) {
	// Execute my code here...
});

// Load `jQuery`
fallback.require(function($) {
	// Execute my code here...
});

// Load `jQuery`
fallback.require(function(jq) {
	// Execute my code here...
});

// Load `jQuery`
fallback.require(function(jquery) {
	// Execute my code here...
});

===

<h4 align="center">fallback.config -> input -> libs -> key - > values -> check</h4>
TypeDefaultRequired
FunctionnullNo

This parameter allows you to write your own custom checking Function to determine whether or not the library in question has loaded properly on the page. This can be extremely useful when attempting to load browser specific scripts and/or stylesheets.

Return ValueDescription
falseThe library has failed to loaded on the page. Try the next URL in the URLs list.
trueThe library has successfully loaded on the page.

This Function expects a Boolean return value to determine whether or not a library has loaded successfully. The check will run immediately when the library in question is referenced prior to attempting to load any of it's URLs. If the check returns false, Fallback JS will then attempt to load up each of the URLs for library. The check will re-run after attempting to load each URL for the library. Once Fallback JS finds that the check has returned true, it'll stop attempting to load anymore URLs and flag the library as having loaded successfully.

Example:

// Configure the Fallback JS library.
fallback.config({
	"libs": {
		"iePolyfills": {
			"check": function() {
				// `window.document.addEventListener` doesn't exist in legacy IE
				// browsers. The following if statement basically says, if we're
				// in legacy IE and `window.iePolyfills` is `undefined` then attempt
				// to load up this JavaScript file; otherwise don't load it.
				if (!window.document.addEventListener && !window.iePolyfills) {
					return false;
				}

				// Let Fallback JS know that this file has loaded properly.
				return true;
			},

			"urls": "/js/iePolyfills"
		}
	}
});

// Load `iePolyfills`
fallback.require(function(iePolyfills) {
	// Execute my code here...
});

iePolyfills.js

window.iePolyfills = true;

===

<h4 align="center">fallback.config -> input -> libs -> key - > values -> deps</h4>
TypeDefaultRequired
Array/StringnullNo

This parameter allows you to set the dependencies which are required to load prior to the library in question. When attempting to reference a library using the define and require functions, all of the library dependencies will load first if they haven't already been loaded.

The value of this parameter can be either a String or String Series (Array of Strings). The value(s) can correlate to either an alias or key for the library(s) dependency.

A good example is jQuery UI. In order for jQuery UI to load we must first load jQuery, otherwise jQuery UI won't load properly.

Example:

// Configure our Fallback JS library.
fallback.config({
	"libs": {
		"jquery": {
			"alias": "$",
			"exports": "jQuery",
			"urls": "//cdnjs.cloudflare.com/ajax/libs/jquery/2.1.1/jquery.min"
		},

		"jqueryui": {
			// When `jQuery UI` loads it defines `window.jQuery.ui` as it's `global`
			// variable.
			"exports": "jQuery.ui",

			// Load `jQuery` prior to loaded this library. Notice here that we're
			// using the `alias` for the `jQuery` library. We could've used the
			// value `jQuery` as well and it would've had the same effect.
			"deps": "$",

			"urls": "//ajax.googleapis.com/ajax/libs/jqueryui/1.11.2/jquery.min"
		}
	}
});

// Load `jQuery` and `jQuery UI`
fallback.require(function(jqueryui) {
	// Execute my code here...
});

===

<h4 align="center">fallback.config -> input -> libs -> key - > values -> exports</h4>
TypeDefaultRequired
Array/StringnullNo

This parameter allows you to tell the Fallback JS library what window global variable(s) it should expect to be defined when attempting to load a library. For example jQuery UI would have an exports value of jQuery.ui since when jQuery UI is loaded it explicitly defines window.jQuery.ui. We need to specify this in order to detect whether a library has loaded properly (especially in legacy browsers).

If the exports parameter is not specified for a library, then the key will be treated as it's exports.

If the globals parameter is turned off, all exports will be disabled.

Example:

// Configure our Fallback JS library.
fallback.config({
	"libs": {
		"$": {
			// In order for this library to have loaded successfully, `window.jQuery`
			// must exist!
			"exports": "jQuery",
			"urls": "//cdnjs.cloudflare.com/ajax/libs/jquery/2.1.1/jquery.min"
		}
	}
});

// Load `jQuery`
fallback.require(function($) {
	// Execute my code here...
});

===

<h4 align="center">fallback.config -> input -> libs -> key - > values -> init</h4>
TypeDefaultRequired
FunctionnullNo

This parameter allows you to invoke a Function immediately after a library has loaded successfully.

Example:

fallback.config({
	"libs": {
		"jQuery": {
			"init": function() {
				// Execute my code here...
			},

			"urls": "//cdnjs.cloudflare.com/ajax/libs/jquery/2.1.1/jquery.min"
		}
	}
});

===

<h4 align="center">fallback.config -> input -> libs -> key - > values -> urls</h4>
TypeDefaultRequired
Array/StringAMDNo

This parameter allows you to set the URLs that will load the library in question. It expects its value to be either a String or String Series (Array of Strings). When loading a library, the URLs in this list will be loaded from first to last (in the Array) until either one has loaded successfully or all have been exhausted. You can add as many URLs as you want, there's no limit.

Example:

// Configure our Fallback JS library.
fallback.config({
	"base": "/js/",

	"libs": {
		"jQuery": {
			"urls": [
				"//.....some-bad-cdn...../.....FAIL-ON-PURPOSE.....",
				"//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min",
				"//cdnjs.cloudflare.com/ajax/libs/jquery/2.1.1/jquery.min"
			]
		}
	}
});

// Fallback JS will attempt to load all of the URLs for `jQuery`
fallback.require(function(jQuery) {
	// Execute my code here...
});

If you don't specify the urls parameter for a library, then the library will seen as an AMD. If the library is deemed as AMD then it will attempt to load the local file relative to the base path that was set by the config Function.

Example:

// Configure our Fallback JS library.
fallback.config({
	"base": "/js/",

	"libs": {
		"test": {
			"alias": "testMod"
		}
	}
});

// Fallback JS will attempt to load `/js/test.js`.
fallback.require(function(testMod) {
	// Execute my code here...
});

// Notice we didn't add a configuration for `test2`, yet Fallback JS will attempt to
// load `/js/test2.js`.
fallback.require(function(test2) {
	// Execute my code here...
});

===

<h4 align="center">fallback.config -> input -> libs -> key - > values -> version</h4>
TypeDefaultRequired
StringnullNo

This parameter allows you to set the version of the library in question. This is simply used as a logging tool for developers and will show up in the output of the stats Function.

Example:

fallback.config({
	"libs": {
		"jQuery": {
			"urls": "//cdnjs.cloudflare.com/ajax/libs/jquery/2.1.1/jquery.min",
			"version": "2.1.1"
		}
	}
});

===

<h4 align="center">Return Values</h4>
ValueTypeDescription
ObjectObjectIf the configuration was imported properly, an Object with the normalized dataset that was imported will be returned.
falseBooleanThe configuration wasn't imported due to being malformed. Turn debugging on and check console for helper messages.

===

fallback.define(name, dependencies, factory)

Aliases: def, define, fallback.def, fallback.define, fbk.def, fbk.define

This function allows you to create a Asynchronous Module Definition (AMD). This has proven to be beneficial when working on larger projects where you want to compartmentalize sections of a larger project.

===

<h4 align="center">Parameters</h4>
ParameterTypeRequiredDefaultDescription
nameStringNonullIf a name is not set, the URL that was used to load the file will be used as the name.
dependenciesArray/StringNonullDependencies that we expect to be load prior to invoking our factory Function.
factoryN/AYesnullA factory can be anything except undefined. The inoked value of a factory is what will be returned whenever the module is referenced.

The arguments for this Function may be passed in the following variety:

===

<h4 align="center">fallback.define -> name</h4>
TypeDefaultRequired
StringnullNo

The name which will be used to reference the module from a define or require Function.

If you don't specify the name for the definition then it'll be deemed as an anonymous module and use the name of the current file as it's definition name. Note that you cannot have multiple anonymous definitions within the same file as the library has no way of knowing how to differentiate each.

Example:

main.js

fallback.define("testDefine", function() {
	return "test";
});

fallback.require(function(testDefine) {
	// This will log the `String` `test` to the console.
	console.log(testDefine);
});

// Lazy load a module.
fallback.require(function(testAnonymous) {
	// This will log `testAnonymous Module!` to the console.
	console.log(testAnonymous);
});

testAnonymous.js

fallback.define(function() {
	return "testAnonymous Module!";
});

===

<h4 align="center">fallback.define -> dependencies</h4>
TypeDefaultRequired
Array/StringnullNo

This parameter can be an Array or String of dependencies you want to be loaded prior to invoking the factory of your definition.

If no dependencies are set and the factory is a Function, then whatever parameters the factory has will become the dependencies.

Example:

// Specify the dependencies as an `Array`.
fallback.define("test1", ["testDependency"], function(testDependency) {
	console.log("`test1` Loaded!");
});

// Specify the dependencies as a `String`.
fallback.define("test2", "testDependency", function(testDependency) {
	console.log("`test2` Loaded!");
});

// Specify the dependencies solely within the `factory`. This will load
// `testDependency.js` before attempting to invoke the console log message.
fallback.define("test3", function(testDependency) {
	console.log("`test3` Loaded!");
});

===

<h4 align="center">fallback.define -> factory</h4>
TypeDefaultRequired
N/AnullYes

@todo

===

Examples:

// Load jQuery before executing the factory.
fallback.define(function(jquery) {
	// Execute my code here...
});
// Load jQuery before executing the factory.
fallback.define(['jquery'], function(jquery) {
	// Execute my code here...
});
// Load jQuery before executing the factory.
fallback.define('test', function(jquery) {
	// Execute my code here...
});
// Load jQuery before executing the factory.
fallback.define('test', ['jquery'], function(jquery) {
	// Execute my code here...
});

===

===

<h4 align="center">Parameters</h4>
ParameterTypeRequiredDefaultDescription
nameStringNonullIf a name is not passed in, the URL that was used to load the file in question will be used as the name for this definition. Please note that you can't have multiple nameless/anonymous definitions in the same file.
dependenciesArray/StringNonullA string/array of dependencies that we expected to be loaded before executing our function.
factoryFunctionYesnullIf dependencies are specified, then they will be sent to this function as their arguments. However, if you don't specify the dependencies, whatever arguments are within this function will be correlated as the dependencies for this function. See below for further details along with an example.

Example:

Each of following examples below will achieve the same goal. We're simply illustrating how you can use the library, and why you may use one method over another.

config.js

First we need to configure our jQuery library, then load up our definition files.

conf({
	"urls": {
		"jquery": {
			alias: "$",
			files: "//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min"
		}
	}
});

req(function(test, test2, test3) {
	test();
	test2();
	test3();
});

test1.js

Full illustration, passing in all parameters.

Notice that the filename is test1.js yet we've explicity named it test instead. When we goto reference this file, we now must use the name test in order to load it properly. In cases where you want to explicity give a name to your definition which differs from it's default, you would specify the name parameter.

def('test', ['jquery'], function($) {
	return function() {
		$('body').html('jQuery Loaded!');
	};
});

test2.js

If you're using a minifier which doesn't automatically preserve your functions arguments names, you would want to explicity specify your dependencies in an array of strings.

def(['jquery'], function($) {
	return function() {
		$('body').html('jQuery Loaded!');
	};
});

test3.js

Short-hand, less typing, faster coding.

def(function($) {
	return function() {
		$('body').html('jQuery Loaded!');
	};
});

fallback.require(dependencies, factory, error)

Aliases: fallback.req, fallback.require, fbk.req, fbk.require, req, require

The parameters in this function will fallback on one another. So for example, if you only pass in a single parameter, that parameter will be treated as the function.

ParameterTypeRequiredDefaultDescription
dependenciesArray/StringNonullA string/array of dependencies that we expected to be loaded before executing our function.
functionFunctionYesnullIf dependencies are specified, then they will be sent to this function as their arguments. However, if you don't specify the dependencies, whatever arguments are within this function will be correlated as the dependencies for this function. See below for further details along with an example.

The arguments for this Function may be passed in the following variety:

@todo here

===

fallback.stats

===

fallback.version


FAQ

Q: What dependencies does Fallback JS have?

A: None! Fallback JS is a standalone library.

Q: What browser versions are supported?

A: Android 4.0+, Chrome (Latest), FireFox (Latest), IE 6+, iOS 5+, Safari (Latest)

Q: Can I provide multiple fallbacks for any given asset?

A: Yes! You can provide as many as you want, there's no limit.

Q: How should Fallback JS be loaded?

A: Ideally Fallback JS should be loaded from the <head> element of your HTML page with the async attribute set on the <script> element. Ideally you'd want Fallback JS to be your only <script> element on the page, and load any additional CSS/JS libraries via the Fallback JS configuration by taking advantage of the special HTML attributes. Be sure to include type="text/javascript" for legacy browsers. @todo

Example:

<html>
<head>
	<script async src="fallback.min.js" type="text/javascript"></script>
</head>
</html>
Q: Can I load up my CSS and JavaScript files in a single configuration block?

A: Yes, please see the Getting Started example.

Q: Can I run the config Function more than once?

A: Yes. You can call the config Function as many times as you want, but if you call the config Functoin with a library that already exists you'll override it's values. @todo

Q: Why can't I call the define function more than once without a name in the same file?

A: @todo

Q: What happens if I set the base configuration parameter more than once?

A: @todo


About

Contributing

Please read the CONTRIBUTING.md document located in this project to see how you can help contribute. We encourage our users to test and report all/any problems they find with the library.

License

The MIT License (MIT)


Support

Need help? We use GitHub!

Any questions, suggestions or bugs should all be submitted to the issues section of the projects GitHub repository.

Staying Alive

Over the course of this projects life span, we've come to find that 4-5x the star gazers on GitHub reflects the adoption rate of the project. We encourage our users to star the project, so that it can help us see how large the project is growing and how urgent issues become when they arise.

Staying Stable

The project contains over 1000 tests which run on a daily basis for all of the supported browsers. The tests are run on SauceLabs which is triggered by Travis CI and Tron CI. If a new bug were to be introduced for a supported browser which directly affects the library, we would know about it in 24 hours at the latest.