xooie 0.0.17.pre → 0.1.0

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

@@ -0,0 +1,355 @@
+/*
+*   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.Tab < Xooie.Widget
+ *
+ * A widget that associates containers of information with "tabs".  The pattern is
+ * designed to mimic the real-world concept of a filing cabinet, where content is
+ * stored in folders with protruding tabs that label said content.
+ *
+ * The Tab widget should be used as a way to organize how content is displayed
+ * visually.  Content is hidden until the associated tab is activated.
+ **/
+define('xooie/widgets/tab', ['jquery', 'xooie/helpers', 'xooie/widgets/base', 'xooie/event_handler'], function($, helpers, Base, EventHandler) {
+
+  function setSelection(widget, selectedTabs) {
+    var activeTabs = widget.getActiveTabs();
+
+    activeTabs.not(selectedTabs).each(function() {
+      widget.deactivateTab($(this));
+    });
+
+    selectedTabs.not(activeTabs).each(function() {
+      widget.activateTab($(this));
+    });
+  }
+/**
+ * Xooie.Tab@xooie-tab-active(event)
+ * - event (Event): A jQuery event object
+ *
+ * An event that is fired when a tab is activated.  Triggers on the `root` element of the widget.
+ *
+ * ##### Event Properties
+ * - **tabId** (String): The id of the tab that was activated.
+ **/
+
+ /**
+ * Xooie.Tab@xooie-tab-inactive(event)
+ * - event (Event): A jQuery event object
+ *
+ * An event that is fired when a tab is deactivated.  Triggers on the `root` element of the widget.
+ *
+ * ##### Event Properties
+ * - **tabId** (String): The id of the tab that was deactivated.
+ **/
+
+/**
+ * new Xooie.Tab(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 Tab instance.  See [[Xooie.Widget]] for more functionality.
+ **/
+  var Tab = Base.extend(function(){
+    var self = this;
+
+    this._tabEvents = new EventHandler(this.namespace());
+
+    this._tabEvents.add({
+      keyup: function(event){
+        if ([13,32].indexOf(event.which) !== -1){
+          setSelection(self, self.selectTabs(event, $(this)));
+
+          event.preventDefault();
+        }
+      },
+
+      mouseup: function(event){
+        setSelection(self, self.selectTabs(event, $(this)));
+      },
+
+      click: function(event){
+        event.preventDefault();
+      }
+    });
+
+    // TODO: Test and document this.  Also, create a property for data-activate
+    this.root().on(this.initEvent(), function(){
+      self.activateTab(self.tabs().filter('[data-activate="true"]'));
+    });
+
+  });
+
+/** internal
+ * Xooie.Tab#_namespace -> String
+ *
+ * See [[Xooie.Widget#_namespace]].
+ * Default: `tab`.
+ **/
+/**
+ * Xooie.Tab#namespace([value]) -> String
+ * - value: an optional value to be set.
+ *
+ * See [[Xooie.Widget#namespace]]
+ **/
+  Tab.define('namespace', 'tab');
+
+/** internal
+ * Xooie.Tab#_tabSelector -> String
+ *
+ * An alternative selector for a [[Xooie.Tab#tabs]]. This allows developers to specify a tab control that may not
+ * be a child of the tab widget.
+ **/
+/**
+ * Xooie.Tab#tabSelector([value]) -> String
+ * - value: an optional value to be set.
+ *
+ * The method for setting or getting [[Xooie.Tab#_tabSelector]].  Returns the current value of
+ * [[Xooie.Tab#_tabSelector]] if no value is passed or sets the value.
+ **/
+  Tab.define('tabSelector');
+
+/** internal
+ * Xooie.Tab#_activeClass -> String
+ *
+ * A class string that is applied to active [[Xooie.Tab#tabs]] and [[Xooie.Tab#tabpanels]].
+ * Default: `is-tab-active`.
+ **/
+/**
+ * Xooie.Tab#activeClass([value]) -> String
+ * - value: an optional value to be set.
+ *
+ * The method for setting or getting [[Xooie.Tab#_activeClass]].  Returns the current value of
+ * [[Xooie.Tab#_activeClass]] if no value is passed or sets the value.
+ **/
+  Tab.defineReadOnly('activeClass', 'is-tab-active');
+
+/**
+ * Xooie.Tab#tabpanels() -> Elements
+ *
+ * Tabpanels are elements that contain the content that is shown or hidden when the corresponding
+ * [[Xooie.Tab#tabs]] is activated.
+ * This role maps to the ARIA [tab role](http://www.w3.org/TR/wai-aria/roles#tab)
+ **/
+  Tab.defineRole('tabpanel');
+
+/**
+ * Xooie.Tab#tabs() -> Elements
+ *
+ * Tabs are elements that, when activated, also activate the corresponding [[Xooie.Tab#tabpanels]].
+ * This role maps to the ARIA [tabpanel role](http://www.w3.org/TR/wai-aria/roles#tabpanel).
+ **/
+  Tab.defineRole('tab');
+
+/**
+ * Xooie.Tab#tablists() -> Elements
+ *
+ * A tablist is an element that contains all the [[Xooie.Tab#tabs]].  If any tabs are not decendants of
+ * the tablist, ownership of the tab is indicated using the `aria-owns` attribute.
+ * There should only be one tablist per tab widget.
+ * This role maps to the ARIA [tablist role](http://www.w3.org/TR/wai-aria/roles#tablist)
+ **/
+  Tab.defineRole('tablist');
+
+/**
+ * Xooie.Tab#activateTab(tab)
+ * - tab (Element): One of the [[Xooie.Tab#tabs]] associated with this widget.
+ *
+ * Activates the [[Xooie.Tab#tabs]] by adding the [[Xooie.Tab#activeClass]] class and setting the `aria-expanded` property to 'true'.
+ * The method also activates the [[Xooie.Tab#tabpanels]] that is indicated by the tab's `aria-controls` attribute,
+ * adding the [[Xooie.Tab#activeClass]] class and setting `aria-expanded` to 'true'.
+ **/
+  Tab.prototype.activateTab = function(tab) {
+    tab.addClass(this.activeClass())
+       .attr('aria-selected', true);
+
+    $('#' + tab.attr('aria-controls')).addClass(this.activeClass())
+                                      .attr('aria-expanded', true)
+                                      .focus();
+
+    var e = $.Event('xooie-tab-active');
+
+    e.tabId = tab.attr('id');
+
+    this.root().trigger(e);
+  };
+
+/**
+ * Xooie.Tab#deactivateTab(tab)
+ * - tab (Element): One of the [[Xooie.Tab#tabs]] associated with this widget.
+ *
+ * Deactivates the [[Xooie.Tab#tabs]] by removing the [[Xooie.Tab#activeClass]] class and setting the `aria-expanded` property to 'false'.
+ * The method also deactivates the [[Xooie.Tab#tabpanels]] that is indicated by the tab's `aria-controls` attribute,
+ * removing the [[Xooie.Tab#activeClass]] class and setting `aria-expanded` to 'false'.
+ **/
+  Tab.prototype.deactivateTab = function(tab) {
+    tab.removeClass(this.activeClass())
+       .attr('aria-selected', false);
+
+    $('#' + tab.attr('aria-controls')).removeClass(this.activeClass())
+                                      .attr('aria-expanded', false);
+
+    var e = $.Event('xooie-tab-inactive');
+
+    e.tabId = tab.attr('id');
+
+    this.root().trigger(e);
+  };
+
+/**
+ * Xooie.Tab#selectTabs(event, selectedTab)
+ * - event (Event): Browser event that triggered selectTabs call
+ * - selectedTab (Element): Tab that was selected by a mouse or keyboard event
+ *
+ * Only called by mouse/keyboard event handlers to generate the list of
+ * currently active tabs. Should return a jQuery collection of tabs that are
+ * to be active. Any tabs which are currently active and not in the
+ * collection will be deactivated, and likewise any tabs not currently active
+ * and in the collection will be activated.
+ *
+ * Override this method to alter the behavior of the Tab widget.
+ **/
+  Tab.prototype.selectTabs = function(event, selectedTab) {
+    return selectedTab;
+  };
+
+/**
+ * Xooie.Tab#getActiveTabs() -> Elements
+ *
+ * Returns a jQuery-selected collection of all [[Xooie.Tab#tabs]] that currently have the
+ * [[Xooie.Tab#activeClass]] class.
+ **/
+  Tab.prototype.getActiveTabs = function() {
+    return this.tabs().filter('.' + this.activeClass());
+  };
+
+/** internal
+ * Xooie.Tab#_process_role_tab(tabs) -> Element
+ * - tabs (Element): A jQuery-selected collection of [[Xooie.Tab#tabs]]
+ *
+ * This method processes the elements that have been designated as [[Xooie.Tab#tabs]] with
+ * the `data-x-role="tab"` attribute.  Tabs are given the [`role="tab"`](http://www.w3.org/TR/wai-aria/roles#tab) and [`aria-selected="false"`](http://www.w3.org/TR/wai-aria/states_and_properties#aria-selected)
+ * [ARIA](http://www.w3.org/TR/wai-aria/) attributes.
+ **/
+  Tab.prototype._process_role_tab = function(tabs){
+    var tabpanels = this.tabpanels(),
+        tab, panelId,
+        self = this;
+
+    tabs.attr('role', 'tab')
+        .attr('aria-selected', false);
+
+    tabs.each(function(index) {
+      tab = $(this);
+      panelId = tabpanels.eq(index).attr('id');
+
+      $(this).attr('aria-controls', panelId);
+
+      if ($(this).is('a')) {
+        $(this).attr('href', '#' + panelId);
+      }
+
+    });
+
+    tabs.on(this._tabEvents.handlers);
+    
+    return tabs;
+  };
+
+/** internal
+ * Xooie.Tab#_get_role_tab() -> Element
+ *
+ * Internal method used to retrieve the [[Xooie.Tab#tabs]] for this widget.  If [[Xooie.Tab#tabSelector]] has been
+ * defined then its value will be used to select from the DOM.  Otherwise, tabs will be selected from decendants of
+ * the root using the `[data-x-role="tab"]` selector.
+ **/
+  Tab.prototype._get_role_tab = function(){
+    if (!helpers.isUndefined(this.tabSelector())) {
+      return $(this.tabSelector());
+    } else {
+      return this.root().find('[data-x-role="tab"]');
+    }
+  };
+
+/** internal
+ * Xooie.Tab#_render_role_tab() -> Elements
+ *
+ * TODO: Create this method to keep parity with the existing tab functionality
+ **/
+  Tab.prototype._render_role_tab = function(){
+
+  };
+
+/** internal
+ * Xooie.Tab#_process_role_tablist(tablist) -> Element
+ * - tablist (Element): A jQuery-selected collection of [[Xooie.Tab#tablists]]
+ *
+ * This method processes the elements that have been designated as [[Xooie.Tab#tablists]] with
+ * the `data-x-role="tablist"` attribute.  The tablist is given the [`role="tablist"`](http://www.w3.org/TR/wai-aria/roles#tablist)
+ * [ARIA](http://www.w3.org/TR/wai-aria/) attributes.  If any [[Xooie.Tab#tabs]] are not decendants of the tab list, the ids of those
+ * tabs are added to the [`aria-owns`](http://www.w3.org/TR/wai-aria/states_and_properties#aria-owns) attribute.
+ **/
+  Tab.prototype._process_role_tablist = function(tablist) {
+    var tabs = this.tabs();
+
+    tablist.attr('role', 'tablist');
+
+    tabs.each(function(index) {
+      var owns, id;
+      if (tablist.has(this).length === 0) {
+        owns = tablist.attr('aria-owns') || '';
+
+        owns = owns.split(' ');
+
+        id = $(this).attr('id');
+
+        if (owns.indexOf(id) === -1) {
+          owns.push(id);
+        }
+
+        tablist.attr('aria-owns', owns.join(' '));
+      }
+    });
+
+    return tablist;
+  };
+/** internal
+ * Xooie.Tab#_render_role_tablist() -> Element
+ *
+ * TODO: Add this method to render the tablist if it is not included.
+ **/
+  Tab.prototype._render_role_tablist = function(){
+    return $('<ul data-x-role="tablist"></ul>');
+  };
+
+/** internal
+ * Xooie.Tab#_process_role_tabpanel(tabpanels) -> Element
+ * - tabpanels (Element): A jQuery-selected collection of [[Xooie.Tab#tabpanels]]
+ *
+ * This method processes the elements that have been designated as [[Xooie.Tab#tabpanels]] with
+ * the `data-x-role="tabpanel"` attribute.  Tabs are given the [`role="tabpanel"`](http://www.w3.org/TR/wai-aria/roles#tab) and [`aria-expanded="false"`](http://www.w3.org/TR/wai-aria/states_and_properties#aria-selected)
+ * [ARIA](http://www.w3.org/TR/wai-aria/) attributes.
+ **/
+  Tab.prototype._process_role_tabpanel = function(tabpanels) {
+    tabpanels.attr('role', 'tabpanel')
+             .attr('aria-expanded', false);
+
+    return tabpanels;
+  };
+
+  return Tab;
+});

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

@@ -0,0 +1,282 @@
+/*
+*   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.
+*/
+
+var $X, Xooie;
+
+/** alias of: $X
+ *  Xooie
+ *
+ *  Xooie is a JavaScript UI widget library.
+ **/
+
+/**
+ * $X(element)
+ * - element (Element | String):  A jQuery collection or string representing the DOM element to be
+ * instantiated as a Xooie widget.
+ *
+ * Traverses the DOM, starting from the element passed to the method, and instantiates a Xooie
+ * widget for every element that has a data-widget-type attribute.
+ **/
+
+$X = Xooie = (function(static_config) {
+    var config = {
+            widgets: {},
+            addons: {}
+        },
+        obj = function() {
+            return false;
+        },
+        gcTimer = null;
+
+    function copyObj(dst, src) {
+        var name;
+
+        for (name in src) {
+            if (src.hasOwnProperty(name)) {
+                dst[name] = src[name];
+            }
+        }
+    }
+
+    function gcCallback() {
+        if (typeof Xooie.cleanup !== 'undefined') {
+            Xooie.cleanup();
+        }
+    }
+
+/**
+ * $X.config(options)
+ * - options (Object): An object that describes the configuration options for Xooie.
+ *
+ * Defines the url strings for Xooie modules that will be used to require said modules.
+ *
+ * ##### Options
+ *
+ * - **root** (String): The location of all Xooie files.
+ * Default: `xooie`.
+ * - **widgets** (Object): Defines the location of widgets.  By default, Xooie will look for widgets in the
+ * '/widgets' directory, relative to the `{root}`.
+ * - **addons** (Object): Defines the location of addons.  By default, Xooie will look for addons in the
+ * '/addons' directory, relative to the `{root}`.
+ * - **cleanupInterval** (Integer): Defines the interval at which Xooie checks for instantiated widgets that are
+ * no longer active in the DOM.  A value of '0' means no cleanup occurs.
+ * Default: `0`.
+ **/
+
+    obj.config = function(options) {
+        var name;
+
+        for (name in options) {
+            if (options.hasOwnProperty(name)) {
+                if (name === 'widgets' || name == 'addons') {
+                    copyObj(config[name], options[name]);
+                } else {
+                    config[name] = options[name];
+                }
+            }
+        }
+
+        if (typeof options.cleanupInterval !== 'undefined') {
+            gcTimer = clearInterval(gcTimer);
+
+            if (config.cleanupInterval > 0) {
+                gcTimer = setInterval(gcCallback, config.cleanupInterval);
+            }
+        }
+    };
+
+/** internal
+ * $X._mapName(name, type) -> String
+ * - name (String): The name of the module, as determeined by the `data-widget-type` or `data-addons` properties.
+ * - type (String): The type of module.  Can be either `'widget'` or `'addon'`
+ *
+ * Maps the name of the widget or addon to the correct url string where the module file is located.
+ **/
+
+    obj._mapName = function(name, type) {
+        if (typeof config[type][name] === 'undefined') {
+            return [config.root, '/', type, '/', name].join('');
+        } else {
+            return config[type][name];
+        }
+    };
+
+    obj.config({
+        root: 'xooie',
+        cleanupInterval: 0
+    });
+
+    if (static_config) {
+        obj.config(static_config);
+    }
+
+    return obj;
+}(Xooie));
+
+define('xooie/xooie', ['jquery', 'xooie/helpers', 'xooie/stylesheet'], function($, helpers, Stylesheet){
+    var config = Xooie.config,
+        _mapName = Xooie._mapName,
+        widgetSelector = '[data-widget-type]';
+        widgetDataAttr = 'widgetType';
+        addonDataAttr = 'addons';
+
+    $X = Xooie = function(element){
+        var nodes, moduleNames, moduleUrls,
+            node, url,
+            i, j;
+
+        element = $(element);
+
+        // Find all elements labeled as widgets:
+        nodes = element.find(widgetSelector);
+
+        // If the element is also tagged, add it to the collection:
+        if (element.is(widgetSelector)){
+            nodes = nodes.add(element);
+        }
+
+        // This array will be the list of unique modules to load:
+        moduleUrls = [];
+
+        // Iterate through each item in the collection:
+        for(i = 0; i < nodes.length; i+=1) {
+            node = $(nodes[i]);
+
+            // Add all of the widget types to the list of modules we need:
+            moduleNames = helpers.toAry(node.data(widgetDataAttr));
+
+            // For each widget we check to see if the url is already in our
+            // list of urls to require:
+            for (j = 0; j < moduleNames.length; j+=1) {
+                url = $X._mapName(moduleNames[j], 'widgets');
+
+                if (moduleUrls.indexOf(url) === -1) {
+                    moduleUrls.push(url);
+                }
+            }
+
+            // Do the same with each addon name:
+            moduleNames = helpers.toAry(node.data(addonDataAttr)) || [];
+
+            for (j = 0; j < moduleNames.length; j+=1) {
+                url = $X._mapName(moduleNames[j], 'addons');
+
+                if (moduleUrls.indexOf(url) === -1) {
+                    moduleUrls.push(url);
+                }
+            }
+        }
+
+        // Now that we have a list of urls to load, let's load them:
+        require(moduleUrls, function(){
+            var widgets, addons, node,
+                addonMods, widgetMod, argIndex,
+                i, j, k;
+
+            // We need to iterate through our collection of nodes again:
+            for (i = 0; i < nodes.length; i+=1) {
+                node = $(nodes[i]);
+
+                // This time, we're keeping track of our addons and widges separately:
+                widgets = helpers.toAry(node.data(widgetDataAttr));
+                addons = helpers.toAry(node.data(addonDataAttr)) || [];
+
+                // Iterate through each widget type:
+                for (j = 0; j < widgets.length; j+=1) {
+
+                    // Get the index of this module from the moduleUrls:
+                    argIndex = moduleUrls.indexOf($X._mapName(widgets[j], 'widgets'));
+
+                    //Get the widget that we'll be instantiating:
+                    widgetMod = arguments[argIndex];
+
+                    addonMods = [];
+
+                    // Now get each addon that we'll instantiate with the widget:
+                    for (k = 0; k < addons.length; k+=1) {
+                        // Get the index of the addon module from moduleUrls:
+                        argIndex = moduleUrls.indexOf($X._mapName(addons[k], 'addons'));
+
+                        addonMods.push(arguments[argIndex]);
+                    }
+
+                    // Instantiate the new instance using the argIndex to find the right module:
+                    new widgetMod(node, addonMods);
+                }
+            }
+        });
+    };
+
+    Xooie.config = config;
+    Xooie._mapName = _mapName;
+
+/** internal, read-only
+ * $X._stylesheet -> Object
+ *
+ * An instance of the [[Stylesheet]] class used to manipluate a dynamically created Xooie stylesheet
+ **/
+    Xooie._stylesheet = new Stylesheet('Xooie');
+
+/** internal
+ * $X._styleRules -> Object
+ *
+ * A cache of css rules defined by the [[Xooie.Widget.createStyleRule]] method.
+ **/
+    Xooie._styleRules = {};
+
+/** internal
+ * $X._instanceCache -> Array
+ *
+ * A collection of currently instantiated widgets.
+ **/
+    Xooie._instanceCache = [];
+
+/** internal
+ * $X._instanceIndex -> Integer
+ *
+ * Tracks the next available instance index in the cache.  This value also serves as the id of the
+ * next instantiated widget.
+ **/
+    Xooie._instanceIndex = 0;
+    
+/**
+ * $X.cleanup()
+ *
+ * Checks all instantiated widgets to ensure that the root element is still in the DOM.  If the
+ * root element is no longer in the DOM, the module is garbage collected.
+ **/
+
+    Xooie.cleanup = function() {
+        var i, instance;
+
+        for (i = 0; i < $X._instanceCache.length; i++) {
+            instance = $X._instanceCache[i];
+
+            if (instance.root() && instance.root().parents('body').length === 0) {
+                instance.cleanup();
+                delete $X._instanceCache[i];
+            }
+        }
+    };
+
+    return Xooie;
+});
+
+require(['jquery', 'xooie/xooie'], function($, $X){
+    $(document).ready(function() {
+        $X($(this));
+    });
+});