Class: ScrollZoneWidget

PR. ScrollZoneWidget

Scrollzone provides vertical and horizontal scrolling functionality through use of a custom implementation of the iScroll library.

This class could be extended to make use of some of the additional events that iScroll triggers by adding a function for the event and then passing that function as a parameter to this.scrollInstance_ within the this.createScroller_() function.

Most of the parameters for the Scrollzone widget are optional but there are some requirements for the construction of the HTML necessary to implement the widget. The widget requires a wrapping element that specifies the widget and then requires two further child elements that define the size of the scrollable area and the content respectively. The first child elements’ size should match that of the widget element (the size should be specified in the styles). Content will 'flow' vertically so to create a scroll area that scrolls hotizontally the content element should be specified as the 'widest' of the elements. See horizontal scrolling example.

Whilst the primary use-case for the scrollzone widget is to display additional copy text (or images in a block of copy) any elements (including other widgets) could be placed into a scrollable widget.

The first example is shown with inline styles to show the sizing - note that the recommendation is to include this styling in an external stylesheet.

HTML Parameters

The following parameters are required.

data-widget="SCROLLZONE" Required
The identifier for the widget type.

The following parameters are optional (defaults are listed between the braces), note also that the parameters for this widget are strings.

id="{{id}}" Optional
It is usually preferable to include a unique ID but it is not strictly necessary.
data-scrollbarH="{{true}}" Optional
true || false. Specifies visibility of the horizontal scrollbar.
data-scrollbarV="{{true}}" Optional
true || false. Specifies visibility of the vertical scrollbar.
data-arrows="{{false}}" Optional
true || false. Specifies visibility of the scroll arrows - scroll arrows appear when there is additional content and disappear when you reach the bounds of the scrollable area.
data-arrow-image="{{string}}" Optional
Path to the location of the arrow image. The arrow image gets rotated for each direction, the image used should render the arrow in the up position.
data-position="{{Top or left}}" Optional
Top or left || Bottom or right. Specifies the initial location of the content within the scrollzone.

Examples

Base Vertically Scrolling Implementation
The following example shows the HTML specifying a Scrollzone widget that scrolls vertically to display additional content. Note that the inline styles presented here are representative of the structure of sizing required to initialise the widget correctly—for a vertically scrolling scrollzone the height and width of the widget element and it’s immediate child should be specified.

id Optional
A unique id for the HTML element.
data-widget="SCROLLZONE" Required
Scrollzone Widget identifier.
<div style="width:500px; height:300px; position:relative; left:200px; top:100px;"
    data-widget="SCROLLZONE">
    <div style="width:500px; height:300px;">
        <div>
            <!-- Content omitted for brevity -->
        </div>
    </div>
</div>

Base Horizontally Scrolling Implementation
This example shows a horizontally scrolling scrollzone. The only difference from the vertical scrolling widget is that the content specifies it’s size as wider than the widget width—if the content does not fit into the wider content area then it will continue to flow 'down' the page as normal and the scrollzone will also vertically scroll.

id Optional
A unique id for the HTML element.
data-widget="SCROLLZONE" Required
Scrollzone Widget identifier.
<div style="width:500px; height:300px; position:relative; left:200px; top:100px;"
    data-widget="SCROLLZONE">
    <div style="width:500px; height:300px;">
        <div style="width:900px">
            <!-- Content omitted for brevity -->
        </div>
    </div>
</div>

Scrollzone with scrolling arrows
The following example adds scroll arrows to the basic vertical implementation. Scroll arrows are only visible when there is additional content in their direction, when you hit the top or bottom of this scrollzone the arrows will disappear.

Note that using arrows for a horizontal and vertical scrollable area will result in a conflict where the down arrow and the right arrow will attempt to render in the same location.

id Optional
A unique id for the HTML element.
data-widget="SCROLLZONE" Required
Scrollzone Widget identifier.
data-arrows="true" Required
Apply arrows.
data-arrow-image="{{src}}" Required
The path to the arrow image.
 <div style="width:500px; height:300px; position:relative; left:200px; top:100px;"
    data-widget="SCROLLZONE"
    data-arrows="true"
    data-arrow-image="../assets/scrollarrow.png">
    <div style="width:500px; height:300px;">
        <div>
            <!-- Content omitted for brevity -->
        </div>
    </div>
</div>
Author:
  • AppStudio Widgets
Source:
  • widgets/ScrollZoneWidget.js, line 2

Extends

  • PR.BaseWidget

Members

arrowImageString

Relative path to the image assset to be used as the arrow graphic

Source:
  • widgets/ScrollZoneWidget.js, line 221

arrowsString

Should the widget automatically add arrows on to indicate ability to scroll (note this is a string, not a boolean).

Source:
  • widgets/ScrollZoneWidget.js, line 215

contentWrapperElObject

The DOM Element this containing wrapping the scrollable content

Source:
  • widgets/ScrollZoneWidget.js, line 175

doesHorizontalScroll_Boolean

Is this scrollzone providing horizontal scroll to the content

Source:
  • widgets/ScrollZoneWidget.js, line 155

doesVerticalScroll_Boolean

Is this scrollzone providing vertical scroll to the content

Source:
  • widgets/ScrollZoneWidget.js, line 149

downArrowElElement

Our 'Down Arrow' DOM element used for the auto arrows functionality

Source:
  • widgets/ScrollZoneWidget.js, line 233

elObject

The DOM Element this Widget is attached too

Source:
  • widgets/ScrollZoneWidget.js, line 169

fadeHeightString

The size in PX of the fade effect indictating end of content

Source:
  • widgets/ScrollZoneWidget.js, line 190

hasMovedBoolean

Holds whether there has been an actual movement (to prevent page swiping)

Source:
  • widgets/ScrollZoneWidget.js, line 280

hideScrollbarsString

Should scrollbars be hidden and shown on focus?

Default Value:
  • false
Source:
  • widgets/ScrollZoneWidget.js, line 209

leftArrowElElement

Our 'Left Arrow' DOM element used for the auto arrows functionality

Source:
  • widgets/ScrollZoneWidget.js, line 240

pageSwipeBoolean

Holds whether the gesture is a candidate for a page navigation event

Source:
  • widgets/ScrollZoneWidget.js, line 273

positionString

Should the content scroll start position to 'Top or Left' or 'Bottom and Right'

Source:
  • widgets/ScrollZoneWidget.js, line 252

rightArrowElElement

Our 'Right Arrow' DOM element used for the auto arrows functionality

Source:
  • widgets/ScrollZoneWidget.js, line 246

scrollableContentElObject

The DOM Element this containing the scrollable content

Source:
  • widgets/ScrollZoneWidget.js, line 181

scrollbarhString

Should horizontal scrollbars be visible

Source:
  • widgets/ScrollZoneWidget.js, line 196

scrollbarvString

Should vertical scrollbars be visible

Source:
  • widgets/ScrollZoneWidget.js, line 202

scrollInstance_

Create the iscroll instance

Some of these options are legacy and updates to iscroll can change their name or meaning.
Although we specify each scrollbar (h or v), iscroll scrollbars are either on or off so if
either scrollbar is set to off then we display neither.

Source:
  • widgets/ScrollZoneWidget.js, line 468

startPosObject

The start position (on the screen) of the gesture/interaction

Source:
  • widgets/ScrollZoneWidget.js, line 258

swipeDistNumber

The tolerance of a swipe gesture, movement must be above this to count as a swipe. in pixels.

Source:
  • widgets/ScrollZoneWidget.js, line 267

upArrowElElement

Our 'Up Arrow' DOM element used for the auto arrows functionality

Source:
  • widgets/ScrollZoneWidget.js, line 228

upArrowEl

Logic all related to Auto Arrows

Source:
  • widgets/ScrollZoneWidget.js, line 497

Methods

initialize( element )

Acts like a constructor, this function triggered by default when you create an object.

Parameters:
Name Type Description
element

The HTML DOM Element which acts like a slideshow.
Throws:
Error HTML Element not attached.
Source:
  • widgets/ScrollZoneWidget.js, line 292

initVars_( )

Initialize the variables, fetch the attribute values from the mark up and assign them to instance variables.

Source:
  • widgets/ScrollZoneWidget.js, line 316
Top