refactor alerts + add new readme which idefientifies goals for 2.0 js

6 files changed, 163 insertions, 41 deletions

diff --git a/js/README.md b/js/README.md
new file mode 100644
index 0000000000..98be75421d
--- /dev/null
+++ b/js/README.md
@@ -0,0 +1,89 @@
+2.0 BOOTSTRAP JS PHILSOPHY
+These are the highlevel design rules which guide the developement of Bootstrap's js plugins.
+
+---
+
+### DATA-ATTRIBUTE API
+
+We believe you should be able to use all plugins provided by bootstrap purely through the markup api without writing a single line of javascript.
+
+We acknoledge that this isn't always the most performant and sometimes it may be desirable to turn this functionality off altogether. Therefore, as of 2.0 we provide the ability to disable the data attribute api by unbinding all events on the body namespaced with `'data-api'`. This looks like this:
+
+    $('body').unbind('.data-api')
+
+To target a specific plugin, just include the plugins name as a namespace along with the data-api namespace like this:
+
+    $('body').unbind('.alert.data-api')
+
+---
+
+### PROGRAMATIC API
+
+We also believe you should be able to use all plugins provided by bootstrap purely through the JS api.
+
+All pubilc APIs should be a single, chainable method, and return the collection acted upon.
+
+    $(".btn.danger").button("toggle").addClass("fat")
+
+All methods should accept an optional options object, a string which targets a particular method, or null which innitiates the default behavior:
+
+    $("#myModal").modal() // initialized with defaults
+
+---
+
+### PLUGIN OPTIONS
+
+Options should be sparse and add universal value. We should pick the right defaults.
+
+All plugins should have a default object which can be modified to effect all instance's default options. The defaults object should be available via `$.fn.plugin.defaults`.
+
+    $.fn.modal.defaults = { … }
+
+An options definiton should take the following form:
+
+    *noun*: *adjective* - describes or modifies a quality of an instance
+
+examples:
+
+    backdrop: true
+    keyboard: false
+    placement: 'above'
+
+---
+
+### PLUGIN EVENTS
+
+All events should have an infinitive and past participle form. The infinitive is fired just before an action takes place, the past participle on completion of the action.
+
+    show | shown
+    hide | hidden
+    change | changed
+
+---
+
+
+### DATA ATTRIBUTES
+
+Data attributes should take the following form:
+
+data-*(verb)* - defines main interaction
+data-target - defined on controller element (if element interacts with an element other than self)
+data-*(noun)* - defines options for element invocation
+
+examples:
+
+    // control other targets
+    data-toggle="modal" data-target="#foo"
+    data-toggle="view" data-target="#foo"
+
+    // defined on element they control
+    data-spy="scroll"
+
+    data-dismiss="modal"
+    data-dismiss="alert"
+
+    data-toggle="dropdown"
+
+    data-toggle="button"
+    data-toggle="buttons-checkbox"
+    data-toggle="buttons-radio"
\ No newline at end of file
diff --git a/js/bootstrap-alerts.js b/js/bootstrap-alerts.js
index 600440e40e..565f831936 100644
--- a/js/bootstrap-alerts.js
+++ b/js/bootstrap-alerts.js
@@ -25,25 +25,22 @@
  /* ALERT CLASS DEFINITION
   * ====================== */
 
-  var Alert = function ( content, options ) {
-    if (options == 'close') return this.close.call(content)
-    this.settings = $.extend({}, $.fn.alert.defaults, options)
-    this.$element = $(content)
-      .delegate(this.settings.selector, 'click', this.close)
-  }
+  var dismiss = '[data-dismiss="alert"]'
+    , Alert = function ( el, close ) {
+        $(el).delegate(dismiss, 'click', this.close)
+      }
 
   Alert.prototype = {
 
-    close: function (e) {
+    close: function ( e ) {
       var $element = $(this)
-        , className = 'alert-message'
 
-      $element = $element.hasClass(className) ? $element : $element.parent()
+      $element = $element.hasClass('alert-message') ? $element : $element.parent()
 
       e && e.preventDefault()
       $element.removeClass('in')
 
-      function removeElement () {
+      function removeElement() {
         $element.remove()
       }
 
@@ -59,32 +56,22 @@
   * ======================= */
 
   $.fn.alert = function ( options ) {
-
     return this.each(function () {
       var $this = $(this)
-        , data
-
-      if ( typeof options == 'string' ) {
-
-        data = $this.data('alert')
-
-        if (typeof data == 'object') {
-          return data[options].call( $this )
-        }
-
-      }
-
-      $(this).data('alert', new Alert( this, options ))
-
+        , data = $this.data('alert')
+      if (!data) $this.data('alert', (data = new Alert(this)))
+      if (typeof options == 'string') data[options].call($this)
     })
   }
 
-  $.fn.alert.defaults = {
-    selector: '[data-dismiss="alert"]'
-  }
+  $.fn.alert.Alert = Alert
+
+
+ /* ALERT DATA-API
+  * ============== */
 
   $(function () {
-    new Alert( $('body') )
+    $('body').delegate(dismiss, 'click.alert.data-api', Alert.prototype.close)
   })
 
 }( window.jQuery || window.ender );
\ No newline at end of file
diff --git a/js/bootstrap-buttons.js b/js/bootstrap-buttons.js
index 759a65f842..5ca678df8b 100644
--- a/js/bootstrap-buttons.js
+++ b/js/bootstrap-buttons.js
@@ -21,6 +21,11 @@
 
   "use strict"
 
+ /* BUTTON PUBLIC CLASS DEFINITION
+  * ============================== */
+
+  var Button
+
   function setState(el, state) {
     var d = 'disabled'
       , $el = $(el)
@@ -43,15 +48,17 @@
     var $el = $(el)
       , $parent = $el.parent('[data-toggle="buttons-radio"]')
 
-    if ($parent) {
-      $parent
-        .find('.active')
-        .removeClass('active')
-    }
+    $parent && $parent
+      .find('.active')
+      .removeClass('active')
 
     $el.toggleClass('active')
   }
 
+
+ /* BUTTON PLUGIN DEFINITION
+  * ======================== */
+
   $.fn.button = function(options) {
     return this.each(function () {
       if (options == 'toggle') return toggle(this)
@@ -63,8 +70,14 @@
     loadingText: 'loading...'
   }
 
+  $.fn.button.Button = Button
+
+
+ /* BUTTON DATA-API
+  * =============== */
+
   $(function () {
-    $('body').delegate('[data-toggle^=button]', 'click', function (e) {
+    $('body').delegate('[data-toggle^=button]', 'click.button.data-api', function (e) {
       $(e.srcElement).button('toggle')
     })
   })
diff --git a/js/bootstrap-collapsible.js b/js/bootstrap-collapsible.js
new file mode 100644
index 0000000000..273eb22720
--- /dev/null
+++ b/js/bootstrap-collapsible.js
@@ -0,0 +1,37 @@
+/* =============================================================
+ * bootstrap-collapsible.js v2.0.0
+ * http://twitter.github.com/bootstrap/javascript.html#collapsible
+ * =============================================================
+ * Copyright 2011 Twitter, Inc.
+ *
+ * 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.
+ * ============================================================ */
+
+(function( $ ){
+
+  var Collapsible = function ( element, options ) {}
+
+  Collapsible.prototype = {}
+
+  /* collapsible PLUGIN DEFINITION
+   * ======================= */
+
+  $.fn.collapsible = function ( options ) {
+
+    return this.each(function () {
+      new Collapsible(this, options)
+    })
+  }
+
+
+})( window.jQuery || window.ender )
\ No newline at end of file
diff --git a/js/bootstrap-dropdown.js b/js/bootstrap-dropdown.js
index bb7d11b1fa..ef243fc6f6 100644
--- a/js/bootstrap-dropdown.js
+++ b/js/bootstrap-dropdown.js
@@ -59,7 +59,7 @@
    * =================================== */
 
   $(function () {
-    $('html').bind("click", clearMenus)
+    $('html').bind("click.dropdown.data-api", clearMenus)
     $('body').dropdown(s)
   })
 
diff --git a/js/bootstrap-modal.js b/js/bootstrap-modal.js
index e15b1237ce..16c805a4e7 100644
--- a/js/bootstrap-modal.js
+++ b/js/bootstrap-modal.js
@@ -194,10 +194,6 @@
       })
     }
 
-    if ( options === true ) {
-      return modal
-    }
-
     if ( typeof options == 'string' ) {
       modal[options]()
     } else if ( modal ) {
@@ -220,7 +216,7 @@
   * ========================== */
 
   $(document).ready(function () {
-    $('body').delegate('[data-controls-modal]', 'click', function (e) {
+    $('body').delegate('[data-controls-modal]', 'click.modal.data-api', function (e) {
       e.preventDefault()
       var $this = $(this)
       $('#' + $this.attr('data-controls-modal')).modal( $this.data() )