booster 0.0.1

data/lib/assets/javascripts/booster/router.js.boost

@@ -0,0 +1,107 @@
+/** @type {Backbone.Router} The one and only application router */
+var router = exports.router = new Backbone.Router();
+
+/** @type {Object.<string, function(Object, function)} ... */
+var params = { };
+
+/** @type {RegExp} Regular expression for finding named parameters in path */
+var namedParam = /[:\*]([\w\d]+)/g;
+
+/**
+ *
+ * @param {string} name The name of the path parameter to catch
+ * @param {function(Object, function)} callback The callback to invoke when handling
+ *                                              routes containing parameters with the
+ *                                              given `name`. This should have the
+ *                                              same signature as regular route middleware
+ *                                              and invoke `next` when done.
+ */
+
+exports.param = function(name, callback) {
+  (params[name] || (params[name] = [])).push(callback);
+}
+
+/**
+ * @param {string} path The route path, passed as-is to `Backbone.Router`
+ * @param {...function(Object, function)} middleware
+ */
+
+exports.route = function(path, middleware) {
+  var parameters = extractParameters(path);
+  var middleware = Array.prototype.slice.call(arguments, 1);
+
+   // The actual route function registered with Backbone. This creates a closure
+   // for the nested `next` function which will be invoked asynchronously as the
+   // application drives it through the middleware stack.
+
+  router.route(path, middleware[middleware.length -1].name, function() {
+    var iter = 0;
+    var run = [];
+    var req = {
+      params: parameters ? normalize(parameters, arguments) : arguments,
+      path: path
+    };
+
+    // Start with any registered parameter middleware. TODO: Determine if it is
+    // OK to move this to the outer `route` function, in which case it would
+    // only include the parameter middleware registered **before** the route
+    // was registered (i.e. no dynamically added param middleware at runtime).
+    _.each(parameters, function(param) {
+      if (params[param]) {
+        run = run.concat(params[param]);
+      }
+    });
+
+    // And append the rest of the middleware registered for this route.
+    run = run.concat(middleware);
+
+    /**
+     * Invokes the middleware, driven by the application asynchronously.
+     * This function is recursive, but there won't be that many middleware
+     * for a route such that the stack will suffer significantly.
+     */
+
+    var next = function() {
+      run[iter++](req, iter < run.length ? next : undefined);
+    }
+
+    next();
+  });
+}
+
+/**
+ * Extracts the named parameters in the given path.
+ *
+ * @param {string} path A URL path that may contain named parameters in the
+ *                      form of `:name` or `*name`.
+ * @return {Array.<string>} An array of all the named parameters found in the
+ *                          path, without `:` and `*`.
+ */
+
+function extractParameters(path) {
+  var match, result = [];
+  while (match = namedParam.exec(path)) {
+    result.push(match[1]);
+  };
+  return result;
+}
+
+/**
+ * Creates a normalized `params` hash that will go into the request argument
+ * to all the route middleware.
+ *
+ * @param {Array.<string>} parameters The named parameters from the URL path that
+ *                                    will be combined with `args` into a hash.
+ * @param {Array.<string>} arguments  The arguments from Backbone which has extracted
+ *                                    them from the location hash.
+ * @return {Object.<string, string>}  A hash where the arguments are keyed by the
+ *                                    parameters.
+ */
+
+function normalize(parameters, args) {
+  var result = { };
+  for (var arg = 0; arg < args.length; ++arg) {
+    result[parameters[arg]] = args[arg];
+  }
+  return result;
+}

data/lib/assets/javascripts/booster/support/binding.js.boost

@@ -0,0 +1 @@
+// To be defined.

data/lib/assets/javascripts/booster/support/helpers.js.boost

@@ -0,0 +1,109 @@
+
+/**
+ * Returns a {Handlebars.SafeString} with HTML for an `<input>` element with name and value based
+ * on the given `attribute` and the current context (`this`) which is expected to be a {Backbone.Model}.
+ *
+ * @param  {string} attribute The name of the attribute to use as the name and value for the textarea
+ * @param  {Object.<String, *>} options Object containing a mandatory `hash` object to be transformed into attributes.
+ * @return {Handlebars.SafeString} A safe string that will not be escaped when used in templates
+ */
+
+exports.input = function(attribute, options) {
+  options = options.hash;
+  options.name = attribute;
+  options.value = this.get(attribute);
+  return tag('input', options);
+}
+
+/**
+ * Returns a {Handlebars.SafeString} with HTML for a `<select>` element with name and content based
+ * on the given `attribute` int the current context (`this`) which is expected to be a {Backbone.Model}.
+ *
+ * @param  {string} attribute The name of the attribute to use as the name and value for the textarea
+ * @param  {Object.<String, *>} options Object containing a mandatory `hash` object to be transformed into attributes.
+ * @return {Handlebars.SafeString} A safe string that will not be escaped when used in templates
+ */
+
+exports.textarea = function(attribute, options) {
+  options = options.hash;
+  options.name = attribute;
+  return tag('textarea', options, this.get(attribute));
+}
+
+/**
+ * @param  {string} attribute The name of the attribute to use as the name and selected option for the select element.
+ * @param  {Object|Array} selectOptions The options to choose from in the select element. This can either be an array
+ *                                      where the key and value will be the same for an option, or an Object where
+ *                                      attribute keys will become __option values__ and the attribute values will
+ *                                      be __presented to the user__.
+ * @param  {Object.<String, *>} options Object containing a mandatory `hash` object to be transformed into attributes.
+ * @return {Handlebars.SafeString} A safe string that will not be escaped when used in templates
+ */
+
+exports.select = function(attribute, selectOptions, options) {
+  options = options.hash;
+  options.name = attribute;
+
+  var value = this.get(attribute);
+
+  if (_.isArray(selectOptions)) {
+    selectOptions = _.map(selectOptions, function(option) { // Intentional non-strict comparison below
+      return '<option value="#{option}" #{value == option ? "selected" : ""}>#{option}</option>';
+    });
+  } else {
+    selectOptions = _.map(_.keys(selectOptions), function(key) { // Intentional non-strict comparison below
+      return '<option value="#{key}" #{value == key ? "selected" : ""}>#{selectOptions[key]}</option>';
+    });
+  }
+
+  return tag('select', options, '\n' + selectOptions.join('\n') + '\n');
+}
+
+/**
+ * Returns a {Handlebars.SafeString} with HTML for an `<input type="radio">` element with name and selected state
+ * based on the given `attribute` and the current context (`this`) which is expected to be a {Backbone.Model}.
+ *
+ * @param  {string} attribute The name of the attribute to use as the name and checked state for the radio button
+ * @param  {*} value The value of the radio button -- if the value of the attribute is the same as this value
+ *                   the radio button will be checked. Correspondingly, checking this radio button will set the
+ *                   model attribute to this value.
+ * @param  {Object.<String, *>} options Object containing a mandatory `hash` object to be transformed into attributes.
+ * @return {Handlebars.SafeString} A safe string that will not be escaped when used in templates
+ */
+
+exports.radio = function(attribute, value, options) {
+  options = options.hash;
+  options.name = attribute;
+  options.value = value;
+  options.type = 'radio';
+
+  if (this.get(attribute) === value) {
+    options.checked = true;
+  }
+
+  return tag('input', options);
+}
+
+/**
+ * Generic helper for creating HTML tags.
+ *
+ * @param {string} name The tag name, for instance `"input"` or `"textarea"`
+ * @param {Object.<String,*>} options A set of options that will be converted into HTML attributes. The values will
+ *                                    have `toString` invoked on them
+ * @param {*=} content Tag content, if any. The result of `content.toString()` will be placed inside the tag.
+ */
+
+function tag(name, options, content) {
+  var attributes = [];
+  _.each(options, function(value, attribute) {
+    attributes.push('#{attribute}="#{value}"');
+  });
+  return new Handlebars.SafeString('<#{name} #{attributes.join(" ")}>#{content || ""}</#{name}>');
+}
+
+// Initialization code for this module; every function exported as a helper is
+// registered as a handlebars-helper so that they can be used directly from
+// Handlebars templates, in addition from JavaScript.
+_.each(exports, function(helper, name) {
+  Handlebars.registerHelper(name, helper);
+});

data/lib/assets/javascripts/booster/support/i18n.js.boost

@@ -0,0 +1,136 @@
+/** @type {RegExp} Regular expression used for capturing string interpolations in the translations **/
+var matcher = /#\{([A-Za-z_0-9]*)\}/gm;
+
+/**
+ * Hash where translations go. The application needs to fill this
+ * out using potentially nested objects where each key corresponds
+ * to a translation (string) or whatever type you like for the key.
+ *
+ * @type {Object.<string, Object>}
+ */
+
+exports.translations = { };
+
+/**
+ * Returns the translation corresponding to the given key. If the
+ * translation is a string containing interpolations, these are resolved
+ * using the keys in the given options hash.
+ *
+ * The translations need not necessarily be strings and can be any
+ * type you like. For instance, it might be a good idea to store complete
+ * hashes with select options to be used in select elements directly
+ * under a key in the translations.
+ *
+ * var I18n = require('booster/support/i18n');
+ * var translation = I18n.t('views.discussion.edit.status_options')
+ *
+ * @param {String} the (composite) key to use when locating translations
+ * @param {Object} options currently only used for string interpolations
+ */
+
+exports.translate = exports.t = function(key, options) {
+  var translation = _.reduce(key.split('.'), function(memo, key) {
+    return memo ? memo[key] : undefined;
+  }, exports.translations);
+
+  // Interpolate string translation, replacing %{attribut} with option value
+  if (typeof translation === 'string') {
+    return _.reduce(translation.match(this.matcher), function(memo, match) {
+      key = match.replace(I18n.matcher, '$1');
+      return memo.replace(match, (options && options[key]) || ('[Missing option: ' + key + ']'));
+    }, translation)
+  }
+
+  return translation || (options && options.silent ? '' : ('[Missing translation: ' + key + ']'));
+}
+
+/**
+ * A model mixin that makes it easier for models to expose internationalized
+ * attribute names to be used as form labels, for instance. It estabslishes a
+ * convention for naming keys in the translations hash exported from this module,
+ * and introduces shortcut functions for reading those translations.
+ *
+ * **Example:**
+ *     
+ *     var I18n = require('booster/support/i18n);
+ *     
+ *     I18n.translations = {
+ *       modelNames: {
+ *         user: 'User'
+ *       },
+ *
+ *       attributeNames: {
+ *         user: {
+ *           firstName: 'First name',
+ *           lastName: 'Last name',
+ *         }
+ *       },
+ *
+ *       valueNames: {
+ *         user: {
+ *           status: {
+ *             0: 'Inactive',
+ *             1: 'Active'
+ *           }
+ *        }
+ *     }
+ *
+ * This mixin is intended to be applied to model constructor functions
+ * and not model constructor prototypes to allow the functions to be invoked
+ * directly on a constructor (App.Models.Customer.modelName() for instance) as
+ * well as on individual instances (someCustomer.constructor.modelName()).
+ *
+ * **Example:**
+ *
+ *     exports.Model = Backbone.Model.extend({
+ *        ...
+ *     });
+ *
+ *     _.extend(exports.Model, require('booster/support/i18n').mixin('user'));
+ *
+ * The namespace argument is required to indicate the namespace used in the `exports.translations`
+ * object where the current translations can be found since the name of the model can't be inferred.
+ *
+ * @param {String} basically the name of the model which gets used when doing translation lookups
+ */
+
+exports.mixin = function(namespace) {
+
+  return {
+
+    /**
+     * Returns the translated name for the model "class" based on the namespace used when mixed in.
+     *
+     * @return {string} The translated name of the model.
+     */
+
+    modelName: function() {
+      return exports.t('modelNames.' + namespace);
+    },
+
+    /**
+     * Returns the translated name for the given attribute.
+     *
+     * @param {string} attribute The name of the model attribute to translate.
+     * @return {string}
+     */
+
+    attributeName: function(attribute) {
+      return exports.t('attributeNames.' + namespace + '.' + attribute);
+    },
+
+    /**
+     * Returns the translated name for the given attribute and value. This is mostly
+     * used for attributes of Number type, for instance a `status` attribute that stores
+     * Numbers that should be translated to "Open", "Closed", "Pending", for instance, based
+     * on a fixed set of possible values for the attribute.
+     *
+     * @param {string} attribute The name of the attribute the value applies to
+     * @param {*} attribute The attribute value to translate. Must respond to `toString()`.
+     */
+ 
+    attributeValueName: function(attribute, value) {
+      return exports.t('valueNames.' + namespace + '.' + attribute + '.' + value);
+    }
+  }
+}

data/lib/assets/javascripts/booster/support/observer.js.boost

@@ -0,0 +1,81 @@
+
+/**
+ * Exposes the local `mixin` as a function to allow it to be parameterized in the
+ * future without breakage, and to align it with other mixins that already are
+ * parameterized. The actual mixin object is stored outside of the function
+ * to prevent unnecessary creation of Function objects.
+ *
+ * @return {Object} A mixin object that can be applied to any {Backbone.Model}
+ */
+
+exports.mixin = function() {
+  return mixin;
+}
+
+/**
+ * A generic mixin that can be applied to any object that wants to track all the
+ * event bindings it makes to any {Backbone.Events} source during its lifetime.
+ * This is achieved by introducing the `observe` and `unobserve` functions that
+ * forwards to the `bind` and `unbind` functions, respectively, of the subject that
+ * they are invoked on.
+ *
+ * As an example, this mixin is applied to the Booster View implementation to track
+ * all the bindings inheriting views do to any models, collections, and other
+ * event sources so that they can be automatically unbound when the view leaves the
+ * DOM and its parent view.
+ *
+ * Instead of using the traditional `this.model.bind("change", this.render)`  the
+ * observe function can be used; `this.observe(this.model, "change", this.render)`.
+ * All `observe` calls ever made by "`this`" can be undone by invoking `unobserve`,
+ * which is what the Booster View implementation does in its `leave` function.
+ *
+ * `observe` automatically makes `this` the context of the callback so that
+ * when using `this.observe(this.model, "change", this.render)`, `render` will be
+ * invoked such that `this` refers to the same object on which `observe` was invoked.
+ */
+
+var mixin = {
+
+  /**
+   * Binds `this` to the given `event` and `subject` using the {Backbone.Events} API.
+   * The binding is recorded internally so that it can be easily undone later in a
+   * generic manner.
+   *
+   * @param {Backbone.Events} subject Any object that mixes in {Backbone.Event}
+   * @param {string} event The name of the event to subscribe to
+   * @param {function(Backbone.Events)} callback Function that will be invoked when
+   *                                             the event is triggered. The `subject` will
+   *                                             be passed as an argument. `this` will refer
+   *                                             to the object on which `observe` was invoked.
+   */
+  observe: function(subject, event, callback) {
+    subject.bind(event, callback, this);
+    this._subjects || (this._subjects = []);
+    this._subjects.push([subject, event, callback]);
+  },
+
+  /**
+   * Unbinds the given `event` and `callback` from `subject`. If no arguments are given,
+   * all events ever bound to, on any subject, will be removed. This essentially undos every
+   * `observer` call ever made to on this object.
+   *
+   * @param {Backbone.Events=} subject A subject observed earlier with `observe` (optional)
+   * @param {string=} event The name of and event observed earlier with `observe` (optional)
+   * @param {function(Backbone.Events)=} callback A callback registered earlier with `observe` (optional)
+   */
+
+  unobserve: function(subject, event, callback) {
+    if (subject === undefined) {
+      _.each(this._subjects, function(subject) {
+        subject[0].unbind(subject[1], subject[2]);
+      });
+      delete this._subjects;
+    } else {
+      subject.unbind(event, callback);
+      this._subjects = _.reject(this._subjects, function(subject) {
+        return subject[0] === subject && subject[1] === event;
+      });
+    }
+  }
+
+}

data/lib/assets/javascripts/booster/support/schema.js.boost

@@ -0,0 +1,117 @@
+
+/**
+ * Exposes the local `mixin` as a function to allow it to be parameterized in the
+ * future without breakage, and to align it with other mixins that already are
+ * parameterized. The actual mixin object is stored outside of the function
+ * to prevent unnecessary creation of Function objects.
+ *
+ * @return {Object} A mixin object that can be applied to any {Backbone.Model}
+ */
+
+exports.mixin = function() {
+  return mixin;
+}
+
+/**
+ * A {Backbone.Model} mixin that introduces support for declaratively specifying that
+ * one or more nested attributes are to be wrapped in {Backbone.Model}s,
+ * {Backbone.Collection}s, or any other type (via constructor) when accessed via the regular
+ * `get()` accessor.
+ *
+ * @type {Object}
+ */
+
+var mixin = {
+
+  /**
+   * Overrides the {Backbone.Model} `get` function to allow attributes of object or array type
+   * to be lazily converted into collections and models which are memoized inside the model instance.
+   * This is an alternative to, for instance, instantiating these nested objects in the
+   * `initialize` function.
+   *
+   * @param {string} attribute The name of the attribute to retrieve.
+   * @override
+   */
+
+  get: function(attribute) {
+
+    // Fast case; the attribute has been accessed before for this model and has already been transformed
+    // using the schema type constructor. We optimize for this and return the memoized value immediately.
+    if (this._memoized && this._memoized[attribute]) {
+      return this._memoized[attribute];
+    }
+
+    // This is the actual internal attribute value which we may need to convert or return as-is.
+    var value = this.attributes[attribute];
+
+    // If the model prototype has specified a schema with an entry for this particular attribute
+    // we go ahead and process it.
+    if (this.schema && this.schema[attribute]) {
+      var type = this.schema[attribute];
+      if (typeof type === 'object') {
+        type = type.type;
+      }
+
+      if (value.constructor !== type) {
+        value = new type(value);
+        value.parent = this;
+
+        // Determine if the value should be memoized for performance reasons. Some types of values
+        // are memoized by default and some by marking the attribute as `{memoized: true}` in the schema.
+        // Memoized values override the internal attribute value so that can be removed from the model
+        // to preserve memory.
+        if (shallMemoize(type)) {
+          this._memoized || (this._memoized = {});
+          this._memoized[attribute] = value
+          delete this.attributes[attribute];
+        }
+      }
+    }
+
+    return value;
+  },
+
+  /**
+   * Overrides {Backbone.Model}.toJson to not only return the internal attributes for the
+   * model, but also any mapped nested models and collections. Nested collections and models are
+   * based on the attributes in a model on instantiation, but manage their own dataset which
+   * needs to be merged back into the model when serialized.
+   *
+   * @return {Object} An object with the internal attributes merged with the attributes of any
+   *                  nested models and collections, recursively. Note that this is not a true
+   *                  JSON string as per the default behavior in {Backbone.Model}
+   * @override
+   */
+
+  toJSON: function() {
+    var self = this;
+    var json = _.clone(this.attributes);
+
+    _.each(this.schema, function(definition, attribute) {
+      if (definition.serialize === false) {
+        delete json[attribute];
+      } else if (_.isFunction(definition.serialize)) {
+        json[attribute] = definition.serialize(self.get(attribute));
+      } else {
+        var value = self.get(attribute);
+        json[attribute] = value.toJSON ? value.toJSON() : value;
+      }
+    });
+
+    return json;
+  }
+}
+
+/**
+ * Returns true if the conversion of an attribute to the given `type` should be
+ * memoized inside the model instance.
+ *
+ * @type {function} The type constructor to evaluate.
+ */
+
+function shallMemoize(type) {
+  return type.prototype instanceof Backbone.Model ||
+         type.prototype instanceof Backbone.Collection ||
+         type === Backbone.Model ||
+         type === Backbone.Collection;
+}