index.mustache revision e808b8824ca1091c8efb5669db9129e68e5e1c14
0N/A <p>ScrollView's main use case is to provide a scrollable content widget for touch devices on which overflow scrollbars are not natively supported. However, it is built on top of YUI's cross-platform/browser gesture and transition layers, so it can also be used to provide flickable scrolling on mouse-based devices across on all the A-grade browsers.</p>
0N/A <p>The `ScrollViewScrollbars` plugin can be added to the base scrollview to provide a scroll indicator. The `ScrollViewPaginator` plugin can be added to provide a cross-platform paginated scrolling implementation (a simple carousel).</p>
0N/A<p>`ScrollView` extends the `Widget` class, and hence follows the same pattern as any widget constructor, accepting a configuration object to set the initial configuration for the widget.</p>
0N/A<p>A ScrollView widget is instantiated from markup by specifying the `srcNode` which contains the content to be scrolled. The content is usually in the form of a list, but doesn't necessarily have to be:</p>
0N/A<p>The `yui3-scrollview-loading` class is applied by the developer to progressively enhanced markup, and can be used along with the `yui3-js-enabled` class applied to the document element, to hide the scrollview markup from view, while the JS is being loaded. The examples show how to set up a `yui3-scrollview-loading` rule to hide progressively enhanced content.</p>
0N/A<p>When instantiating from markup, a reference to the `srcNode` is provided to the constructor as part of the configuration object. This reference can be a node reference, or a selector string which can be used to identify the node. If the selector string is too broad (returns multiple nodes), the first node found will be used.
0N/A var scrollview = new Y.ScrollView({
0N/A<p>Generally, a ScrollView widget will be scrollable either horizontally (along the X axis) or vertically (along the Y axis). The ScrollView determines which direction it can scroll in based on whether or not its content is taller (vertically scrolled) or wider (horizontally scrolled) than its height or width respectively, as you would expect
0N/Afrom native overflow handling. In the above example the widget is given a fixed height, so that it will scroll vertically, when the content gets larger than the specified height. In most use cases you will provide either a height or a width to the ScrollView widget constructor.</p>
0N/A<p>Following instantiation, a call to `render` is required to have the ScrollView's state reflected in the DOM, as with all YUI 3 widgets:</p>
0N/A var scrollview = new Y.ScrollView({ ... });
0N/A<p>ScrollView provides the following core attributes, in addition to the attributes provided by the base <a href="../widget/index.html#attributes">Widget</a> class:</p>
0N/A <tr><td>`scrollX`</td><td>The number of pixels to scroll the widget's content by, along the X axis (vertically).</td></tr>
0N/A <tr><td>`scrollY`</td><td>The number of pixels to scroll the widget's content by, along the Y axis (horizontally).</td></tr>
0N/A<p>Additionally, the following attributes control the sensitivity and scroll dynamics, per instance:</p>
0N/A <tr><td>`flick`</td><td>An object which specifies the minimum distance and minimum velocity (in pixels/ms - generally around 0.5) which should constitute a flick gesture. Can be set to false to disable flick support, in which case the ScrollView content can only be dragged to scroll it.</td><td>`{minDistance:10, minVelocity:0.3}`</td></tr>
0N/A <tr><td>`deceleration`</td><td>A drag coefficient, which defines how quickly the velocity of the scrollview content decreases after a flick, when it's still with in the min and max bounds for the widget. The closer this is to 1, the less friction there is after a flick.</td><td>`0.98`</td></tr>
0N/A <tr><td>`bounce`</td><td>A drag coefficient, which defines how quickly the velocity of the scrollview content decreases after a flick, when it's past the min and max bounds for the widget. Can be set to 0 to disable bounce behavior.</td><td>`0.1`</td></tr>
0N/A<p>The following properties are provided as static properties and can be used to define default values affecting scroll dynamics for all ScrollViews on the page:</p>
0N/A <tr><td>`Y.ScrollView.BOUNCE_RANGE`</td><td>The default bounce distance in pixels.</td><td>`150`</td></tr>
0N/A <tr><td>`Y.ScrollView.FRAME_STEP`</td><td>The default time interval used when animating the flick deceleration.</td><td>`30`</td></tr>
0N/A <tr><td>`Y.ScrollView.EASING`</td><td>The default easing used when scrolling to a given X or Y.</td><td>`cubic-bezier(0, 0.1, 0, 1.0)`</td></tr>
0N/A <tr><td>`Y.ScrollView.SNAP_EASING`</td><td>The default easing used for the snap back animation when scrolled past the min or max bounds for the widget.</td><td>`ease-out`</td></tr>
0N/A<p>The final rendered ScrollView has the markup structure shown below (shown for a vertical scrollview):</p>
0N/A <!-- Content Box, which is scrolled using either top/left, or transform:translate, where supported -->
0N/A <!-- Scrollbar indicator, if Scrollbar Plugin is added (added by default for the "scrollview" module) -->
0N/A<p>The `yui3-scrollview-vert`, or `yui3-scrollview-horiz` classes applied to the bounding box can be used to style the scrollview based on its scroll orientation.</p>
0N/A<p>The core structural css for the ScrollView is shown below, and is pretty straightforward. It simply sets up the bounding box and the content box as positioned elements, and sets overflow hidden, so that the
0N/A<p>Since the scrollable content is commonly set up as a list (for semantic reasons), the core css for ScrollView also ships with a rule targeting list items (`LI`s), so that list content works out of the box, for both vertical and horizontal scrollviews (inline-block is used so that we can trivially support the horizontal use case):</p>
0N/A<p>The above rules can of course be over-ridden for cases in which you don't want lists inside ScrollView handled specially.</p>
0N/A<p>The ScrollBar plugin provides a visual scroll indicator to let the user know how much scrollable content there is, and the current scroll position they're at.</p>
0N/A<p>When using the `scrollview` module, the `ScrollViewScrollbars` plugin is automatically pulled down and plugged in for all ScrollView instances (plugged in at the class level).</p>
0N/A<p>However, the user can also choose to pull down just the base scrollview module (`scrollview-base`) and add scrollbar support optionally (when and if required).</p>
0N/A var scrollview = new Y.ScrollView({
0N/A scrollview.scrollbars is an instance of the ScrollViewScrollbars
0N/A<p>When the `ScrollViewScrollbars` plugin is plugged in to a ScrollView instance, a `scrollbars` property (the namespace for the plugin) is added to the ScrollView instance, which points to an instance of the plugin, as shown above. The plugin provides public `hide()`, `show()` and `flash()` methods for the scroll indicator.</p>
0N/A<p>The `ScrollViewPaginator` plugin adds pagination support to ScrollView, so that it recognizes, and stops at, discrete page boundaries within its content, as opposed to scrolling continuously (it effectively makes ScrollView behave like a simple Carousel).</p>
0N/A<p>Adding the `scrollview-paginator` module to the `use` statement will pull down and add the `Plugin.ScrollViewPaginator` plugin class to the YUI instance. It can then be plugged in to ScrollView instances requiring pagination support, as shown below:</p>
0N/A var scrollview = new Y.ScrollView({
0N/A scrollview.pages is an instance of the ScrollViewPaginator
0N/A scrollview.pages.set("index", 3);
0N/A scrollview.pages.scrollTo(3, 0.6, "ease-in");
0N/A scrollview.pages.get("total");
0N/A<p>The paginator plugin accepts a `selector` attribute as part of its configuration, which selects the list of elements to be used to establish page boundaries. In the example above, each `LI` within the ScrollView's content box, defines a <em>page</em> in the ScrollView.</p>