ui-scroll-panels

Library to enable scrolling between panels, similar to sliders, carousels, and some HTML presentation frameworks.

Here, the goal is a simple API which works for one or many panels.

Example

var scroll = uiScrollPanels()
	.select( '.main' )
	.init();

Note: each scrollable panel requires its own scroll instance. Hence, do not

var scroll = uiScrollPanels();

scroll.select( '.container-1' )
	.init();

scroll.select( '.container-2' )
	.init();

This will lead to container-1 controls to affect container-2 panels. Switching the context is possible using the select method, but this is only advised when programmatically scrolling between panels.

Instead,

var scroll1 = uiScrollPanels()
	.select( 'container-1' )
	.init();

var scroll2 = uiScrollPanels()
	.select( 'container-2' )
	.init();

API

To enable scrolling between panels, one must first create a scroll panel instance. To do so,

var scroll = uiScrollPanels();

Scroll panels are configurable and have the following methods...

scroll.select( selector )

This method selects and initializes a panel container. If scroll controls do not already exist in the container, they are inserted. By using select, one is able to determine the panel context for scrolling.

scroll.select( '.container-1' );
// Any UI interaction affects panels in container `.container-1`

scroll.select( '.container-2' );
// Any UI interaction now affects panels in container `.container-2`

scroll.current( [idx] )

This method is a setter/getter. If no index is provided, returns the current panel index. To set the current panel index,

scroll.current( 2 );

Note: for the moment, this only affects future scrolls. Jumping to the desired panel is on the project roadmap.

scroll.init()

This method initializes a scroll layout by adding event listeners and hiding all panels beside the current panel (default: 0).

scroll.init();

scroll.scroll( direction[, clbk] )

This method provides a programmatic means to scroll between panels. A callback may be provided which is invoked after scroll end.

Currently, only left and right directions are supported.

scroll.scroll( 'left', function onEnd() {
	console.log( 'beep!' );	
});

Shortcuts

h, left: scroll left
l, right: scroll right
k, up: scroll up (not yet supported)
j, down: scroll down (not yet supported)

Notes

If multiple scroll containers are present, shortcuts currently affect all scroll containers; e.g., a left keypress will cause all scroll containers to scroll left.

===

Browserify

To recompile a client-side library, use browserify. The following command will compile (from the top-level project directory) a standalone client-side script and place in the dist directory.

browserify './lib/index.js' -s uiScrollPanels -o './dist/ui-scroll-panels.js'

If no module systems are found, uiScrollPanels will be bound to the window global.

Tests

WARNING: unit and functional tests are fairly non-existent at the moment.

Unit

Unit tests use the Mocha test framework with Chai assertions.

Assuming you have installed Mocha,

$ npm install -g mocha

execute the following command in the top-level application directory to run the tests:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

Assuming you have installed Istanbul,

$ npm install -g istanbul

execute the following command to generate a test coverage report:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ open reports/coverage/lcov-report/index.html

kgryte/ui-scroll-panels