Better documentation, more comments.

hansl · hansl · commit 8b8ef6a794ce · 2014-04-16T10:40:50.000-07:00
diff --git a/README.md b/README.md
@@ -4,12 +4,22 @@
 
 A script loader for AngularJS that perform AMD-like script injection without the need for special syntax.
 
+
+
+
+
+
 # Rationale
 
 Say you are like me and love having a Javascript file for every module. And you have a lot of scripts with specific tasks; directives, factories, utility functions. You name it.
 
 One solution that we used here at Coders at Work was RequireJS, but I grew tired of it; it is becoming too heavy and doesn't integrate that well with AngularJS.
 
+
+
+
+
+
 # Example
 
 So I decided to go ahead and build this little script. Here's how it works:
@@ -25,7 +35,7 @@ So I decided to go ahead and build this little script. Here's how it works:
 >         
 >         <body>
 >             <div ng-controller="TestCtrl as test">
->                 {{test.value}}<br/>
+>                 {{test.value}}
 >             </div>
 >         </body>
 >     </html>
@@ -47,9 +57,14 @@ So I decided to go ahead and build this little script. Here's how it works:
 >     });
 > ```
 
-Angularjs-loader automatically sees that angular.module() has a dependency to 'test_ctrl', and as such loads the script automatically when it's ready. When all `angular.module()` calls are done, it automatically bootstrap angular.
+Angularjs-loader automatically sees that angular.module() has a dependency to 'test_ctrl', and loads the script automatically when it's ready. When all `angular.module()` calls are done, it automatically bootstrap angular.
+
+As long as you stick to AngularJS, there's no need for shims, paths or configurations. A blocking module makes it simple to include other libraries as well.
+
+
+
+
 
-As long as you stick to AngularJS, there's no need for shims, paths or configurations.
 
 # API
 
@@ -65,6 +80,8 @@ It takes 3 arguments:
 * `onbootstrap`. Code to evaluate when the Angular is finished loading.
 * `noinit`. Any non-empty string to prevent the AngularJS-Loader from automatically starting the initialization process. See [Tests](#Tests).
 
+
+
 ## Angular Modules
 
 The loader overrides `angular.module()` and does two things:
@@ -75,11 +92,13 @@ The loader overrides `angular.module()` and does two things:
 
 As you use `angular.module()` to create a module, it will load its dependencies recursively. Using `angular.module()` to only access the module itself is okay and has no side effect.
 
+
+
 ## Custom Scripts
 
 When you need to load custom scripts you should use the new function `angular.loader()`. It takes 2 arguments and returns a simplified promise object.
 
-The first argument is either a filename or an array of filename to load. Remember that these will be transformed using [path transform](#Configuration).
+The first argument is either a filename or an array of filename to load. Remember that these will be transformed using the [path transform](#Configuration).
 
 The second argument is an object of named options:
 
@@ -93,12 +112,16 @@ Omitting this option performs no checks at all and unlock the bootstrap when the
 
 The object returned can be used as a simpler Angular deferred promise object, but there's no `finally` method on it, only `catch` and `then`. The promise will be fulfilled after the checker has returned `true` for all the scripts.
 
+
+
 ## Locking the Bootstrap
 
 You can lock bootstrapping of AngularJS with `angular.loader.lock()` (and unlock it with `angular.loader.unlock()`). The functions take a name as parameter. Locking the same name twice, unlocking an unlocked or unknown name are all errors. The only limit on locks are that you cannot lock/unlock once the bootstrap happened. Anything after bootstrapping angular is considered an error.
 
 Locking and unlocking before the end of loading all the modules and their dependencies will simply result in waiting for the dependencies to finish loading.
 
+
+
 ## <a name="Configuration"></a> Configuration
 
 Configuration is set by calling `angular.loader.config()`. The function takes an object as argument and update the internal configuration.
@@ -108,48 +131,83 @@ The list of configuration options is as follow:
 * `path`. A map of name to full path (or `null`). If a module name is present in this map, the loader will use this path instead of the name to load. If the full path in the map is `null`, the script will return 
 * `pathTransform`. A list of functions that take a path and return a path or `null`. This is to allow transforming a module or script name to its file path. The transform chain will not be executed if the path is part of the `path` option above or is a full URI.
 * `checker`. A checker map for modules. See loading custom scripts above. This is to simplify the calls to `angular.loader()`.
+* `error`. An error handler. If specified, NO error will be thrown or outputted, they will all be passed to the handler.
 
 The process of getting a script path from a module name is as follow:
 
 ```javascript
-var name;  // Original name for the module.
-var path = name in config.path ? config.path[name] : name;  // Path to load.
-if (path === null) return;
-if (isUri(path)) return path;
-
-for (var i = 0; i < config.transformPath.length; i++) {
-	old_path = path;
-	path = config.transformPath[i](path, name);
-	if (path === null) {
-	    path = old_path;
-	    break;
-	}
-}
-
-if (isUri(path)) return path;
-if (path[0] != '/') path = '/' + path;
-if (!/\.js$/.test(path)) path += '.js';
-return path;
+    var name;  // Original name for the module.
+    var path = name in config.path ? config.path[name] : name;  // Path to load.
+    if (path === null) return;
+    if (isUri(path)) return path;
+
+    for (var i = 0; i < config.transformPath.length; i++) {
+    	old_path = path;
+	    path = config.transformPath[i](path, name);
+    	if (path === null) {
+	        path = old_path;
+	        break;
+    	}
+    }
+
+    if (isUri(path)) return path;
+    if (path[0] != '/') path = '/' + path;
+    if (!/\.js$/.test(path)) path += '.js';
+    return path;
 ```
 
+
+
 ## <a name="Tests"></a> Tests (Karma and Jasmine)
 
-*__To Be Done!__*
+Some Karma tests are included to cover the most basis cases. Tests are added regularly for better coverage.
+
+To run the tests, simply run `karma run` in the angularjs-loader folder.
+
 
------
 
 # ToDo
 
+For version 1.0:
+
 1. Minification pre-step. Having a script that takes all `angular.module()` calls and merge the scripts into a single file (or multiple).
 
+Future:
+
+1. Nothing really.
+
+
+
+
+
+
 # Suggestions / Questions / Praises
 
 If you think of something, create an issue!
 
+
+
+
+
+
 # FAQ
 
 
 
+
+### Are there any complex examples out there?
+
+None for now. I want to add some cookbook for this as it can be quite powerful but hard to grasp. I figure that for now the simple case will be enough for most uses.
+
+### Requirejs does X. Why don't you do it?
+
+A mixture of reasons, really. RequireJS has a couple of devs behind it and more bandwidth. Also, I wanted to keep the size really low (AJS-Loader is currently under 3650 bytes minified and uncompressed, while RequireJS sits at 15kb) and performance really high (benchmarks coming later).
+
+Some stuff had to be sacrificed. Mainly, there's no plugin for AJS-Loader, you can't load things that are not scripts (but can load stuff outside of AngularJS modules, of course), it is mainly meant as a developer only script (meaning that production code should use the `concat` script I'm working on), and while path transforms and checkers can be quite powerful, they're also more complex than other solutions.
+
+
+
+
 # Special Thanks
 
 None for now.
diff --git a/angularjs-loader.js b/angularjs-loader.js
@@ -26,20 +26,20 @@ var ANGULARJS_LOADER_DEBUG = true;
  *******************************************************************************
  * Documentation: see http://github.com/hansl/angularjs-loader
  */
-(function(window) {
+(function(window, UNDEFINED) {
 
 /**
  * These constants are just easier to shorten and reuse when using a
  * minificator.
  */
-var UNDEFINED = void 0;
 var NULL = null;
 
 /**
  * Config parameters passed in angular.loader.config().
  * @type Config
  */
 var config = {
+    error: NULL,
     path: {},
     checker: {},
     pathTransform: []
@@ -58,16 +58,16 @@ var angularModuleOriginalFn = window.angular && window.angular.module;
  * Some polyfills.
  */
 // Returns true if the value is of type type.
-function is(value, type) {
+function isOfType(value, type) {
     return typeof value == type;
 }
 // Returns true if the value is a string.
 function isString(value) {
-    return is(value, 'string');
+    return isOfType(value, 'string');
 }
 // Returns true if the value is an object.
 function isObject(value) {
-    return is(value, 'object');
+    return isOfType(value, 'object');
 }
 // Extend an object. See jQuery.extend() for "some" documentation.
 function extend(orig, extension, override) {
@@ -89,8 +89,16 @@ function bind(fn, o, args) {
 }
 
 
+/*******************************************************************************
+ * Error function. If a handler is specified it will be called with the ID and
+ * params. Otherwise this will either throw or log an error on the console.
+ * Optimized, the message will disappear.
+ */
 function error(id, params, msg) {
-    if (ANGULARJS_LOADER_DEBUG) {
+    if (config.error) {
+        config.error(id, params);
+    }
+    else if (ANGULARJS_LOADER_DEBUG) {
         message = msg.replace(/\{\d+\}/g, function(_, i) {
             return params[i];
         });
@@ -569,11 +577,11 @@ if (ANGULARJS_LOADER_TESTING) {
         lockCount = 0;
         isBootstrapped = false;
         locks = {};
-        mainModulePathArg = null;
-        rootPathArg = null;
-        timeoutArg = null;
-        bootstrapFnArg = null;
-        angularModuleOriginalFn = null;
+        mainModulePathArg = NULL;
+        rootPathArg = NULL;
+        timeoutArg = NULL;
+        bootstrapFnArg = NULL;
+        angularModuleOriginalFn = NULL;
 
         maybeSwapAngularModuleFn();
     }
