1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<div class="intro">
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai{{>getting-started}}
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<h2 id="using">Using ScrollView</h2>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<h3 id="instantiating">Instantiating A ScrollView</h3>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<h4>Instantiating From Markup: Progressive Enhancement</h4>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<div id="scrollable" class="yui3-scrollview-loading">
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <li>Aerosmith</li>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <li>Bob Dylan</li>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <li>Bob Seger</li>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<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.
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen DesaiThe following code references the markup shown above, while constructing the scrollview:</p>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen DesaiYUI({...}).use("scrollview", function(Y) {
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai var scrollview = new Y.ScrollView({
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai srcNode:"#scrollable",
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai height:"20em"
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<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
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desaifrom 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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai var scrollview = new Y.ScrollView({ ... });
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<h3 id="attributes">Attributes</h3>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <tr><th>Attribute</th><th>Description</th></tr>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <tr><td>`scrollX`</td><td>The number of pixels to scroll the widget's content by, along the X axis (vertically).</td></tr>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <tr><td>`scrollY`</td><td>The number of pixels to scroll the widget's content by, along the Y axis (horizontally).</td></tr>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<p>Additionally, the following attributes control the sensitivity and scroll dynamics, per instance:</p>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <tr><th>Attribute</th><th>Description</th><th>Default</th></tr>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<h3>Static Properties Controlling Scroll Dynamics</h3>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <tr><th>Static Property</th><th>Description</th><th>Default</th></tr>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <tr><td>`Y.ScrollView.BOUNCE_RANGE`</td><td>The default bounce distance in pixels.</td><td>`150`</td></tr>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <tr><td>`Y.ScrollView.FRAME_STEP`</td><td>The default time interval used when animating the flick deceleration.</td><td>`30`</td></tr>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<h3 id="markup">Markup Structure</h3>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<p>The final rendered ScrollView has the markup structure shown below (shown for a vertical scrollview):</p>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<!-- Bounding Box, with overflow setting and fixed dimension (in this case height) -->
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<div class="yui3-widget yui3-scrollview yui3-scrollview-vert" style="height: 310px;">
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <!-- Content Box, which is scrolled using either top/left, or transform:translate, where supported -->
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <div class="yui3-scrollview-content" id="scrollable" style="left: 0px; top: 0px;">
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai ... scrollable content. generally a list ...
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <!-- Scrollbar indicator, if Scrollbar Plugin is added (added by default for the "scrollview" module) -->
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <div class="yui3-scrollview-scrollbar yui3-scrollview-scrollbar-vert">
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <span class="yui3-scrollview-child yui3-scrollview-first"></span>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <span class="yui3-scrollview-child yui3-scrollview-middle"></span>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai <span class="yui3-scrollview-child yui3-scrollview-last"></span>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<h3 id="css">CSS</h3>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<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
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desaicontent beyond the bounding box area is hidden, until scrolled into view.</p>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai/* Bounding Box */
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai.yui3-scrollview {
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai position: relative; /* To provide positioning context */
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai overflow: hidden; /* To clip scrolled content */
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai/* Content Box */
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai.yui3-scrollview-content {
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai position:relative; /* To allow positioning */
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai.yui3-scrollview-content ul {
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai.yui3-scrollview-content li {
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai list-style:none;
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai /* cross browser inline block */
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai display: -moz-inline-stack;
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai display: inline-block;
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai *display: inline;
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<p>The above rules can of course be over-ridden for cases in which you don't want lists inside ScrollView handled specially.</p>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<h3 id="scrollbars">ScrollBar Plugin</h3>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen DesaiYUI({...}).use("scrollview-base", "scrollview-scrollbars", function(Y) {
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai /* ScrollView without scrollbar indicator */
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai var scrollview = new Y.ScrollView({
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai srcNode:"#scrollable",
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai height:"20em"
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai /* Add scrollbar indicator support */
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai scrollview.plug(Y.Plugin.ScrollViewScrollbars);
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai scrollview.scrollbars is an instance of the ScrollViewScrollbars
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<h3 id="paginator">Paginator Plugin</h3>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<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>
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen DesaiYUI({...}).use("scrollview-base", "scrollview-paginator", function(Y) {
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai /* ScrollView without paginator */
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai var scrollview = new Y.ScrollView({
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai srcNode:"#scrollable",
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai height:"20em"
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai /* Plug in pagination support */
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai scrollview.plug(Y.Plugin.ScrollViewPaginator, {
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai selector: "li" // elements definining page boundaries
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai scrollview.pages is an instance of the ScrollViewPaginator
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai scrollview.pages.scrollTo(3, 0.6, "ease-in");
52df2f0673e47b3a77ac1ab47e2fd49af1ff7b5aSatyen Desai<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>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>When plugged in, the plugin API is available on the `pages` property of the scrollview widget instance, and can be used to set the current page, or retrieve paging information.</p>