some progress on affix plugin

docs/assets/css/bootstrap.css

@@ -5501,3 +5501,7 @@ a.badge:hover {
 .invisible {
   visibility: hidden;
 }
+
+.affix {
+  position: fixed;
+}

docs/assets/css/docs.css

@@ -891,6 +891,7 @@ form.bs-docs-example {
   margin-right: 10px;
   background-color: #fff;
   border: 1px solid #e5e5e5;
+  margin-left: 0;
   -webkit-border-radius: 6px;
      -moz-border-radius: 6px;
           border-radius: 6px;
@@ -930,11 +931,27 @@ form.bs-docs-example {
   opacity: .75;
 }
 
+.bs-docs-sidenav.affix {
+  top: 40px;
+}
+
 @media (max-width: 979px) {
 
+  .bs-docs-sidenav.affix {
+    top: 0px;
+  }
+
   .bs-docs-sidenav {
     margin-top: 30px;
     margin-right: 0;
   }
 
 }
+
+@media (max-width: 767px) {
+
+  .bs-docs-sidenav.affix {
+    position: relative;
+  }
+
+}

docs/assets/js/application.js

@@ -43,32 +43,6 @@
       })
     }
 
-    // fix sub nav on scroll
-    var $win = $(window)
-      , $nav = $('.subhead .navbar-subnav')
-      , navTop = $('.subhead .navbar-subnav').length && $('.subhead .navbar-subnav').offset().top - 40
-      , isFixed = 0
-
-    processScroll()
-
-    // hack sad times - holdover until rewrite for 2.1
-    $nav.on('click', function () {
-      if (!isFixed) setTimeout(function () {  $win.scrollTop($win.scrollTop() - 47) }, 10)
-    })
-
-    $win.on('scroll', processScroll)
-
-    function processScroll() {
-      var i, scrollTop = $win.scrollTop()
-      if (scrollTop >= navTop && !isFixed) {
-        isFixed = 1
-        $nav.addClass('navbar-subnav-fixed')
-      } else if (scrollTop <= navTop && isFixed) {
-        isFixed = 0
-        $nav.removeClass('navbar-subnav-fixed')
-      }
-    }
-
     // tooltip demo
     $('.tooltip-demo').tooltip({
       selector: "a[rel=tooltip]"

docs/assets/js/bootstrap-affix.js

@@ -0,0 +1,104 @@
+/* ==========================================================
+ * bootstrap-affix.js v2.1.0
+ * http://twitter.github.com/bootstrap/javascript.html#affix
+ * ==========================================================
+ * Copyright 2012 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 ($) {
+
+  "use strict"; // jshint ;_;
+
+
+ /* AFFIX CLASS DEFINITION
+  * ====================== */
+
+  var Affix = function (element, options) {
+    this.options = $.extend({}, $.fn.affix.defaults, options)
+    this.$window = $(window)
+      .on('scroll.affix.data-api', $.proxy(this.checkPosition, this))
+      .on('resize.affix.data-api', $.proxy(this.refresh, this))
+    this.$element = $(element)
+    this.refresh()
+  }
+
+  Affix.prototype.refresh = function () {
+    this.position = this.$element.offset()
+  }
+
+  Affix.prototype.checkPosition = function () {
+    if (!this.$element.is(':visible')) return
+
+    var scrollLeft = this.$window.scrollLeft()
+      , scrollTop = this.$window.scrollTop()
+      , position = this.position
+      , offset = this.options.offset
+      , affix
+
+    if (typeof offset != 'object') offset = { x: offset, y: offset }
+
+
+    affix = (offset.x == null || (position.left - scrollLeft <= offset.x))
+         && (offset.y == null || (position.top  - scrollTop  <= offset.y))
+
+    if (affix == this.affixed) return
+
+    this.affixed = affix
+
+    this.$element[affix ? 'addClass' : 'removeClass']('affix')
+  }
+
+
+ /* AFFIX PLUGIN DEFINITION
+  * ======================= */
+
+  $.fn.affix = function (option) {
+    return this.each(function () {
+      var $this = $(this)
+        , data = $this.data('affix')
+        , options = typeof option == 'object' && option
+      if (!data) $this.data('affix', (data = new Affix(this, options)))
+      if (typeof option == 'string') data[option]()
+    })
+  }
+
+  $.fn.affix.Constructor = Affix
+
+  $.fn.affix.defaults = {
+    offset: 0
+  }
+
+
+
+ /* AFFIX DATA-API
+  * ============== */
+
+  $(function () {
+    $('[data-spy="affix"]').each(function () {
+      var $spy = $(this)
+        , data = $spy.data()
+  
+      data.offset = data.offset || {}
+
+      data.offsetX && (data.offset.x = data.offsetX)
+      data.offsetY && (data.offset.y = data.offsetY)
+
+      $spy.affix(data)
+    })
+  })
+
+
+}(window.jQuery);

docs/assets/js/bootstrap-modal.js

@@ -26,9 +26,9 @@
  /* MODAL CLASS DEFINITION
   * ====================== */
 
-  var Modal = function (content, options) {
+  var Modal = function (element, options) {
     this.options = options
-    this.$element = $(content)
+    this.$element = $(element)
       .delegate('[data-dismiss="modal"]', 'click.dismiss.modal', $.proxy(this.hide, this))
     this.options.remote && this.$element.find('.modal-body').load(this.options.remote)
   }

docs/assets/js/bootstrap-popover.js

@@ -26,7 +26,7 @@
  /* POPOVER PUBLIC CLASS DEFINITION
   * =============================== */
 
-  var Popover = function ( element, options ) {
+  var Popover = function (element, options) {
     this.init('popover', element, options)
   }
 
@@ -72,7 +72,7 @@
     }
 
   , destroy: function () {
-      this.$element.off().removeData('popover')
+      this.hide().$element.off('.' + this.type).removeData(this.type)
     }
 
   })

docs/assets/js/bootstrap-scrollspy.js

@@ -26,12 +26,12 @@
  /* SCROLLSPY CLASS DEFINITION
   * ========================== */
 
-  function ScrollSpy( element, options) {
+  function ScrollSpy(element, options) {
     var process = $.proxy(this.process, this)
       , $element = $(element).is('body') ? $(window) : $(element)
       , href
     this.options = $.extend({}, $.fn.scrollspy.defaults, options)
-    this.$scrollElement = $element.on('scroll.scroll.data-api', process)
+    this.$scrollElement = $element.on('scroll.scroll-spy.data-api', process)
     this.selector = (this.options.target
       || ((href = $(element).attr('href')) && href.replace(/.*(?=#[^\s]+$)/, '')) //strip for ie7
       || '') + ' .nav li > a'
@@ -121,7 +121,7 @@
  /* SCROLLSPY PLUGIN DEFINITION
   * =========================== */
 
-  $.fn.scrollspy = function ( option ) {
+  $.fn.scrollspy = function (option) {
     return this.each(function () {
       var $this = $(this)
         , data = $this.data('scrollspy')
@@ -141,7 +141,7 @@
  /* SCROLLSPY DATA-API
   * ================== */
 
-  $(function () {
+  $(window).on('load', function () {
     $('[data-spy="scroll"]').each(function () {
       var $spy = $(this)
       $spy.scrollspy($spy.data())

docs/assets/js/bootstrap-tab.js

@@ -26,7 +26,7 @@
  /* TAB CLASS DEFINITION
   * ==================== */
 
-  var Tab = function ( element ) {
+  var Tab = function (element) {
     this.element = $(element)
   }
 

docs/assets/js/bootstrap-tooltip.js

@@ -47,8 +47,8 @@
       if (this.options.trigger != 'manual') {
         eventIn  = this.options.trigger == 'hover' ? 'mouseenter' : 'focus'
         eventOut = this.options.trigger == 'hover' ? 'mouseleave' : 'blur'
-        this.$element.on(eventIn, this.options.selector, $.proxy(this.enter, this))
-        this.$element.on(eventOut, this.options.selector, $.proxy(this.leave, this))
+        this.$element.on(eventIn + '.' + this.type, this.options.selector, $.proxy(this.enter, this))
+        this.$element.on(eventOut + '.' + this.type, this.options.selector, $.proxy(this.leave, this))
       }
 
       this.options.selector ?
@@ -176,6 +176,8 @@
       $.support.transition && this.$tip.hasClass('fade') ?
         removeWithAnimation() :
         $tip.remove()
+
+      return this
     }
 
   , fixTitle: function () {
@@ -236,7 +238,7 @@
     }
 
   , destroy: function () {
-      this.$element.off().removeData('tooltip')
+      this.hide().$element.off('.' + this.type).removeData(this.type)
     }
 
   }

docs/assets/js/bootstrap.js

@@ -751,9 +751,9 @@
  /* MODAL CLASS DEFINITION
   * ====================== */
 
-  var Modal = function (content, options) {
+  var Modal = function (element, options) {
     this.options = options
-    this.$element = $(content)
+    this.$element = $(element)
       .delegate('[data-dismiss="modal"]', 'click.dismiss.modal', $.proxy(this.hide, this))
     this.options.remote && this.$element.find('.modal-body').load(this.options.remote)
   }
@@ -1000,8 +1000,8 @@
       if (this.options.trigger != 'manual') {
         eventIn  = this.options.trigger == 'hover' ? 'mouseenter' : 'focus'
         eventOut = this.options.trigger == 'hover' ? 'mouseleave' : 'blur'
-        this.$element.on(eventIn, this.options.selector, $.proxy(this.enter, this))
-        this.$element.on(eventOut, this.options.selector, $.proxy(this.leave, this))
+        this.$element.on(eventIn + '.' + this.type, this.options.selector, $.proxy(this.enter, this))
+        this.$element.on(eventOut + '.' + this.type, this.options.selector, $.proxy(this.leave, this))
       }
 
       this.options.selector ?
@@ -1129,6 +1129,8 @@
       $.support.transition && this.$tip.hasClass('fade') ?
         removeWithAnimation() :
         $tip.remove()
+
+      return this
     }
 
   , fixTitle: function () {
@@ -1189,7 +1191,7 @@
     }
 
   , destroy: function () {
-      this.$element.off().removeData('tooltip')
+      this.hide().$element.off('.' + this.type).removeData(this.type)
     }
 
   }
@@ -1250,7 +1252,7 @@
  /* POPOVER PUBLIC CLASS DEFINITION
   * =============================== */
 
-  var Popover = function ( element, options ) {
+  var Popover = function (element, options) {
     this.init('popover', element, options)
   }
 
@@ -1296,7 +1298,7 @@
     }
 
   , destroy: function () {
-      this.$element.off().removeData('popover')
+      this.hide().$element.off('.' + this.type).removeData(this.type)
     }
 
   })
@@ -1351,12 +1353,12 @@
  /* SCROLLSPY CLASS DEFINITION
   * ========================== */
 
-  function ScrollSpy( element, options) {
+  function ScrollSpy(element, options) {
     var process = $.proxy(this.process, this)
       , $element = $(element).is('body') ? $(window) : $(element)
       , href
     this.options = $.extend({}, $.fn.scrollspy.defaults, options)
-    this.$scrollElement = $element.on('scroll.scroll.data-api', process)
+    this.$scrollElement = $element.on('scroll.scroll-spy.data-api', process)
     this.selector = (this.options.target
       || ((href = $(element).attr('href')) && href.replace(/.*(?=#[^\s]+$)/, '')) //strip for ie7
       || '') + ' .nav li > a'
@@ -1446,7 +1448,7 @@
  /* SCROLLSPY PLUGIN DEFINITION
   * =========================== */
 
-  $.fn.scrollspy = function ( option ) {
+  $.fn.scrollspy = function (option) {
     return this.each(function () {
       var $this = $(this)
         , data = $this.data('scrollspy')
@@ -1466,7 +1468,7 @@
  /* SCROLLSPY DATA-API
   * ================== */
 
-  $(function () {
+  $(window).on('load', function () {
     $('[data-spy="scroll"]').each(function () {
       var $spy = $(this)
       $spy.scrollspy($spy.data())
@@ -1501,7 +1503,7 @@
  /* TAB CLASS DEFINITION
   * ==================== */
 
-  var Tab = function ( element ) {
+  var Tab = function (element) {
     this.element = $(element)
   }
 

docs/base-css.html

@@ -85,7 +85,7 @@
   ================================================== -->
   <div class="row">
     <div class="span3 bs-docs-sidebar">
-      <ul class="nav nav-list bs-docs-sidenav">
+      <ul class="nav nav-list bs-docs-sidenav" data-spy="affix" data-offset-y="80">
         <li><a href="#typography">Typography <i class="icon-chevron-right"></i></a></li>
         <li><a href="#code">Code <i class="icon-chevron-right"></i></a></li>
         <li><a href="#tables">Tables <i class="icon-chevron-right"></i></a></li>
@@ -1794,6 +1794,7 @@ For example, &lt;code&gt;section&lt;/code&gt; should be wrapped as inline.
     <script src="assets/js/bootstrap-collapse.js"></script>
     <script src="assets/js/bootstrap-carousel.js"></script>
     <script src="assets/js/bootstrap-typeahead.js"></script>
+    <script src="assets/js/bootstrap-affix.js"></script>
     <script src="assets/js/application.js"></script>
 
 

docs/components.html

@@ -85,7 +85,7 @@
   ================================================== -->
   <div class="row">
     <div class="span3 bs-docs-sidebar">
-      <ul class="nav nav-list bs-docs-sidenav">
+      <ul class="nav nav-list bs-docs-sidenav" data-spy="affix" data-offset-y="80">
         <li><a href="#dropdowns">Dropdowns <i class="icon-chevron-right"></i></a></li>
         <li><a href="#buttonGroups">Button groups <i class="icon-chevron-right"></i></a></li>
         <li><a href="#buttonDropdowns">Button dropdowns <i class="icon-chevron-right"></i></a></li>
@@ -2198,6 +2198,7 @@ class="clearfix"
     <script src="assets/js/bootstrap-collapse.js"></script>
     <script src="assets/js/bootstrap-carousel.js"></script>
     <script src="assets/js/bootstrap-typeahead.js"></script>
+    <script src="assets/js/bootstrap-affix.js"></script>
     <script src="assets/js/application.js"></script>
 
 

docs/customize.html

@@ -85,7 +85,7 @@
   ================================================== -->
   <div class="row">
     <div class="span3 bs-docs-sidebar">
-      <ul class="nav nav-list bs-docs-sidenav">
+      <ul class="nav nav-list bs-docs-sidenav" data-spy="affix" data-offset-y="80">
         <li><a href="#components">1. Choose components</a></li>
         <li><a href="#plugins">2. Select jQuery plugins</a></li>
         <li><a href="#variables">3. Customize variables</a></li>
@@ -469,6 +469,7 @@
     <script src="assets/js/bootstrap-collapse.js"></script>
     <script src="assets/js/bootstrap-carousel.js"></script>
     <script src="assets/js/bootstrap-typeahead.js"></script>
+    <script src="assets/js/bootstrap-affix.js"></script>
     <script src="assets/js/application.js"></script>
 
 

docs/extend.html

@@ -85,7 +85,7 @@
   ================================================== -->
   <div class="row">
     <div class="span3 bs-docs-sidebar">
-      <ul class="nav nav-list bs-docs-sidenav">
+      <ul class="nav nav-list bs-docs-sidenav" data-spy="affix" data-offset-y="80">
         <li><a href="#built-with-less">Built with LESS <i class="icon-chevron-right"></i></a></li>
         <li><a href="#compiling">Compiling Bootstrap <i class="icon-chevron-right"></i></a></li>
         <li><a href="#static-assets">Use as static assets <i class="icon-chevron-right"></i></a></li>
@@ -281,6 +281,7 @@
     <script src="assets/js/bootstrap-collapse.js"></script>
     <script src="assets/js/bootstrap-carousel.js"></script>
     <script src="assets/js/bootstrap-typeahead.js"></script>
+    <script src="assets/js/bootstrap-affix.js"></script>
     <script src="assets/js/application.js"></script>
 
 

docs/getting-started.html

@@ -83,7 +83,7 @@
 
   <div class="row">
     <div class="span3 bs-docs-sidebar">
-      <ul class="nav nav-list bs-docs-sidenav">
+      <ul class="nav nav-list bs-docs-sidenav" data-spy="affix" data-offset-y="80">
         <li><a href="#download-bootstrap">Download <i class="icon-chevron-right"></i></a></li>
         <li><a href="#file-structure">File structure <i class="icon-chevron-right"></i></a></li>
         <li><a href="#contents">What's included <i class="icon-chevron-right"></i></a></li>
@@ -322,6 +322,7 @@
     <script src="assets/js/bootstrap-collapse.js"></script>
     <script src="assets/js/bootstrap-carousel.js"></script>
     <script src="assets/js/bootstrap-typeahead.js"></script>
+    <script src="assets/js/bootstrap-affix.js"></script>
     <script src="assets/js/application.js"></script>
 
 

docs/index.html

@@ -197,6 +197,7 @@
     <script src="assets/js/bootstrap-collapse.js"></script>
     <script src="assets/js/bootstrap-carousel.js"></script>
     <script src="assets/js/bootstrap-typeahead.js"></script>
+    <script src="assets/js/bootstrap-affix.js"></script>
     <script src="assets/js/application.js"></script>
 
 

docs/javascript.html

@@ -85,7 +85,8 @@
   ================================================== -->
   <div class="row">
     <div class="span3 bs-docs-sidebar">
-      <ul class="nav nav-list bs-docs-sidenav">
+      <ul class="span3 nav nav-list bs-docs-sidenav" data-spy="affix" data-offset-y="80">
+        <li><a href="#overview">Overview <i class="icon-chevron-right"></i></a></li>
         <li><a href="#transitions">Transitions <i class="icon-chevron-right"></i></a></li>
         <li><a href="#modals">Modal <i class="icon-chevron-right"></i></a></li>
         <li><a href="#dropdowns">Dropdown <i class="icon-chevron-right"></i></a></li>
@@ -113,15 +114,51 @@
         </div>
 
         <h3>Individual or compiled</h3>
-        <p>If you have downloaded the latest version of Bootstrap, both <strong>bootstrap.js</strong> and <strong>bootstrap.min.js</strong> contain all of these plugins.</p>
+        <p>If you have downloaded the latest version of Bootstrap, both <strong>bootstrap.js</strong> and <strong>bootstrap.min.js</strong> contain all of the plugins listed on this page.</p>
 
         <h3>Data attributes</h3>
-        <p>...</p>
+        <p>You can use all Bootstrap plugins purely through the markup API without writing a single line of JavaScript. This is Bootstrap's first class API and should be your first consideration when using a plugin.</p>
+
+        <p>That said, in some situations it may be desirable to turn this functionality off. Therefore, we also provide the ability to disable the data attribute API by unbinding all events on the body namespaced with `'data-api'`. This looks like this:
+
+<pre class="prettyprint linenums">
+  $('body').off('.data-api')
+</pre>
+
+        <p>Alternatively, to target a specific plugin, just include the plugins name as a namespace along with the data-api namespace like this:</p>
+
+<pre class="prettyprint linenums">
+  $('body').off('.alert.data-api')
+</pre>
 
         <h3>Programmatic API</h3>
-        <p>...</p>
+        <p>We also believe you should be able to use all Bootstrap plugins purely through the JavaScript API. All public APIs are single, chainable methods, and return the collection acted upon.</p>
+
+<pre class="prettyprint linenums">
+  $(".btn.danger").button("toggle").addClass("fat")
+</pre>
+
+        <p>All methods should accept an optional options object, a string which targets a particular method, or nothing (which initiates a plugin with default behavior):</p>
+
+<pre class="prettyprint linenums">
+  $("#myModal").modal()                       // initialized with defaults
+  $("#myModal").modal({ keyboard: false })   // initialized with no keyboard
+  $("#myModal").modal('show')                // initializes and invokes show immediately</p>
+</pre>
+
+        <p>Each plugin also exposes it's raw constructor on a `Constructor` property: <code>$.fn.popover.Constructor</code>. If you'd like to get a particular plugin instance, retrieve it directly from an element: <code>$('[rel=popover]').data('popover')</code>.</p>
 
 
+        <h3>Events</h3>
+        <p>Bootstrap provides custom events for most plugin's unique actions. Generally, these come in an infinitive and past participle form - where the infinitive (ex. <code>show</code>) is triggered at the start of an event, and it's past participle form (ex. <code>shown</code>) is trigger on the completion of an action.</p>
+
+        <p>All infinitive events provide preventDefault functionality. This provides the abililty to stop the execution of an action before it starts.</p>
+
+<pre class="prettyprint linenums">
+  $('#myModal').on('show', function (e) {
+      if (!data) return e.preventDefault() // stops modal from being shown
+  })
+</pre>
 
       </section>
 
@@ -849,7 +886,7 @@ $('a[data-toggle="tab"]').on('shown', function (e) {
         <p>Toggles an element's tooltip.</p>
         <pre class="prettyprint linenums">$('#element').tooltip('toggle')</pre>
         <h4>.tooltip('destroy')</h4>
-        <p>Destroys an element's tooltip.</p>
+        <p>Hides and destroys an element's tooltip.</p>
         <pre class="prettyprint linenums">$('#element').tooltip('destroy')</pre>
       </section>
 
@@ -1004,7 +1041,7 @@ $('a[data-toggle="tab"]').on('shown', function (e) {
         <p>Toggles an elements popover.</p>
         <pre class="prettyprint linenums">$('#element').popover('toggle')</pre>
         <h4>.popover('destroy')</h4>
-        <p>Destroys an element's popover.</p>
+        <p>Hides and destroys an element's popover.</p>
         <pre class="prettyprint linenums">$('#element').popover('destroy')</pre>
       </section>
 
@@ -1581,23 +1618,60 @@ $('.carousel').carousel({
       ================================================== -->
       <section id="affix">
         <div class="page-header">
-          <h1>
-            Affix
-            <small>Make an element stick in place</small>
-          </h1>
+          <h1>Affix <small>bootstrap-affix.js</small></h1>
         </div>
 
-        <h2>...</h2>
-        <p>...</p>
-        <div class="bs-docs-example">
 
+        <h2>Example</h2>
+        <p>The subnavigation on the left is a live demo of the affix plugin.</p>
+        
+        <hr class="bs-docs-separator">
+
+        <h2>Usage</h2>
+
+        <h3>Via data attributes</h3>
+        <p>To easily add affix behavior to any element, just add <code>data-spy="affix"</code> to the element you want to spy on. When the affix offsets are satisified, an <code>.affix</code> class is added to the element. </p>
+
+        <pre class="prettyprint linenums">&lt;div data-spy="affix"&gt;...&lt;/body&gt;</pre>
+        
+        <div class="alert alert-info">
+          <strong>Heads up!</strong>
+          It's up to you to maintain the dimensions of an element when toggling between relative and fixed positions. To see how this is done, refer to this pages subnavigation.
         </div>
+
+        <h3>Via javascript</h3>
+        <p>Call the affix plugin via javascript:</p>
+        <pre class="prettyprint linenums">$('#navbar').affix()</pre>
+
+        <h3>Methods</h3>
+        <h4>.scrollspy('refresh')</h4>
+        <p>When using affix in conjunction with adding or removing of elements from the DOM, you'll need to call the refresh method like so:</p>
 <pre class="prettyprint linenums">
-...
+$('[data-spy="affix"]').each(function () {
+  $(this).affix('refresh')
+});
 </pre>
-      </section>
-
 
+        <h3>Options</h3>
+        <p>Options can be passed via data attributes or javascript. For data attributes, append the option name to <code>data-</code>, as in <code>data-offset-y=""</code>.</p>
+        <table class="table table-bordered table-striped">
+          <thead>
+           <tr>
+             <th style="width: 100px;">Name</th>
+             <th style="width: 100px;">type</th>
+             <th style="width: 50px;">default</th>
+             <th>description</th>
+           </tr>
+          </thead>
+          <tbody>
+           <tr>
+             <td>offset</td>
+             <td>number | object</td>
+             <td>10</td>
+             <td>Pixels to offset from screen when calculating position of scroll. If a single number is provide, the offset will be applied in both top and left directions. To listen for a single direction, or multiple unique offsets, just provided an object <code>offset: { x: 10 }</code>.</td>
+           </tr>
+          </tbody>
+        </table>
 
     </div>
   </div>
@@ -1642,6 +1716,7 @@ $('.carousel').carousel({
     <script src="assets/js/bootstrap-collapse.js"></script>
     <script src="assets/js/bootstrap-carousel.js"></script>
     <script src="assets/js/bootstrap-typeahead.js"></script>
+    <script src="assets/js/bootstrap-affix.js"></script>
     <script src="assets/js/application.js"></script>
 
 

docs/scaffolding.html

@@ -86,7 +86,7 @@
   ================================================== -->
   <div class="row">
     <div class="span3 bs-docs-sidebar">
-      <ul class="nav nav-list bs-docs-sidenav">
+      <ul class="nav nav-list bs-docs-sidenav" data-spy="affix" data-offset-y="80">
         <li><a href="#global">Global styles <i class="icon-chevron-right"></i></a></li>
         <li><a href="#gridSystem">Grid system <i class="icon-chevron-right"></i></a></li>
         <li><a href="#fluidGridSystem">Fluid grid system <i class="icon-chevron-right"></i></a></li>
@@ -579,6 +579,7 @@
     <script src="assets/js/bootstrap-collapse.js"></script>
     <script src="assets/js/bootstrap-carousel.js"></script>
     <script src="assets/js/bootstrap-typeahead.js"></script>
+    <script src="assets/js/bootstrap-affix.js"></script>
     <script src="assets/js/application.js"></script>
 
 

docs/templates/layout.mustache

@@ -121,6 +121,7 @@
     <script src="assets/js/bootstrap-collapse.js"></script>
     <script src="assets/js/bootstrap-carousel.js"></script>
     <script src="assets/js/bootstrap-typeahead.js"></script>
+    <script src="assets/js/bootstrap-affix.js"></script>
     <script src="assets/js/application.js"></script>
 
     {{#production}}

docs/templates/pages/base-css.mustache

@@ -14,7 +14,7 @@
   ================================================== -->
   <div class="row">
     <div class="span3 bs-docs-sidebar">
-      <ul class="nav nav-list bs-docs-sidenav">
+      <ul class="nav nav-list bs-docs-sidenav" data-spy="affix" data-offset-y="80">
         <li><a href="#typography">{{_i}}Typography{{/i}} <i class="icon-chevron-right"></i></a></li>
         <li><a href="#code">{{_i}}Code{{/i}} <i class="icon-chevron-right"></i></a></li>
         <li><a href="#tables">{{_i}}Tables{{/i}} <i class="icon-chevron-right"></i></a></li>

docs/templates/pages/components.mustache

@@ -14,7 +14,7 @@
   ================================================== -->
   <div class="row">
     <div class="span3 bs-docs-sidebar">
-      <ul class="nav nav-list bs-docs-sidenav">
+      <ul class="nav nav-list bs-docs-sidenav" data-spy="affix" data-offset-y="80">
         <li><a href="#dropdowns">{{_i}}Dropdowns{{/i}} <i class="icon-chevron-right"></i></a></li>
         <li><a href="#buttonGroups">{{_i}}Button groups{{/i}} <i class="icon-chevron-right"></i></a></li>
         <li><a href="#buttonDropdowns">{{_i}}Button dropdowns{{/i}} <i class="icon-chevron-right"></i></a></li>

docs/templates/pages/customize.mustache

@@ -14,7 +14,7 @@
   ================================================== -->
   <div class="row">
     <div class="span3 bs-docs-sidebar">
-      <ul class="nav nav-list bs-docs-sidenav">
+      <ul class="nav nav-list bs-docs-sidenav" data-spy="affix" data-offset-y="80">
         <li><a href="#components">{{_i}}1. Choose components{{/i}}</a></li>
         <li><a href="#plugins">{{_i}}2. Select jQuery plugins{{/i}}</a></li>
         <li><a href="#variables">{{_i}}3. Customize variables{{/i}}</a></li>

docs/templates/pages/extend.mustache

@@ -14,7 +14,7 @@
   ================================================== -->
   <div class="row">
     <div class="span3 bs-docs-sidebar">
-      <ul class="nav nav-list bs-docs-sidenav">
+      <ul class="nav nav-list bs-docs-sidenav" data-spy="affix" data-offset-y="80">
         <li><a href="#built-with-less">{{_i}}Built with LESS{{/i}} <i class="icon-chevron-right"></i></a></li>
         <li><a href="#compiling">{{_i}}Compiling Bootstrap{{/i}} <i class="icon-chevron-right"></i></a></li>
         <li><a href="#static-assets">{{_i}}Use as static assets{{/i}} <i class="icon-chevron-right"></i></a></li>

docs/templates/pages/getting-started.mustache

@@ -12,7 +12,7 @@
 
   <div class="row">
     <div class="span3 bs-docs-sidebar">
-      <ul class="nav nav-list bs-docs-sidenav">
+      <ul class="nav nav-list bs-docs-sidenav" data-spy="affix" data-offset-y="80">
         <li><a href="#download-bootstrap">{{_i}}Download{{/i}} <i class="icon-chevron-right"></i></a></li>
         <li><a href="#file-structure">{{_i}}File structure{{/i}} <i class="icon-chevron-right"></i></a></li>
         <li><a href="#contents">{{_i}}What's included{{/i}} <i class="icon-chevron-right"></i></a></li>

docs/templates/pages/javascript.mustache

@@ -14,7 +14,8 @@
   ================================================== -->
   <div class="row">
     <div class="span3 bs-docs-sidebar">
-      <ul class="nav nav-list bs-docs-sidenav">
+      <ul class="span3 nav nav-list bs-docs-sidenav" data-spy="affix" data-offset-max-979="40" data-offset="80">
+        <li><a href="#overview">{{_i}}Overview{{/i}} <i class="icon-chevron-right"></i></a></li>
         <li><a href="#transitions">{{_i}}Transitions{{/i}} <i class="icon-chevron-right"></i></a></li>
         <li><a href="#modals">{{_i}}Modal{{/i}} <i class="icon-chevron-right"></i></a></li>
         <li><a href="#dropdowns">{{_i}}Dropdown{{/i}} <i class="icon-chevron-right"></i></a></li>
@@ -42,16 +43,51 @@
         </div>
 
         <h3>{{_i}}Individual or compiled{{/i}}</h3>
-        <p>{{_i}}If you have downloaded the latest version of Bootstrap, both <strong>bootstrap.js</strong> and <strong>bootstrap.min.js</strong> contain all of these plugins.{{/i}}</p>
+        <p>{{_i}}If you have downloaded the latest version of Bootstrap, both <strong>bootstrap.js</strong> and <strong>bootstrap.min.js</strong> contain all of the plugins listed on this page.{{/i}}</p>
 
         <h3>{{_i}}Data attributes{{/i}}</h3>
-        <p>{{_i}}...{{/i}}</p>
+        <p>{{_i}}You can use all Bootstrap plugins purely through the markup API without writing a single line of JavaScript. This is Bootstrap's first class API and should be your first consideration when using a plugin.{{/i}}</p>
+
+        <p>{{_i}}That said, in some situations it may be desirable to turn this functionality off. Therefore, we also provide the ability to disable the data attribute API by unbinding all events on the body namespaced with `'data-api'`. This looks like this:{{/i}}
+
+<pre class="prettyprint linenums">
+  $('body').off('.data-api')
+</pre>
+
+        <p>{{_i}}Alternatively, to target a specific plugin, just include the plugins name as a namespace along with the data-api namespace like this:{{/i}}</p>
+
+<pre class="prettyprint linenums">
+  $('body').off('.alert.data-api')
+</pre>
 
         <h3>{{_i}}Programmatic API{{/i}}</h3>
-        <p>{{_i}}...{{/i}}</p>
+        <p>{{_i}}We also believe you should be able to use all Bootstrap plugins purely through the JavaScript API. All public APIs are single, chainable methods, and return the collection acted upon.{{/i}}</p>
+
+<pre class="prettyprint linenums">
+  $(".btn.danger").button("toggle").addClass("fat")
+</pre>
+
+        <p>{{_i}}All methods should accept an optional options object, a string which targets a particular method, or nothing (which initiates a plugin with default behavior):{{/i}}</p>
+
+<pre class="prettyprint linenums">
+  $("#myModal").modal()                       // initialized with defaults
+  $("#myModal").modal({ keyboard: false })   // initialized with no keyboard
+  $("#myModal").modal('show')                // initializes and invokes show immediately</p>
+</pre>
+
+        <p>{{_i}}Each plugin also exposes it's raw constructor on a `Constructor` property: <code>$.fn.popover.Constructor</code>. If you'd like to get a particular plugin instance, retrieve it directly from an element: <code>$('[rel=popover]').data('popover')</code>.{{/i}}</p>
 
 
-        {{! Thought: consider porting much of the JS readme here? }}
+        <h3>{{_i}}Events{{/i}}</h3>
+        <p>{{_i}}Bootstrap provides custom events for most plugin's unique actions. Generally, these come in an infinitive and past participle form - where the infinitive (ex. <code>show</code>) is triggered at the start of an event, and it's past participle form (ex. <code>shown</code>) is trigger on the completion of an action.{{/i}}</p>
+
+        <p>{{_i}}All infinitive events provide preventDefault functionality. This provides the abililty to stop the execution of an action before it starts.{{/i}}</p>
+
+<pre class="prettyprint linenums">
+  $('#myModal').on('show', function (e) {
+      if (!data) return e.preventDefault() // stops modal from being shown
+  })
+</pre>
 
       </section>
 
@@ -1512,23 +1548,60 @@ $('.carousel').carousel({
       ================================================== -->
       <section id="affix">
         <div class="page-header">
-          <h1>
-            {{_i}}Affix{{/i}}
-            <small>{{_i}}Make an element stick in place{{/i}}</small>
-          </h1>
+          <h1>{{_i}}Affix{{/i}} <small>bootstrap-affix.js</small></h1>
         </div>
 
-        <h2>{{_i}}...{{/i}}</h2>
-        <p>{{_i}}...{{/i}}</p>
-        <div class="bs-docs-example">
 
+        <h2>{{_i}}Example{{/i}}</h2>
+        <p>{{_i}}The subnavigation on the left is a live demo of the affix plugin.{{/i}}</p>
+        
+        <hr class="bs-docs-separator">
+
+        <h2>{{_i}}Usage{{/i}}</h2>
+
+        <h3>{{_i}}Via data attributes{{/i}}</h3>
+        <p>{{_i}}To easily add affix behavior to any element, just add <code>data-spy="affix"</code> to the element you want to spy on. When the affix offsets are satisified, an <code>.affix</code> class is added to the element. {{/i}}</p>
+
+        <pre class="prettyprint linenums">&lt;div data-spy="affix"&gt;...&lt;/body&gt;</pre>
+        
+        <div class="alert alert-info">
+          <strong>{{_i}}Heads up!{{/i}}</strong>
+          {{_i}}It's up to you to maintain the dimensions of an element when toggling between relative and fixed positions. To see how this is done, refer to this pages subnavigation.{{/i}}
         </div>
+
+        <h3>{{_i}}Via javascript{{/i}}</h3>
+        <p>{{_i}}Call the affix plugin via javascript:{{/i}}</p>
+        <pre class="prettyprint linenums">$('#navbar').affix()</pre>
+
+        <h3>{{_i}}Methods{{/i}}</h3>
+        <h4>.scrollspy('refresh')</h4>
+        <p>{{_i}}When using affix in conjunction with adding or removing of elements from the DOM, you'll need to call the refresh method like so:{{/i}}</p>
 <pre class="prettyprint linenums">
-...
+$('[data-spy="affix"]').each(function () {
+  $(this).affix('refresh')
+});
 </pre>
-      </section>
-
 
+        <h3>{{_i}}Options{{/i}}</h3>
+        <p>{{_i}}Options can be passed via data attributes or javascript. For data attributes, append the option name to <code>data-</code>, as in <code>data-offset-y=""</code>.{{/i}}</p>
+        <table class="table table-bordered table-striped">
+          <thead>
+           <tr>
+             <th style="width: 100px;">{{_i}}Name{{/i}}</th>
+             <th style="width: 100px;">{{_i}}type{{/i}}</th>
+             <th style="width: 50px;">{{_i}}default{{/i}}</th>
+             <th>{{_i}}description{{/i}}</th>
+           </tr>
+          </thead>
+          <tbody>
+           <tr>
+             <td>{{_i}}offset{{/i}}</td>
+             <td>{{_i}}number | object{{/i}}</td>
+             <td>{{_i}}10{{/i}}</td>
+             <td>{{_i}}Pixels to offset from screen when calculating position of scroll. If a single number is provide, the offset will be applied in both top and left directions. To listen for a single direction, or multiple unique offsets, just provided an object <code>offset: { x: 10 }</code>.{{/i}}</td>
+           </tr>
+          </tbody>
+        </table>
 
     </div>{{! /span9 }}
   </div>{{! row}}

docs/templates/pages/scaffolding.mustache

@@ -15,7 +15,7 @@
   ================================================== -->
   <div class="row">
     <div class="span3 bs-docs-sidebar">
-      <ul class="nav nav-list bs-docs-sidenav">
+      <ul class="nav nav-list bs-docs-sidenav" data-spy="affix" data-offset-y="80">
         <li><a href="#global">{{_i}}Global styles{{/i}} <i class="icon-chevron-right"></i></a></li>
         <li><a href="#gridSystem">{{_i}}Grid system{{/i}} <i class="icon-chevron-right"></i></a></li>
         <li><a href="#fluidGridSystem">{{_i}}Fluid grid system{{/i}} <i class="icon-chevron-right"></i></a></li>

docs/upgrading.html

@@ -302,6 +302,7 @@
     <script src="assets/js/bootstrap-collapse.js"></script>
     <script src="assets/js/bootstrap-carousel.js"></script>
     <script src="assets/js/bootstrap-typeahead.js"></script>
+    <script src="assets/js/bootstrap-affix.js"></script>
     <script src="assets/js/application.js"></script>
 
 

js/.jshintrc

@@ -3,6 +3,7 @@
     "laxcomma" : true,
     "laxbreak" : true,
     "browser"  : true,
+    "eqnull"   : true,
     "debug"    : true,
     "devel"    : true,
     "boss"     : true,

js/README.md

@@ -1,112 +0,0 @@
-## 2.0 BOOTSTRAP JS PHILOSOPHY
-These are the high-level design rules which guide the development of Bootstrap's plugin apis.
-
----
-
-### 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. This is Bootstrap's first class API.
-
-We acknowledge that this isn't always the most performant and it may sometimes 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').off('.data-api')
-
-To target a specific plugin, just include the plugins name as a namespace along with the data-api namespace like this:
-
-    $('body').off('.alert.data-api')
-
----
-
-### PROGRAMATIC API
-
-We also believe you should be able to use all plugins provided by Bootstrap purely through the JavaScript API.
-
-All public APIs should be single, chainable methods, 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 initiates the default behavior:
-
-    $("#myModal").modal() // initialized with defaults
-    $("#myModal").modal({ keyboard: false }) // initialized with no keyboard
-    $("#myModal").modal('show') // initializes and invokes show immediately
-
----
-
-### 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 affect all instances' default options. The defaults object should be available via `$.fn.plugin.defaults`.
-
-    $.fn.modal.defaults = { … }
-
-An options definition should take the following form:
-
-    *noun*: *adjective* - describes or modifies a quality of an instance
-
-Examples:
-
-    backdrop: true
-    keyboard: false
-    placement: 'top'
-
----
-
-### 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
-
-All infinitive events should provide preventDefault functionality. This provides the abililty to stop the execution of an action.
-
-    $('#myModal').on('show', function (e) {
-        if (!data) return e.preventDefault() // stops modal from being shown
-    })
-
----
-
-### CONSTRUCTORS
-
-Each plugin should expose its raw constructor on a `Constructor` property -- accessed in the following way:
-
-
-    $.fn.popover.Constructor
-
----
-
-### DATA ACCESSOR
-
-Each plugin stores a copy of the invoked class on an object. This class instance can be accessed directly through jQuery's data API like this:
-
-    $('[rel=popover]').data('popover') instanceof $.fn.popover.Constructor
-
----
-
-### DATA ATTRIBUTES
-
-Data attributes should take the following form:
-
-- data-{{verb}}={{plugin}} - defines main interaction
-- data-target || href^=# - defined on "control" element (if element controls an element other than self)
-- data-{{noun}} - defines class instance options
-
-Examples:
-
-    // control other targets
-    data-toggle="modal" data-target="#foo"
-    data-toggle="collapse" data-target="#foo" data-parent="#bar"
-
-    // 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"

js/bootstrap-affix.js

@@ -0,0 +1,102 @@
+/* ==========================================================
+ * bootstrap-affix.js v2.1.0
+ * http://twitter.github.com/bootstrap/javascript.html#affix
+ * ==========================================================
+ * Copyright 2012 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 ($) {
+
+  "use strict"; // jshint ;_;
+
+
+ /* AFFIX CLASS DEFINITION
+  * ====================== */
+
+  var Affix = function (element, options) {
+    this.options = $.extend({}, $.fn.affix.defaults, options)
+    this.$window = $(window)
+      .on('scroll.affix.data-api', $.proxy(this.checkPosition, this))
+      .on('resize.affix.data-api', $.proxy(this.refresh, this))
+    this.$element = $(element)
+    this.refresh()
+  }
+
+  Affix.prototype.refresh = function () {
+    this.position = this.$element.offset()
+  }
+
+  Affix.prototype.checkPosition = function () {
+    if (!this.$element.is(':visible')) return
+
+    var scrollLeft = this.$window.scrollLeft()
+      , scrollTop = this.$window.scrollTop()
+      , position = this.position
+      , offset = this.options.offset
+      , affix
+
+    if (typeof offset != 'object') offset = { x: offset, y: offset }
+
+    affix = (offset.x == null || (position.left - scrollLeft <= offset.x))
+         && (offset.y == null || (position.top  - scrollTop  <= offset.y))
+
+    if (affix == this.affixed) return
+
+    this.affixed = affix
+
+    this.$element[affix ? 'addClass' : 'removeClass']('affix')
+  }
+
+
+ /* AFFIX PLUGIN DEFINITION
+  * ======================= */
+
+  $.fn.affix = function (option) {
+    return this.each(function () {
+      var $this = $(this)
+        , data = $this.data('affix')
+        , options = typeof option == 'object' && option
+      if (!data) $this.data('affix', (data = new Affix(this, options)))
+      if (typeof option == 'string') data[option]()
+    })
+  }
+
+  $.fn.affix.Constructor = Affix
+
+  $.fn.affix.defaults = {
+    offset: 0
+  }
+
+
+ /* AFFIX DATA-API
+  * ============== */
+
+  $(function () {
+    $('[data-spy="affix"]').each(function () {
+      var $spy = $(this)
+        , data = $spy.data()
+  
+      data.offset = data.offset || {}
+
+      data.offsetX && (data.offset.x = data.offsetX)
+      data.offsetY && (data.offset.y = data.offsetY)
+
+      $spy.affix(data)
+    })
+  })
+
+
+}(window.jQuery);

js/bootstrap-modal.js

@@ -26,9 +26,9 @@
  /* MODAL CLASS DEFINITION
   * ====================== */
 
-  var Modal = function (content, options) {
+  var Modal = function (element, options) {
     this.options = options
-    this.$element = $(content)
+    this.$element = $(element)
       .delegate('[data-dismiss="modal"]', 'click.dismiss.modal', $.proxy(this.hide, this))
     this.options.remote && this.$element.find('.modal-body').load(this.options.remote)
   }

js/bootstrap-popover.js

@@ -26,7 +26,7 @@
  /* POPOVER PUBLIC CLASS DEFINITION
   * =============================== */
 
-  var Popover = function ( element, options ) {
+  var Popover = function (element, options) {
     this.init('popover', element, options)
   }
 

js/bootstrap-scrollspy.js

@@ -26,12 +26,12 @@
  /* SCROLLSPY CLASS DEFINITION
   * ========================== */
 
-  function ScrollSpy( element, options) {
+  function ScrollSpy(element, options) {
     var process = $.proxy(this.process, this)
       , $element = $(element).is('body') ? $(window) : $(element)
       , href
     this.options = $.extend({}, $.fn.scrollspy.defaults, options)
-    this.$scrollElement = $element.on('scroll.scroll.data-api', process)
+    this.$scrollElement = $element.on('scroll.scroll-spy.data-api', process)
     this.selector = (this.options.target
       || ((href = $(element).attr('href')) && href.replace(/.*(?=#[^\s]+$)/, '')) //strip for ie7
       || '') + ' .nav li > a'
@@ -121,7 +121,7 @@
  /* SCROLLSPY PLUGIN DEFINITION
   * =========================== */
 
-  $.fn.scrollspy = function ( option ) {
+  $.fn.scrollspy = function (option) {
     return this.each(function () {
       var $this = $(this)
         , data = $this.data('scrollspy')
@@ -141,7 +141,7 @@
  /* SCROLLSPY DATA-API
   * ================== */
 
-  $(function () {
+  $(window).on('load', function () {
     $('[data-spy="scroll"]').each(function () {
       var $spy = $(this)
       $spy.scrollspy($spy.data())

js/bootstrap-tab.js

@@ -26,7 +26,7 @@
  /* TAB CLASS DEFINITION
   * ==================== */
 
-  var Tab = function ( element ) {
+  var Tab = function (element) {
     this.element = $(element)
   }
 

js/tests/index.html

@@ -27,6 +27,7 @@
   <script src="../../js/bootstrap-tooltip.js"></script>
   <script src="../../js/bootstrap-popover.js"></script>
   <script src="../../js/bootstrap-typeahead.js"></script>
+  <script src="../../js/bootstrap-affix.js"></script>
 
   <!-- unit tests -->
   <script src="unit/bootstrap-transition.js"></script>
@@ -41,6 +42,7 @@
   <script src="unit/bootstrap-tooltip.js"></script>
   <script src="unit/bootstrap-popover.js"></script>
   <script src="unit/bootstrap-typeahead.js"></script>
+  <script src="unit/bootstrap-affix.js"></script>
 </head>
 <body>
   <div>

js/tests/unit/bootstrap-affix.js

@@ -0,0 +1,25 @@
+$(function () {
+
+    module("bootstrap-affix")
+
+      test("should be defined on jquery object", function () {
+        ok($(document.body).affix, 'affix method is defined')
+      })
+
+      test("should return element", function () {
+        ok($(document.body).affix()[0] == document.body, 'document.body returned')
+      })
+
+      test("should exit early if element is not visible", function () {
+        var $affix = $('<div style="display: none"></div>').affix()
+        $affix.data('affix').checkPosition()
+        ok(!$affix.hasClass('affix'), 'affix class was not added')
+      })
+
+      test("should add affix class if scrolled to correct position", function () {
+        var $affix = $('<div></div>').appendTo('body').affix()
+        $('body').trigger('scroll')
+        ok($affix.hasClass('affix'), 'element has class affix')
+      })
+
+})

less/utilities.less

@@ -24,3 +24,7 @@
 .invisible {
   visibility: hidden;
 }
+
+.affix {
+  position: fixed;
+}