|
| 1 | +<!doctype html> |
| 2 | +<html lang="en"> |
| 3 | +<head> |
| 4 | + <meta charset="utf-8"> |
| 5 | + <meta name="viewport" content="width=device-width"> |
| 6 | + <title>jQuery Smooth Scroll Plugin</title> |
| 7 | + <style> |
| 8 | + html, |
| 9 | + body { |
| 10 | + margin: 0; |
| 11 | + padding: 0; |
| 12 | + border-width: 0; |
| 13 | + } |
| 14 | + body { |
| 15 | + font-family: "Helvetica Neue", Helvetica, Arial, sans-serif; |
| 16 | + width: 94%; |
| 17 | + margin: 0 auto; |
| 18 | + padding: 0 3%; |
| 19 | + max-width: 1120px; |
| 20 | + font-size: 1em; |
| 21 | + line-height: 1.5; |
| 22 | + background-color: #fff; |
| 23 | + color: #242424; |
| 24 | + } |
| 25 | + pre { |
| 26 | + background-color: #f3f3f3; |
| 27 | + padding: .25em; |
| 28 | + border: 1px solid #ccc; |
| 29 | + font-size: .9em; |
| 30 | + overflow: auto; |
| 31 | + } |
| 32 | + code { |
| 33 | + font-family: Monaco, Courier, monospace; |
| 34 | + } |
| 35 | + h1, h2, h3 { |
| 36 | + font-weight: normal; |
| 37 | + color: #141414; |
| 38 | + } |
| 39 | + h2 { |
| 40 | + padding-bottom: .2em; |
| 41 | + border-bottom: 1px solid #ccc; |
| 42 | + } |
| 43 | + .right { |
| 44 | + float: right; |
| 45 | + } |
| 46 | + </style> |
| 47 | +</head> |
| 48 | +<body> |
| 49 | + |
| 50 | +<div class="right"><a href="demo/index.html">Demo</a></div> |
| 51 | +<h1>Smooth Scroll Plugin</h1> |
| 52 | +<h2>Features</h2> |
| 53 | +<h3>$.fn.smoothScroll</h3> |
| 54 | +<ul> |
| 55 | +<li>Allows for easy implementation of smooth scrolling for same-page links.</li> |
| 56 | +<li>Works like this: <code>$('a').smoothScroll();</code></li> |
| 57 | +<li>Specify a containing element if you want: <code>$('#container a').smoothScroll();</code></li> |
| 58 | +<li>Exclude links if they are within a containing element: <code>$('#container a').smoothScroll({excludeWithin: ['.container2']});</code></li> |
| 59 | +<li>Exclude links if they match certain conditions: <code>$('a').smoothScroll({exclude: ['.rough','#chunky']});</code></li> |
| 60 | +<li>Adjust where the scrolling stops: <code>$('.backtotop').smoothScroll({offset: -100});</code></li> |
| 61 | +<li>Add a callback function that is triggered before the scroll starts: `$('a').smoothScroll({beforeScroll: function() { alert('ready to go!'); }});</li> |
| 62 | +<li>Add a callback function that is triggered after the scroll is complete: <code>$('a').smoothScroll({afterScroll: function() { alert('we made it!'); }});</code></li> |
| 63 | +<li>Add back button support by including a history management plugin such as <a href="http://benalman.com/code/projects/jquery-bbq/docs/files/jquery-ba-bbq-js.html">Ben Alman's BBQ</a>. See <a href="demo/bbq.html">demo/bbq.html</a> for an example of how to implement this.</li> |
| 64 | +</ul> |
| 65 | +<h4>Options</h4> |
| 66 | +<p>The following options, shown with their default values, are available for both <code>$.fn.smoothScroll</code> and <code>$.smoothScroll</code>:</p> |
| 67 | +<pre><code class="lang-javascript">{ |
| 68 | + offset: 0, |
| 69 | + |
| 70 | + // one of 'top' or 'left' |
| 71 | + direction: 'top', |
| 72 | + |
| 73 | + // only use if you want to override default behavior |
| 74 | + scrollTarget: null, |
| 75 | + |
| 76 | + // fn(opts) function to be called before scrolling occurs. |
| 77 | + // `this` is the element(s) being scrolled |
| 78 | + beforeScroll: function() {}, |
| 79 | + |
| 80 | + // fn(opts) function to be called after scrolling occurs. |
| 81 | + // `this` is the triggering element |
| 82 | + afterScroll: function() {}, |
| 83 | + easing: 'swing', |
| 84 | + speed: 400, |
| 85 | + |
| 86 | + // coefficient for "auto" speed |
| 87 | + autoCoefficent: 2 |
| 88 | + |
| 89 | +}</code></pre> |
| 90 | +<p>The options object for <code>$.fn.smoothScroll</code> can take two additional properties: |
| 91 | +<code>exclude</code> and <code>excludeWithin</code>. The value for both of these is an array of |
| 92 | +selectors, DOM elements or jQuery objects. Default value for both is an |
| 93 | +empty array.</p> |
| 94 | +<h3>$.smoothScroll</h3> |
| 95 | +<ul> |
| 96 | +<li>Utility method works without a selector: <code>$.smoothScroll()</code></li> |
| 97 | +<li>Can be used to scroll any element (not just <code>document.documentElement</code> / |
| 98 | +<code>document.body</code>)</li> |
| 99 | +<li><p>Doesn't automatically fire, so you need to bind it to some other user |
| 100 | +interaction. For example:</p> |
| 101 | +<pre><code> $('button.scrollsomething').on('click', function() { |
| 102 | + $.smoothScroll({ |
| 103 | + scrollElement: $('div.scrollme'), |
| 104 | + scrollTarget: '#findme' |
| 105 | + }); |
| 106 | + return false; |
| 107 | + });</code></pre> |
| 108 | +</li> |
| 109 | +<li><p>The <code>$.smoothScroll</code> method can take one or two arguments.</p> |
| 110 | +<ul> |
| 111 | +<li>If the first argument is a number, the document is scrolled to that |
| 112 | +position. If it's an options object, those options determine how the |
| 113 | +document (or other element) will be scrolled.</li> |
| 114 | +<li>If a number is provided as the second argument, it will override whatever may have been set for the <code>scrollTarget</code> option.</li> |
| 115 | +</ul> |
| 116 | +</li> |
| 117 | +</ul> |
| 118 | +<h4>Additional Option</h4> |
| 119 | +<p>The following option, in addition to those listed for <code>$.fn.smoothScroll</code> above, is available |
| 120 | +for <code>$.smoothScroll</code>:</p> |
| 121 | +<pre><code class="lang-javascript">{ |
| 122 | + // jQuery set of elements you wish to scroll. |
| 123 | + // if null (default), $('html, body').firstScrollable() is used. |
| 124 | + scrollElement: null, |
| 125 | +}</code></pre> |
| 126 | +<h3>$.fn.scrollable</h3> |
| 127 | +<ul> |
| 128 | +<li>Selects the matched element(s) that are scrollable. Acts just like a |
| 129 | +DOM traversal method such as <code>.find()</code> or <code>.next()</code>.</li> |
| 130 | +<li>The resulting jQuery set may consist of <strong>zero, one, or multiple</strong> |
| 131 | +elements.</li> |
| 132 | +</ul> |
| 133 | +<h3>$.fn.firstScrollable</h3> |
| 134 | +<ul> |
| 135 | +<li>Selects the first matched element that is scrollable. Acts just like a |
| 136 | +DOM traversal method such as <code>.find()</code> or <code>.next()</code>.</li> |
| 137 | +<li>The resulting jQuery set may consist of <strong>zero or one</strong> element.</li> |
| 138 | +<li>This method is used <em>internally</em> by the plugin to determine which element |
| 139 | +to use for "document" scrolling: |
| 140 | +<code>$('html, body').firstScrollable().animate({scrollTop: someNumber}, |
| 141 | +someSpeed)</code></li> |
| 142 | +</ul> |
| 143 | +<h2>Notes</h2> |
| 144 | +<ul> |
| 145 | +<li>To determine where to scroll the page, the <code>$.fn.smoothScroll</code> method looks |
| 146 | +for an element with an <em>id</em> attribute that matches the <code><a></code> element's hash. |
| 147 | +It does <em>not</em> look at the element's <em>name</em> attribute. If you want a clicked link |
| 148 | +to scroll to a "named anchor" (e.g. <code><a name="foo"></code>), you'll need to use the |
| 149 | +<code>$.smoothScroll</code> method instead.</li> |
| 150 | +<li>The plugin's <code>$.fn.smoothScroll</code> and <code>$.smoothScroll</code> methods use the |
| 151 | +<code>$.fn.firstScrollable</code> DOM traversal method (also defined by this plugin) |
| 152 | +to determine which element is scrollable. If no elements are scrollable, |
| 153 | +these methods return a jQuery object containing an empty array, just like |
| 154 | +all of jQuery's other DOM traversal methods. Any further chained methods, |
| 155 | +therefore, will be called against no elements (which, in most cases, |
| 156 | +means that nothing will happen).</li> |
| 157 | +</ul> |
| 158 | + |
| 159 | +</body> |
| 160 | +</html> |
0 commit comments