xooie 0.1.7 → 1.0.0

data/vendor/assets/javascripts/xooie/widgets/base.js

@@ -0,0 +1,644 @@
+/*
+* Copyright 2012 Comcast
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*     http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/**
+ * class Xooie.Widget
+ *
+ * The base xooie widget.  This widget contains all common functionality for Xooie widgets but does not provide
+ * specific functionality.
+ **/
+
+define('xooie/widgets/base', ['jquery', 'xooie/xooie', 'xooie/helpers', 'xooie/shared', 'xooie/keyboard_navigation'], function($, $X, helpers, shared, keyboardNavigation) {
+
+  var Widget;
+
+/**
+ * Xooie.Widget@xooie-init(event)
+ * - event (Event): A jQuery event object
+ *
+ * A jQuery special event triggered when the widget is successfully initialized.  Triggers on the `root` element
+ * of the widget.  This event will fire if bound after the widget is instantiated.
+ **/
+
+  $.event.special['xooie-init'] = {
+    add: function(handleObj) {
+      var id = $(this).data('xooieInstance');
+      if (typeof id !== 'undefined') {
+        var event = $.Event('xooie-init');
+        event.namespace = handleObj.namespace;
+        event.data = handleObj.data;
+
+        handleObj.handler.call(this, event);
+      }
+    }
+  };
+
+/**
+ * Xooie.Widget@xooie-refresh(event)
+ * - event (Event): A jQuery event object
+ *
+ * A jQuery special event triggered when the widget is refreshed.  Refresh events occur when the `root` element
+ * is passed to [[$X]].  Triggers on the `root` element of the widget.
+ **/
+
+/** internal
+ * Xooie.Widget.roleDetails(name) -> Object
+ *
+ * TODO: Test and document.
+ **/
+  function roleDetails (name) {
+    return {
+      processor: '_process_role_' + name,
+      renderer: '_render_role_' + name,
+      getter: '_get_role_' + name,
+      pluralName: name + 's',
+      selector: '[data-x-role=' + name + ']'
+    };
+  }
+
+/** internal
+ * Xooie.Widget.roleDispatcher(name, prototype)
+ *
+ * TODO: Test and document.
+ **/
+  function roleDispatcher(name, prototype) {
+    var role = roleDetails(name);
+
+    if (helpers.isUndefined(prototype[role.pluralName])) {
+      prototype._definedRoles.push(name);
+
+      prototype[role.pluralName] = function() {
+        return this[role.getter]();
+      };
+    }
+  }
+
+/** internal
+ * Xooie.Widget.cacheInstance(instance) -> Integer
+ * - instance (Widget): An instance of a Xooie widget to be cached
+ *
+ * Recursively checks for the next available index in [[$X._instanceCache]] using [[$X._instanceIndex]]
+ * as a reference point.  Returns the index.
+ **/
+  function cacheInstance (instance) {
+    if (typeof instance !== 'undefined') {
+      var index = $X._instanceIndex;
+
+      $X._instanceIndex += 1;
+
+      if (typeof $X._instanceCache[index] === 'undefined') {
+        $X._instanceCache[index] = instance;
+
+        return index;
+      } else {
+        return cacheInstance(instance);
+      }
+    }
+  }
+
+/**
+ * new Xooie.Widget(element[, addons])
+ * - element (Element | String): A jQuery-selected element or string selector for the root element of this widget
+ * - addons (Array): An optional collection of [[Xooie.Addon]] classes to be instantiated with this widget
+ *
+ * Instantiates a new Xooie widget, or returns an existing widget if it is already associated with the element passed.
+ * Any addons passed into the constructor will be instantiated and added to the [[Xooie.Widget#addons]] collection.
+ **/
+  Widget = function(element, addons) {
+    var self = this;
+
+    element = $(element);
+
+    //set the default options
+    this._setData(element.data());
+
+    //do instance tracking
+    if (element.data('xooieInstance')) {
+      if (typeof $X._instanceCache[element.data('xooieInstance')] !== 'undefined'){
+        element.trigger(this.get('refreshEvent'));
+        return $X._instanceCache[element.data('xooieInstance')];
+      } else {
+        this.cleanup();
+      }
+    }
+
+    element.on(this.get('initEvent') + ' ' + this.get('refreshEvent'), function(){
+      self._applyRoles();
+    });
+
+    var id = cacheInstance(this);
+
+    this.set('id', id);
+
+    this.set('root', element);
+
+    element.addClass(this.get('className'))
+           .addClass(this.get('instanceClass'));
+
+    var initCheck = function(){
+      var i;
+
+      if (!self._extendCount || self._extendCount <= 0) {
+
+        if (typeof addons !== 'undefined') {
+          for (i = 0; i < addons.length; i+=1) {
+            new addons[i](self);
+          }
+        }
+        
+        element.attr('data-xooie-instance', id);
+
+        element.trigger(self.get('initEvent'));
+        self._extendCount = null;
+      } else {
+        setTimeout(initCheck, 0);
+      }
+    };
+
+    if (this._extendCount > 0) {
+      setTimeout(initCheck, 0);
+    } else {
+      initCheck();
+    }
+
+    // new keyboardNavigation();
+  };
+
+/** internal
+ * Xooie.Widget._renderMethods -> Object
+ *
+ * A dispatch table of all supported template render methods.
+ *
+ * ##### Supported Frameworks
+ *
+ * - **mustache**: [http://mustache.github.io/]
+ * - **jsrender**: [https://github.com/BorisMoore/jsrender]
+ * - **underscore**: [http://underscorejs.org/]
+ **/
+  Widget._renderMethods = {
+    //TODO: make this a default template
+    'micro_template': function(template, view) {
+      if (typeof template.micro_render !== 'undefined') {
+        return $(template.micro_render(view));
+      } else {
+        return false;
+      }
+    },
+
+    'mustache': function(template, view) {
+      if (typeof Mustache !== 'undefined' && typeof Mustache.render !== 'undefined') {
+        return $(Mustache.render(template.html(), view));
+      } else {
+        return false;
+      }
+    },
+
+    'jsrender': function(template, view) {
+      if (typeof template.render !== 'undefined') {
+        return $(template.render(view));
+      } else {
+        return false;
+      }
+    },
+
+    'underscore': function(template, view) {
+      if (typeof _ !== 'undefined' && typeof _.template !== 'undefined') {
+        return $(_.template(template.html())(view).trim());
+      } else {
+        return false;
+      }
+    }
+  };
+
+//CLASS METHODS
+
+/**
+ * Xooie.Widget.defineWriteOnly(name)
+ * - name (String): The name of the property to define as a write-only property
+ *
+ * See [[Xooie.shared.defineWriteOnly]].
+ **/
+  Widget.defineWriteOnly = function(name) {
+    shared.defineWriteOnly(this, name);
+  };
+
+/**
+ * Xooie.Widget.defineReadOnly(name[, defaultValue])
+ * - name (String): The name of the property to define as a read-only property.
+ * - defaultValue (Object): An optional default value.
+ *
+ * See [[Xooie.shared.defineReadOnly]].
+ **/
+  Widget.defineReadOnly = function(name, defaultValue){
+    shared.defineReadOnly(this, name, defaultValue);
+  };
+
+/**
+ * Xooie.Widget.define(name[, defaultValue])
+ * - name (String): The name of the property to define.
+ * - defaultValue: An optional default value.
+ *
+ * A method that defines a property as both readable and writable.  In reality it calls both [[Xooie.Widget.defineReadOnly]]
+ * and [[Xooie.Widget.defineWriteOnly]].
+ **/
+  Widget.define = function(name, defaultValue){
+    this.defineReadOnly(name, defaultValue);
+    this.defineWriteOnly(name);
+  };
+
+/**
+ * Xooie.Widget.defineRole(name)
+ *
+ * TODO: This needs tests and documentation
+ **/
+  Widget.defineRole = function(name) {
+    var role = roleDetails(name);
+
+    roleDispatcher(name, this.prototype);
+
+    if (!helpers.isFunction(this.prototype[role.getter])) {
+      this.prototype[role.getter] = function() {
+        return this.root().find(role.selector);
+      };
+    }
+  };
+
+/**
+ * Xooie.Widget.extend(constr) -> Widget
+ * - constr (Function): The constructor for the new [[Xooie.Widget]] class.
+ *
+ * See [[Xooie.shared.extend]].
+ **/
+  Widget.extend = function(constr){
+    return shared.extend(constr, this);
+  };
+
+/**
+ * Xooie.Widget.createStyleRule(selector, properties) -> cssRule | undefined
+ * - selector (String): The selector used to identify the rule.
+ * - properties (Object): A hash of key/value pairs of css properties and values.
+ *
+ * Creates a new css rule in the Xooie stylesheet.  If the rule exists, it will overwrite said rule.
+ **/
+ // TODO: update so that if the rule exists the properties are added to the rule
+  Widget.createStyleRule = function(selector, properties) {
+    if (typeof $X._stylesheet.addRule !== 'undefined') {
+      return $X._stylesheet.addRule(selector, properties);
+    }
+  };
+
+/**
+ * Xooie.Widget.getStyleRule(selector) -> cssRule | undefined
+ * - selector (String): The selector used to identify the rule.
+ *
+ * Retrieves the css rule from the Xooie stylesheet using the provided `selector`.  If the rule is not
+ * present in [[$X._styleRules]] then the method will check in [[$X._stylesheet]].
+ **/
+  Widget.getStyleRule = function(selector) {
+    if ($X._styleRules.hasOwnProperty(selector)) {
+      return $X._styleRules[selector];
+    } else {
+      return $X._stylesheet.getRule(selector);
+    }
+  };
+
+/** internal
+ * Xooie.Widget#_definedProps -> Array
+ *
+ * A collection of properties that have been defined for this class instance.
+ **/
+  Widget.prototype._definedProps = [];
+
+/** internal
+ * Xooie.Widget#_definedRoles -> Array
+ *
+ * A collection of roles that have been defined for this class instance.
+ **/
+  Widget.prototype._definedRoles = [];
+
+/** internal, read-only
+ * Xooie.Widget#_extendCount -> Integer | null
+ *
+ * Tracks the number of constructors that need to be called.
+ **/
+  Widget.prototype._extendCount = null;
+
+//PROPERTY DEFINITIONS
+
+/** internal
+ * Xooie.Widget#_id -> Integer
+ *
+ * The id of this widget.  This value is used to keep track of the instance.
+ **/
+/**
+ * Xooie.Widget#id([value]) -> Integer
+ * - value: an optional value to be set.
+ *
+ * The method for setting or getting [[Xooie.Widget#_id]].  Returns the current value of
+ * [[Xooie.Widget#_id]] if no value is passed or sets the value.
+ **/
+  Widget.define('id');
+
+/** internal
+ * Xooie.Widget#_root -> Element
+ *
+ * The root DOM element associated with this widget.  This is a jQuery-selected element.
+ **/
+/**
+ * Xooie.Widget#root([value]) -> Element
+ * - value: an optional value to be set.
+ *
+ * The method for setting or getting [[Xooie.Widget#_root]].  Returns the current value of
+ * [[Xooie.Widget#_root]] if no value is passed or sets the value.
+ **/
+  Widget.define('root');
+
+/** internal
+ * Xooie.Widget#_namespace -> String
+ *
+ * The namespace of the widget.  This value is used for determining the value of [[Xooie.Widget#className]],
+ * [[Xooie.Widget#refreshEvent]], [[Xooie.Widget#initEvent]], and [[Xooie.Widget#instanceClass]].
+ **/
+/**
+ * Xooie.Widget#namespace([value]) -> String
+ * - value: an optional value to be set.
+ *
+ * The method for setting or getting [[Xooie.Widget#_namespace]].  Returns the current value of
+ * [[Xooie.Widget#_namespace]] if no value is passed or sets the value.
+ **/
+  Widget.define('namespace', '');
+
+/** internal
+ * Xooie.Widget#_templateLanguage -> String
+ *
+ * Determines the template framework to use.
+ * Default: `micro_template`.
+ **/
+/**
+ * Xooie.Widget#templateLanguage([value]) -> String
+ * - value: an optional value to be set.
+ *
+ * The method for setting or getting [[Xooie.Widget#_templateLanguage]].  Returns the current value of
+ * [[Xooie.Widget#_templateLanguage]] if no value is passed or sets the value.
+ **/
+  Widget.define('templateLanguage', 'micro_template');
+
+/** internal, read-only
+ * Xooie.Widget#_addons -> Object
+ *
+ * A collection of addons instantiated addons associated with this widget.
+ * Default: `{}`.
+ **/
+/** read-only
+ * Xooie.Widget#addons([value]) -> Object
+ * - value: an optional value to be set.
+ *
+ * The method for setting or getting [[Xooie.Widget#_addons]].  Returns the current value of
+ * [[Xooie.Widget#_addons]] if no value is passed or sets the value.
+ **/
+  Widget.defineReadOnly('addons');
+
+/** internal, read-only
+ * Xooie.Widget#_refreshEvent -> String
+ *
+ * The name of the event that is triggered when the module is refreshed.  Refresh events are triggered
+ * when the root element of this widget is passed to [[$X]].
+ * Default: `xooie-refresh`.
+ **/
+/** read-only
+ * Xooie.Widget#refreshEvent() -> String
+ *
+ * The method for getting [[Xooie.Widget#_refreshEvent]].
+ **/
+  Widget.defineReadOnly('refreshEvent', 'xooie-refresh');
+
+/** internal, read-only
+ * Xooie.Widget#_initEvent -> String
+ *
+ * The name of the event that is triggered when the module is initialized.  The initialization event
+ * is not triggered until all addons have been instantiated.
+ * Default: `xooie-init`.
+ **/
+/** read-only
+ * Xooie.Widget#initEvent() -> String
+ *
+ * The method for getting [[Xooie.Widget#_initEvent]].
+ **/
+  Widget.defineReadOnly('initEvent', 'xooie-init');
+
+/** internal, read-only
+ * Xooie.Widget#_className -> String
+ *
+ * The string class name that is applied to the root element of this widget when it is instantiated.
+ * Default: `is-instantiated`.
+ **/
+/** read-only
+ * Xooie.Widget#className() -> String
+ *
+ * The method for getting [[Xooie.Widget#_className]].
+ **/
+  Widget.defineReadOnly('className', 'is-instantiated');
+
+/** internal, read-only
+ * Xooie.Widget#_instanceClass -> String
+ *
+ * A class that is generated and applied to the root element of the widget.
+ * Default: `{{namespace}}-{{id}}`
+ **/
+/** read-only
+ * Xooie.Widget#instanceClass() -> String
+ *
+ * The method for getting [[Xooie.Widget#_instanceClass]].
+ **/
+  Widget.defineReadOnly('instanceClass');
+
+
+//PROTOTYPE DEFINITIONS
+
+/** internal
+ * Xooie.widget#_setData(data)
+ * - data (Object): A collection of key/value pairs.
+ *
+ * Sets the properties to the values specified, as long as the property has been defined.
+ **/
+  Widget.prototype._setData = function(data) {
+    var i;
+
+    for (i = 0; i < this._definedProps.length; i+=1) {
+      if (typeof data[this._definedProps[i]] !== 'undefined') {
+        this.set(this._definedProps[i], data[this._definedProps[i]]);
+      }
+    }
+  };
+
+/**
+ * Xooie.Widget#get(name) -> object
+ * - name (String): The name of the property to be retrieved.
+ *
+ * See [[Xooie.shared.get]].
+ **/
+  Widget.prototype.get = function(name) {
+    return shared.get(this, name);
+  };
+
+/**
+ * Xooie.Widget#set(name, value)
+ * - name (String): The name of the property to be set.
+ * - value: The value of the property to be set.
+ *
+ * See [[Xooie.shared.set]].
+ **/
+  Widget.prototype.set = function(name, value) {
+    return shared.set(this, name, value);
+  };
+
+/**
+ * Xooie.Widget#cleanup()
+ *
+ * Removes the `className` and `instanceClass` classes and `data-xooie-instance` attribute from the root element.
+ * Calls [[Xooie.Addon.cleanup]] for each addon.  This will permit the instance to be garbage collected.
+ **/
+  Widget.prototype.cleanup = function() {
+    var name;
+
+    for (name in this.addons()) {
+      if (this.addons().hasOwnProperty(name)) {
+        this.addons()[name].cleanup();
+      }
+    }
+
+    this.root().removeClass(this.className());
+    this.root().removeClass(this.instanceClass());
+    this.root().attr('data-xooie-instance', false);
+  };
+
+/**
+ * Xooie.Widget#render(template, view) -> Element
+ * - template (Element): A jQuery-selected script element that contains the template to be rendered.
+ * - view (Object): The data to be passed to the template when it is rendered.
+ *
+ * Renders the template with the provided data by calling the method in [[Xooie.Widget.renderMethods]] based on the
+ * template language specified.  Returns `$('<span>Error rendering template</span>')` when an error occurs
+ **/
+  Widget.prototype.render = function(template, view) {
+    var language = template.data('templateLanguage') || this.templateLanguage(),
+      result = Widget._renderMethods[language](template, view);
+
+    if (result === false) {
+      return $('<span>Error rendering template</span>');
+    } else {
+      return result;
+    }
+  };
+
+/** internal
+ * Xooie.Widget#_getRoleId(role, index) -> String
+ * - role (String): The name of the role for which this id is being generated.
+ * - index (Integer): The index at which the particular element exists in the read order.
+ *
+ * Generates an id string to be applied to an element of the specified role.  The format of
+ * this id string is `x-[[Xooie.Widget#id]]-{role}-{index}`.
+ **/
+  Widget.prototype._getRoleId = function(role, index) {
+    return 'x-' + this.id() + '-' + role + '-' + index;
+  };
+
+/** internal
+ * Xooie.Widget#_applyRoles()
+ *
+ * TODO: Test and document.
+ **/
+  Widget.prototype._applyRoles = function() {
+    var i, j, role, elements;
+
+    for (i=0; i < this._definedRoles.length; i+=1) {
+      role = roleDetails(this._definedRoles[i]);
+      elements = this[role.getter]();
+      
+      if (elements.length === 0 && helpers.isFunction(this[role.renderer])) {
+        elements = this[role.renderer]();
+      }
+
+      if (helpers.isUndefined(elements)) {
+        return;
+      }
+
+      for (j=0; j < elements.length; j+=1) {
+        $(elements[j]).attr('id', this._getRoleId(this._definedRoles[i], j));
+      }
+
+      if (helpers.isFunction(this[role.processor])) {
+        this[role.processor](elements);
+      }
+    }
+  };
+
+/** internal
+ * Xooie.Widget#_process_addons(addons) -> Object
+ * - addons (Object): The collection of instantiated addons for this widget
+ *
+ * Checks to see if the addons object has been defined.  We can't define objects as
+ * 'default' values for properties since the object will be the same for each instance.
+ **/
+  Widget.prototype._process_addons = function(addons){
+    if (typeof addons === 'undefined'){
+      addons = this._addons = {};
+    }
+
+    return addons;
+  };
+
+/** internal
+ * Xooie.Widget#_process_refreshEvent(refreshEvent) -> String
+ * - refreshEvent (String): The unmodified refreshEvent string.
+ *
+ * Adds the [[Xooie.Widget#namespace]] to the `refreshEvent`
+ **/
+  Widget.prototype._process_refreshEvent = function(refreshEvent){
+    return this.namespace() === '' ? refreshEvent : refreshEvent + '.' + this.namespace();
+  };
+
+/** internal
+ * Xooie.Widget#_process_initEvent(initEvent) -> String
+ * - initEvent (String): The unmodified initEvent string.
+ *
+ * Adds the [[Xooie.Widget#namespace]] to the `initEvent`
+ **/
+  Widget.prototype._process_initEvent = function(initEvent){
+    return this.namespace() === '' ? initEvent : initEvent + '.' + this.namespace();
+  };
+
+/** internal
+ * Xooie.Widget#_process_className(className) -> String
+ * - className (String): The unmodified className string.
+ *
+ * Adds the [[Xooie.Widget#namespace]] to the `className`
+ **/
+  Widget.prototype._process_className = function(className) {
+    return this.namespace() === '' ? className : className + '-' + this.namespace();
+  };
+
+/** internal
+ * Xooie.Widget#_process_instanceClass() -> String
+ *
+ * Creates an instanceClass string from the [[Xooie.Widget#namespace]] and [[Xooie.Widget#id]].
+ **/
+  Widget.prototype._process_instanceClass = function() {
+    return this.namespace() === '' ? 'widget-' + this.id() : this.namespace() + '-' + this.id();
+  };
+
+  return Widget;
+});