diff options
Diffstat (limited to 'docs/javascript/affix.md')
| -rw-r--r-- | docs/javascript/affix.md | 182 |
1 files changed, 92 insertions, 90 deletions
diff --git a/docs/javascript/affix.md b/docs/javascript/affix.md index 46bee00d7..f588f49ba 100644 --- a/docs/javascript/affix.md +++ b/docs/javascript/affix.md @@ -3,29 +3,29 @@ layout: page title: Affix --- -<div class="bs-docs-section"> - <h1 id="affix" class="page-header">Affix <small>affix.js</small></h1> +## Example - <h2 id="affix-examples">Example</h2> - <p>The subnavigation on the right is a live demo of the affix plugin.</p> +The subnavigation on the right is a live demo of the affix plugin. - <hr class="bs-docs-separator"> +## Usage - <h2 id="affix-usage">Usage</h2> - <p>Use the affix plugin via data attributes or manually with your own JavaScript. <strong class="text-danger">In both situations, you must provide CSS for the positioning and width of your affixed content.</strong></p> +Use the affix plugin via data attributes or manually with your own JavaScript. **In both situations, you must provide CSS for the positioning and width of your affixed content.** - <h3>Positioning via CSS</h3> - <p>The affix plugin toggles between three classes, each representing a particular state: <code>.affix</code>, <code>.affix-top</code>, and <code>.affix-bottom</code>. You must provide the styles for these classes yourself (independent of this plugin) to handle the actual positions.</p> - <p>Here's how the affix plugin works:</p> - <ol> - <li>To start, the plugin adds <code>.affix-top</code> to indicate the element is in its top-most position. At this point no CSS positioning is required.</li> - <li>Scrolling past the element you want affixed should trigger the actual affixing. This is where <code>.affix</code> replaces <code>.affix-top</code> and sets <code>position: fixed;</code> (provided by Bootstrap's code CSS).</li> - <li>If a bottom offset is defined, scrolling past that should replace <code>.affix</code> with <code>.affix-bottom</code>. Since offsets are optional, setting one requires you to set the appropriate CSS. In this case, add <code>position: absolute;</code> when necessary. The plugin uses the data attribute or JavaScript option to determine where to position the element from there.</li> - </ol> - <p>Follow the above steps to set your CSS for either of the usage options below.</p> +### Position via CSS - <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. Use offsets to define when to toggle the pinning of an element.</p> +The affix plugin toggles between three classes, each representing a particular state: `.affix`, `.affix-top`, and `.affix-bottom`. You must provide the styles for these classes yourself (independent of this plugin) to handle the actual positions. + +Here's how the affix plugin works: + +- To start, the plugin adds `.affix-top` to indicate the element is in its top-most position. At this point no CSS positioning is required. +- Scrolling past the element you want affixed should trigger the actual affixing. This is where `.affix` replaces `.affix-top` and sets `position: fixed;` (provided by Bootstrap's code CSS). +- If a bottom offset is defined, scrolling past that should replace `.affix` with `.affix-bottom`. Since offsets are optional, setting one requires you to set the appropriate CSS. In this case, add `position: absolute;` when necessary. The plugin uses the data attribute or JavaScript option to determine where to position the element from there. + +Follow the above steps to set your CSS for either of the usage options below. + +### Via data attributes + +To easily add affix behavior to any element, just add `data-spy="affix"` to the element you want to spy on. Use offsets to define when to toggle the pinning of an element. {% highlight html %} <div data-spy="affix" data-offset-top="60" data-offset-bottom="200"> @@ -33,8 +33,10 @@ title: Affix </div> {% endhighlight %} - <h3>Via JavaScript</h3> - <p>Call the affix plugin via JavaScript:</p> +### Via JavaScript + +Call the affix plugin via JavaScript: + {% highlight js %} $('#my-affix').affix({ offset: { @@ -47,74 +49,74 @@ title: Affix {% endhighlight %} - <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-top="200"</code>.</p> - - <div class="table-responsive"> - <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 | function | object</td> - <td>10</td> - <td>Pixels to offset from screen when calculating position of scroll. If a single number is provided, the offset will be applied in both top and bottom directions. To provide a unique, bottom and top offset just provide an object <code>offset: { top: 10 }</code> or <code>offset: { top: 10, bottom: 5 }</code>. Use a function when you need to dynamically calculate an offset.</td> - </tr> - <tr> - <td>target</td> - <td>selector | node | jQuery element</td> - <td>the <code>window</code> object</td> - <td>Specifies the target element of the affix.</td> - </tr> - - </tbody> - </table> - </div><!-- /.table-responsive --> - - - <h3>Events</h3> - <p>Bootstrap's affix class exposes a few events for hooking into affix functionality.</p> - <div class="table-responsive"> - <table class="table table-bordered table-striped"> - <thead> - <tr> - <th style="width: 150px;">Event Type</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>affix.bs.affix</td> - <td>This event fires immediately before the element has been affixed.</td> - </tr> - <tr> - <td>affixed.bs.affix</td> - <td>This event is fired after the element has been affixed.</td> - </tr> - <tr> - <td>affix-top.bs.affix</td> - <td>This event fires immediately before the element has been affixed-top.</td> - </tr> - <tr> - <td>affixed-top.bs.affix</td> - <td>This event is fired after the element has been affixed-top.</td> - </tr> - <tr> - <td>affix-bottom.bs.affix</td> - <td>This event fires immediately before the element has been affixed-bottom.</td> - </tr> - <tr> - <td>affixed-bottom.bs.affix</td> - <td>This event is fired after the element has been affixed-bottom.</td> - </tr> - </tbody> - </table> - </div><!-- /.table-responsive --> +### Options + +Options can be passed via data attributes or JavaScript. For data attributes, append the option name to `data-`, as in `data-offset-top="200"`. + +<div class="table-responsive"> + <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 | function | object</td> + <td>10</td> + <td>Pixels to offset from screen when calculating position of scroll. If a single number is provided, the offset will be applied in both top and bottom directions. To provide a unique, bottom and top offset just provide an object <code>offset: { top: 10 }</code> or <code>offset: { top: 10, bottom: 5 }</code>. Use a function when you need to dynamically calculate an offset.</td> + </tr> + <tr> + <td>target</td> + <td>selector | node | jQuery element</td> + <td>the <code>window</code> object</td> + <td>Specifies the target element of the affix.</td> + </tr> + </tbody> + </table> +</div> + +### Events + +Bootstrap's affix class exposes a few events for hooking into affix functionality. + +<div class="table-responsive"> + <table class="table table-bordered table-striped"> + <thead> + <tr> + <th style="width: 150px;">Event Type</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>affix.bs.affix</td> + <td>This event fires immediately before the element has been affixed.</td> + </tr> + <tr> + <td>affixed.bs.affix</td> + <td>This event is fired after the element has been affixed.</td> + </tr> + <tr> + <td>affix-top.bs.affix</td> + <td>This event fires immediately before the element has been affixed-top.</td> + </tr> + <tr> + <td>affixed-top.bs.affix</td> + <td>This event is fired after the element has been affixed-top.</td> + </tr> + <tr> + <td>affix-bottom.bs.affix</td> + <td>This event fires immediately before the element has been affixed-bottom.</td> + </tr> + <tr> + <td>affixed-bottom.bs.affix</td> + <td>This event is fired after the element has been affixed-bottom.</td> + </tr> + </tbody> + </table> </div> |