Saturday, September 12, 2015

The Eh (Canadian) programming language

I know a guy who is Canadian and, just for fun, I wrote a programming language for him.

The language is the Eh programming language.   The syntax is similar to JavaScript, except that instead of a line ending with a semicolon, it ends with a comma, a space, the word "eh" and a question mark (?).  For example:
var src = 'script', eh?
var s = '', eh?
s += 'Hello', eh?
s += ' ', eh?
s += 'World', eh?
s += ' from ' + src, eh?
console.log(s), eh?
This will print the following to the JavaScript console:
Hello World from script
An Eh script can be included inline using the "text/eh" type:

Or loaded from an external script file:

Here's the source code for the Eh compiler (in JavaScript) named eh.js:
// eh compiler
window.onload = function() {
  // execute eh code
  function executeEh(src) {
    eval(src.replace(/,\seh\?/g, ';'));
  }
  // load eh scripts
  var scripts = document.getElementsByTagName('script');
  for (var s=0; s < scripts.length; s++) {
    if (scripts[s].type === 'text/eh') {
      if (scripts[s].src) {
        // execute external eh scripts
        var extScript = new XMLHttpRequest();
        extScript.open("GET", scripts[s].src, true);
        extScript.send();
        extScript.onreadystatechange = function() {
          if ((extScript.readyState== 4)
              && (extScript.status == 200)) {
            executeEh(extScript.responseText);
          }
        };
      } else {
        // execute inline eh scripts
        executeEh(scripts[s].innerHTML);
      }
    }
  }
}
Eh supports all major JavaScript libraries and APIs.

Here's a Plunker to demonstrate: http://plnkr.co/edit/ASrEWq3uoZgi6TwolGLd

If you make an Eh script, comment below and let me know!

Tuesday, September 1, 2015

Put your Git branch in your Mac or Linux prompt

There is a lot of examples out there but here's a basic way to show your Git branch in your profile.

First, edit your .bash_profile.
$ vi .bash_profile
Press "i" to put vi in "insert mode".  Then, add the following to your .bash_profile:
ps1_git_branch() {
git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/ (\1)/'
}
export PS1="\w\$(ps1_git_branch)\$ "
After making this change and starting a new Terminal, the prompt will show the following in non-Git folders:
~/Documents $
In Git folders, the prompt will show the following (if you are on the "master" branch):
~/Documents/git/code (master)$
Very convenient.

Friday, August 14, 2015

JavaScript private data using createPrivateThis()

In JavaScript, all object properties are public.

But, coming from Java and a long line of languages before it, I've seen how private properties can enforce better designs.  Is there a convenient way to enforce private properties in JavaScript?

Up to now, there were four proposed solutions:
  1. Imaginary privacy: Put an underscore (_) in front of all private properties to indicate that they are private.
  2. Everything in the constructor: Use closure and attach all your functions to the this object; don't use Object.prototype.func = anymore.
  3. Weakmaps: http://www.nczonline.net/blog/2014/01/21/private-instance-members-with-weakmaps-in-javascript/
  4. Everything public: Why care?
I am now proposing a fifth solution: createPrivateThis().

My objectives were simple:
  1. Provide Java-style public and private data in JavaScript.
  2. Prevent read access to the private data from outside the object.
  3. Allow functions to be created on the prototype object as normal.
  4. Allow functions on the prototype object to access public and private data using the this pointer.
Here's the code that I came up with:
/**
 * Wrap the prototype functions and put the wrappers on the
 * object itself.  A wrapper merges the object and private
 * properties before the call, makes the call then unmerges
 * the object and private properties.
 *
 * Normally, you create your private data in the constructor
 * function and give distinct names to public and private
 * data.  Then, during function calls, you use the this
 * pointer for BOTH public and private data.  In ambiguous
 * situations, the private data is operated on with the
 * exception that adding/deleting data defaults to the
 * (public) object.
 *
 * It is possible to create private functions and variables
 * with the same name using the transitory getPrivateThis()
 * method but this is NOT recommended and is an advanced use.
 *
 * @param {Object} obj The object that needs private data.
 * @return {Object} The private data pointer (this_p).
 */
function createPrivateThis(obj) {
  // use Underscore.js or our own mini version
  var __ = (typeof _ === 'undefined')? {
    isFunction: function(f) {
        return f 
           & {}.toString.call(f) == '[object Function]';
    },
    has: function(o, k) {
      return o.hasOwnProperty(k);
    },
    keys: function(o) {
      return Object.keys(o);
    },
    clone: function(o) {
      var k, o2 = {};
      for (k in o) {
        if (o.hasOwnProperty(k)) {
          o2[k] = o[k];
        }
      }
      return o2;
    },
    each: function(oa, f) {
      var i, k;
      if (oa.constructor === Array) {
        for (i=0; i < oa.length; ++i) {
          f(oa[i]);
        }
      } else {
        for (k in oa) {
          if (oa.hasOwnProperty(k)) {
            f(oa[k], k);
          }
        }
      }
    },
    extend: function() {
      var a, arg, d = arguments[0];
      for (a=1; a < arguments.length; ++a) {
        arg = arguments[a];
        for (var k in arg) {
          if (arg.hasOwnProperty(k)) {
            d[k] = arg[k];
          }
        }
      }
      return d;
    },
    union: function() {
      var a = Array.prototype.concat.apply({}, arguments)
      var b = [], a1, i;
      while (a.length > 0) {
        a1 = a.pop();
        for (i=0; (i < b.length) && (a1 !== b[i]); ++i) ;
        if (i === b.length) {
          b.push(a1);
        }
      }
      return b;
    }
  }: _;
  var priv = {};
  var getPriv = function() {
    return priv;
  };
  // iterate over each function in the object prototype
  __.each(obj.constructor.prototype, function(value, key) {
    if (__.isFunction(value) && !__.has(obj, key)) {
      // intercept the function on the object itself
      obj[key] = function() {
        var pre = __.clone(priv);
        // combine the object and its private properties
        var full = __.extend({}, obj, priv);
        // add the getPrivateThis() access function
        full.getPrivateThis = getPriv;
        // invoke original function with combined object
        var r = value.apply(full, arguments);
        // remove the getPrivateThis() access function
        delete full.getPrivateThis;
        var objKeysToUpdate = {}, objKeysToDelete = {};
        var privKeysToUpdate = {}, privKeysToDelete = {};
        var allKeys = __.union(__.keys(pre), __.keys(priv),
          __.keys(obj), __.keys(full));
        // decide what to do with every key that we ever saw
        __.each(allKeys, function(key) {
          if (__.has(pre, key) !== __.has(priv, key)) {
            // private property was added or deleted
            // using getPrivateThis()
            if (__.has(full, key)) {
              // add/modify object property with the same name
              objKeysToUpdate[key] = full[key];
            } else if (!__.has(full, key) && __.has(obj, key)) {
              // delete object property with the same name
              objKeysToDelete[key] = 'delete';
            }
          } else if (__.has(full, key) && __.has(priv, key)) {
            // modify private property
            privKeysToUpdate[key] = full[key];
          } else if (!__.has(full, key) && __.has(priv, key)) {
            // delete private property
            privKeysToDelete[key] = 'delete';
          } else if (__.has(full, key) && !__.has(priv, key)) {
            // add/modify object property
            objKeysToUpdate[key] = full[key];
          } else if (!__.has(full, key) && __.has(obj, key)) {
            // delete object property
            objKeysToDelete[key] = 'delete';
          }
        });
        // do what we decided to do with the keys
        __.each(objKeysToUpdate, function(value, key) {
          obj[key] = value;
        });
        __.each(objKeysToDelete, function(value, key) {
          delete obj[key];
        });
        __.each(privKeysToUpdate, function(value, key) {
          priv[key] = value;
        });
        __.each(privKeysToDelete, function(value, key) {
          delete priv[key];
        });
        return r;
      };
    }
  });
  return priv;
}

The core idea is to create wrapper functions on the this object which automatically intercept the calls to the functions defined on the prototype object.  The automatically generated interception functions combine the this and the private data, make a call to the prototype function, then uncombine the data back into the this and the private data.

In practice, createPrivateThis() is used like this:
function Animal() {
  var this_p = createPrivateThis(this);
  this_p.nickname = "NoName";
  this.type = 'animal';
}

Animal.prototype.getPrivateNickname = function() {
  // this.nickname is private but we can access it inside here
  return this.nickname;
};

Animal.prototype.setPrivateNickname = function(nick) {
  // this.nickname is private but we can access it inside here
  this.nickname = nick;
};

Animal.prototype.getPublicType = function() {
  return this.type;
};

Animal.prototype.setPublicType = function(type) {
  this.type = type;
};

The private property, nickname, is not accessible outside the object.  It is accessed via the this pointer but it does not actually reside on the object.  The private property actually exists as a local variable in the createPrivateThis() function that is accessed via closure (only available inside the function).

Thursday, August 13, 2015

Make Mac Minecraft work on Oracle Java

My son likes to play Minecraft.  I like to use Oracle Java 8 instead of the decrepit Apple Java (6) that Apple insists on.  Can't Minecraft use Oracle Java 8?

It can but it took me 6 months to figure out how to do it right.  You can modify the Minecraft Mac application so it will work on whatever is installed, either Oracle Java 8 or Apple Java 6.  You can even do it without starting a Terminal (but I'll tell you how to do it in Terminal, too).

On MacOS X Yosemite:

1.  Make a copy of your Minecraft application for backup.

2.  Start Safari and go to this page:

https://raw.githubusercontent.com/tofi86/universalJavaApplicationStub/master/src/universalJavaApplicationStub

This is a bash script from https://github.com/tofi86/universalJavaApplicationStub GitHub project.

3.  Choose the "File" menu, then select the "Save As..." menu item.  Select the "Page Source" item in the "Format" dropdown list.  Now, save it using the default name (i.e. universalJavaApplicationStub) on your Desktop.

4.  Go to the Applications folder, right click on the Minecraft application and select "Show Package Contents".  A Finder window will open.  Double-click on the Contents folder to open it.  Start Finder and choose the "Go" menu, then select the "Go to Folder..." menu item.  Type "/Applications/Minecraft.app/Contents" and press the "Go" button.  A Finder window will open.

5.  Double-click on the MacOS folder.  If it is a Java application, you will probably see a single file named JavaApplicationStub in the MacOS folder.

6.  Drag the universalJavaApplicationStub into the MacOS folder.  Now, there are two files in there.

7.  Right click on universalJavaApplicationStub and select the "Get Info" menu item.  Open the "Name & Extensions" item.

8.  If the "Hide extension" checkbox is enabled and checked, uncheck it.

9.  In the text box, delete the extension (probably ".txt") and close the "Get Info" box.

10.  If you get "Are you sure you want to remove the extension ".txt"?" prompt, press the "Remove" button.  (The icon for universalJavaApplicationStub will change to a green CRT terminal icon with the text, "exec", on it.)  Leave the "MacOS" Finder window open.

11.  Oh, I lied.  You do have to use Terminal.  Open the Applications folder, open the Utilities and run Terminal application.

12.  Paste the following into Terminal and press the "Return" key to execute it:

chmod ugo+x /Applications/Minecraft.app/Contents/MacOS/universalJavaApplicationStub

This command adds eXecute permissions to the file for User, Group and Other.

If you don't get an error, it probably worked.  If you get an error, you can give up on this process and, don't worry, the Minecraft application is undamaged.  In either case, close the Terminal.

13.  Press the back button on the original Finder window to return to the Contents folder.

14.  Right click on the Info.plist file.  Select the "Open With" menu, then choose the "Other..." menu item.  Scroll down and select the "TextEdit" application.  The TextEdit application should start.

15.  Edit and save the file:

A.  Insert "universal" in front of "JavaApplicationStub" so it reads <string>universal JavaApplicationStub</string>.

B.  Insert an "X" at <key>Java</key> to make <key>JavaX</key>.

16.  Go to the Applications folder and run Minecraft.  It should work.  You're done.

If you want to perform this same process entirely in Terminal, start a Terminal and do this:

$ cp -r /Applications/Minecraft.app /Applications/Minecraft\ copy.app
$ cd /Applications/Minecraft.app/Contents
$ curl "https://raw.githubusercontent.com/tofi86/universalJavaApplicationStub/master/src/universalJavaApplicationStub" -o "MacOS/universalJavaApplicationStub"
$ chmod ugo+x MacOS/universalJavaApplicationStub
$ vi Info.plist
Press i to insert text
- <string>JavaApplicationStub</string>
+ <string>universalJavaApplicationStub</string>
- <key>Java</key>
+ <key>JavaX</key>
Press Esc, then type ZZ which will save

This technique should work for any Mac Java application, as long as you go to the correct .app folder.

Don't forget that you have to a backslash (\) before any spaces in the name when using Terminal so Minecraft copy.app becomes Minecraft\ copy.app.

If you need to troubleshoot, try running universalJavaApplicationStub from the Terminal and see if it launches Minecraft or gives you error messages.  If that works, try running the open command so open /Applications/Minecraft.app and see if that launches Minecraft or gives you error messages.  The error messages can be somewhat cryptic but, with Google, perhaps you can figure out what the issue is.

References:
http://apple.stackexchange.com/questions/88110/make-minecraft-or-java-preferences-app-run-on-java-7
http://gaming.stackexchange.com/questions/178178/making-minecraft-run-with-java-8-on-os-x-10-10
http://www.cgwerks.com/make-minecraft-work-mac-osx-yosemite-latest-java-8/
https://gist.github.com/pudquick/7518753
http://www.minecraftforum.net/forums/support/unmodified-minecraft-client/1858141-minecraft-x64-for-mac-with-java-7
https://bugs.mojang.com/browse/MCL-1049
http://mosx.tumblr.com/post/64402950499/os-x-tip-execute-java-apps-like-minecraft-or
http://stackoverflow.com/questions/14806709/application-is-using-java-6-from-apple-instead-of-java-7-from-oracle-on-mac-os-x
http://superuser.com/questions/490425/how-do-i-switch-between-java-7-and-java-6-on-os-x-10-8-2

Thursday, July 30, 2015

What does _.bind() do?

The name, "bind", conjures fear.  It's scary.  Binding sounds mysterious and strange.

Underscore.js has the _.bind() function.  What does it do?

Let's say that you using the JavaScript setTimeout() function to set the focus on a jQuery DOM element.

var el = $('#myinput');
setTimeout(function() { el.focus(); }, 50);

The setTimeout() function takes a standalone function as its first argument.

Now, consider this code:

var el = $('#myinput');
setTimeout(el.focus, 50);

This code doesn't work.  Why?  Well, the focus() call is an object method, not a standalone function.  The setTimeout() function expects a standalone function, not an object method.

A standalone function and an object method aren't the same thing.  If you pass an object method as an argument that expects a standalone function, it's not the same thing, it's wrong and it doesn't work.

It's as if you passed a string as an argument to a function that expects a number.  You passed the wrong kind of thing, even if the string contains a number.  If you want it to work, you have to convert the string to the proper type before calling the function.

So, how can you convert an object method call into a standalone function?

One way is to create a standalone function that calls the object method as you did in the original code.

A second way is to call the _.bind() function.

The _.bind() function says, "Create a standalone function that invokes the method in the first argument, using the second argument as the this object."

So, instead of creating your own standalone function, the _.bind() function will create one for you.

var el = $('#myinput');
setTimeout(_.bind(el.focus, el), 50);

The _.bind(el.focus, el) code creates a standalone function that calls the el.focus() method.  You can think of it as converting a method (call) into a standalone function.

The _.bind() implementation is more complex but you can understand it by imagining that it is implemented like this:

function bind(method, self) {
  return function() {
    self.method(); // this doesn't work; it's just for clarity
  };
}

That's what _bind.() does.  It takes a method call and "converts" it into a standalone function.

Once you grasp this, you will discover that _.bind() has additional uses, such as converting a standalone function call with multiple arguments into a standalone function with no arguments.

With this explanation, I hope that _.bind() and binding is no longer mysterious and strange.  And not scary.


AngularJS dependency resolution and child controller creation

Suppose that you have an AngularJS template (HTML with AngularJS tags, same thing) and an AngularJS controller and you want to execute them together:

var elem = angular.element(angularTemplateHtml);
var compileFunc = $compile(elem);
$controller(controllerName, locals);
elem = compileFunc($scope);

This is how ngRoute bootstraps a route.

Suppose that the controller has dependencies.  How are they resolved?

Deep inside angular.js, there is an invoke() function that looks like this:

function invoke(fn, self, locals, serviceName) {
  if (typeof locals === 'string') {
    serviceName = locals;
    locals = null;
  }
  var args = [],
    $inject = createInjector.$$annotate(fn, strictDi, serviceName),
    length, i,
    key;

  for (i = 0, length = $inject.length; i < length; i++) {
    key = $inject[i];
    if (typeof key !== 'string') {
      throw $injectorMinErr('itkn',
        'Incorrect injection token! Expected service name as string, got {0}', key);
    }
    args.push(
      locals && locals.hasOwnProperty(key)
      ? locals[key]
      : getService(key, serviceName)
    );
  }
  if (isArray(fn)) {
    fn = fn[length];
  }
  // http://jsperf.com/angularjs-invoke-apply-vs-switch
  // #5388
  return fn.apply(self, args);
}

AngularJS looks for dependencies in the locals object and getService().  If it doesn't find the dependency in either place, the dependency fails and you get an error.

It's interesting that you can bolt dependencies onto the locals object.  The locals object is passed directly into the $controller() function so, if you are calling $controller() function directly, you can provide dependencies to the controller, even if those dependencies aren't AngularJS services.

The $controller() function itself looks like this:

/**
 * @ngdoc service
 * @name $controller
 * @requires $injector
 *
 * @param {Function|string} constructor If called with a function
 * then it's considered to be the controller constructor function.
 * Otherwise it's considered to be a string which is used to
 * retrieve the controller constructor using the following steps:
 *
 *  * check if a controller with given name is registered via 
 *    `$controllerProvider`
 *  * check if evaluating the string on the current scope returns
 *    a constructor
 *  * if $controllerProvider#allowGlobals, check
 *    `window[constructor]` on the global `window` object (not
 *    recommended)
 *
 * The string can use the `controller as property` syntax, where
 * the controller instance is published as the specified property
 * on the `scope`; the `scope` must be injected into `locals` param
 * for this to work correctly.
 *
 * @param {Object} locals Injection locals for Controller.
 * @return {Object} Instance of given controller.
 *
 * @description
 * `$controller` service is responsible for instantiating
 * controllers.
 *
 * It's just a simple call to {@link auto.$injector $injector}, but
 * extracted into a service, so that one can override this service
 * with [BC version](https://gist.github.com/1649788).
 */
return function(expression, locals, later, ident) {
  // PRIVATE API:
  //   param `later` --- indicates that the controller's constructor
  //     is invoked at a later time. If true, $controller will
  //     allocate the object with the correct prototype chain, but
  //     will not invoke the controller until a returned callback is
  //     invoked.
  //   param `ident` --- An optional label which overrides the label
  //     parsed from the controller expression, if any.
  var instance, match, constructor, identifier;
  later = later === true;
  if (ident && isString(ident)) {
    identifier = ident;
  }

  if (isString(expression)) {
    match = expression.match(CNTRL_REG);
    if (!match) {
      throw $controllerMinErr('ctrlfmt',
        "Badly formed controller string '{0}'. " +
        "Must match `__name__ as __id__` or `__name__`.",
        expression);
    }
    constructor = match[1],
    identifier = identifier || match[3];
    expression = controllers.hasOwnProperty(constructor)
      ? controllers[constructor]
      : getter(locals.$scope, constructor, true) ||
        (globals ? getter($window, constructor, true) : undefined);
        assertArgFn(expression, constructor, true);
  }

  if (later) {
    // Instantiate controller later:
    // This machinery is used to create an instance of the object
    // before calling the controller's constructor itself.
    //
    // This allows properties to be added to the controller before
    // the constructor isinvoked. Primarily, this is used for
    // isolate scope bindings in $compile.
    //
    // This feature is not intended for use by applications, and is
    // thus not documented publicly.
    // Object creation: http://jsperf.com/create-constructor/2
    var controllerPrototype = (isArray(expression) ?
      expression[expression.length - 1] : expression).prototype;
    instance = Object.create(controllerPrototype || null);

    if (identifier) {
      addIdentifier(locals, identifier, instance, constructor
        || expression.name);
    }

    var instantiate;
    return instantiate = extend(function() {
      var result = $injector.invoke(expression, instance, locals,
        constructor); // resolve dependencies
      if (result !== instance && (isObject(result)
        || isFunction(result))) {
        instance = result;
        if (identifier) {
          // If result changed, re-assign controllerAs value to
          // scope.
          addIdentifier(locals, identifier, instance, constructor
            || expression.name);
        }
      }
      return instance;
    }, {
      instance: instance,
      identifier: identifier
    });
  }
  instance = $injector.instantiate(expression, locals, constructor);

The $controller() function's first argument is expression.   This is either a controller object or its a string with the controller's name.  If it's a string with the controller's name, the $controller() function immediately looks up the controller object and sets expression equal to the object.

Then, the $controller() function chooses whether to create the object instance and return the constructor function to be called later (in green text) or to create the object instance and call the constructor immediately.

In our example, the constructor is called immediately.

But what happens if angularTemplateHtml contains additional controllers that are created by using the ng-controller attribute?

When $compile() function is invoked, it crawls through the angularTemplateHtml DOM tree using functions named nodeLinkFn()childLinkFn() and compositeLinkFn() to find and instantiate AngularJS constructs, like controllers.

The compileFunc() function is created and returned by the $compile() call.

Inside AngularJS, the compileFunc() function looks like this:

return function publicLinkFn(scope, cloneConnectFn, options) {
  assertArg(scope, 'scope');

  options = options || {};
  var parentBoundTranscludeFn = options.parentBoundTranscludeFn,
    transcludeControllers = options.transcludeControllers,
    futureParentElement = options.futureParentElement;

AngularJS crawls the angularTemplateHtml DOM tree during the $compile() function and, when it finds a ng-controller attribute, it invokes the setupControllers() function.

function setupControllers($element, attrs, transcludeFn,
    controllerDirectives, isolateScope, scope) {
  var elementControllers = createMap();
  for (var controllerKey in controllerDirectives) {
    var directive = controllerDirectives[controllerKey];
    var locals = {
      $scope: directive === newIsolateScopeDirective
        || directive.$$isolateScope ? isolateScope : scope,
      $element: $element,
      $attrs: attrs,
      $transclude: transcludeFn
    };
    var controller = directive.controller;
    if (controller == '@') {
      controller = attrs[directive.name];
    }

    var controllerInstance = $controller(controller, locals, true,
      directive.controllerAs);

Notice the bold purple text where the locals object is created by AngularJS when it finds an ng-controller attribute.  While a child controller can access its parent's $scope for various purposes, a child controller's locals object is hardcoded, unavailable and unlinked to the parent controller's locals object!  So, a parent controller cannot resolve dependencies for a child controller created by AngularJS.  Wouldn't it be nice if a parent controller could use its locals object to provide dependency resolution and control over instantiation of its child controllers?  But, it doesn't.  Maybe next version.

Notice the orange highlighted true argument inside the setupControllers() function.  The true argument allocates the controller instance but does not invoke the constructor immediately.  It returns the constructor to be invoked later.

AngularJS allocates controller instances during the $compile() call (in our example) but waits and invokes constructors later during the compileFunc() call (in our example).

During the compileFunc() call, the child controller constructor functions are invoked in this code:

if (elementControllers) {
  // Initialize bindToController bindings for new/isolate scopes
  var scopeDirective = newIsolateScopeDirective
    || newScopeDirective;
  var bindings;
  var controllerForBindings;
  if (scopeDirective && elementControllers[scopeDirective.name]) {
    bindings = scopeDirective.$$bindings.bindToController;
    controller = elementControllers[scopeDirective.name];

    if (controller && controller.identifier && bindings) {
      controllerForBindings = controller;
      thisLinkFn.$$destroyBindings = 
        initializeDirectiveBindings(scope, attrs,
        controller.instance, bindings, scopeDirective);
    }
  }
  for (i in elementControllers) {
    controller = elementControllers[i];
    var controllerResult = controller();

    if (controllerResult !== controller.instance) {
      // If the controller constructor has a return value,
      // overwrite the instance from setupControllers and update
      //the element data
      controller.instance = controllerResult;
      $element.data('$' + i + 'Controller', controllerResult);
      if (controller === controllerForBindings) {
        // Remove and re-install bindToController bindings
        thisLinkFn.$$destroyBindings();
        thisLinkFn.$$destroyBindings =
          initializeDirectiveBindings(scope, attrs,
            controllerResult, bindings, scopeDirective);
      }
    }
  }
}

Notice the bold red text shows where the child controller construction functions are invoked during the compileFunc() call.

This shows the lifecycle of controller objects, both directly created controllers and controllers created by AngularJS itself.

Monday, July 27, 2015

AngularJS $formatters

Suppose you have a new directive that declares a tag like:

<input type="array">

In AngularJS v1.4.1, when you add an "input" directive, AngularJS decides how its going to store your data.  Will your data be stored as a string (in a text node), in a JavaScript object (hanging off a DOM node) or what?

In the case above, is the data stored as a string like "[1, 2, 3, 4]" in a text node or is it stored as a JavaScript array like ctrl.array = [1, 2, 3, 4]?

It decides by running through a whole list of known (to AngularJS) input types and, if it does not know about a new, unexpected input type, it decides that it must be stored as a string.

The known types are:
  • text
  • date ('yyyy-MM-dd')
  • datetime-local ('yyyy-MM-ddTHH:mm:ss.sss')
  • time ('HH:mm:ss.sss')
  • week ('yyyy-Www')
  • month ('yyyy-MM')
  • number
  • url
  • email
  • radio
  • checkbox
  • hidden
  • button
  • submit
  • reset
  • file
If you default to being stored as a string, it adds this function to the $formatters object on the caller's instantiated directive.

function stringBasedInputType(ctrl) {
  ctrl.$formatters.push(function(value) {
    return ctrl.$isEmpty(value) ? value : value.toString();
  });
}

As you can see, if the object doesn't have a toString() method, it will call the default toString() method for all JavaScript objects.  If that happens, the user's data may be "stored" as "[object Object]".  Oh, no!

To avoid this, make sure that you empty or change the $formatters array so it is appropriate:

angular
  .directive('input', function(...) {
    return {
      restrict: 'E',
      require: '?ngModel',
      link: function($scope, $element, $attributes, ngModel) {
        ngModel.$formatters = [];
        ...

That way, you can get the unformatted object and handle it appropriately.