angular-slides
AngularJS directive for vertical, fullscreen, slide-based web pages.
Overview
The goal of this project is to easily allow layouts with the following features:
- the page is divided into a vertical sequence of slides
- each slide is fullscreen, i.e. it spans the whole viewport
- users can't (directly) scroll: up and down arrow key are used to change slide (with scrolling performed programmatically in JavaScript)
- indvidual slides can be linked
Also, events are fired to signal slide changes, which is useful to hide, reveal and animate stuff.
Getting started
Adding angular-slides to your project
Use npm:
$ npm install angular-slides
or Bower:
$ bower install msl-slides
Then, inside your HTML page:
<!-- AngularJS is the only required dependency -->
Note: If you're using Bower, just replace node_modules
with
bower_components
and angular-slides
with msl-slides
.
Note: The demo
folder of this repository contains a working example.
Another useful example is
this project's website.
Using the mslSlides directive
Basics
First slide Second slide Third slide
Note: CSS styling is up to you. The only style added by the mslSlides
directive is 100vw
width and 100vh
height to each slide.
Note: Remember to load the msl.slides
module into your AngularJS app,
e.g.:
var myApp = angular;
Links
First slide Go to next slide Second slide
Events
First slide Second slide
angular;
API
If you're not happy with the previous examples, here is a bunch of detailed informations that will hold true (until breaking changes):
- the
mslSlides
directive is hosted inside an AngularJS module calledmsl.slides
- slides must be put inside the
<msl-slides>
element - a slide can be any HTML element (although inline elements don't make sense)
- slides are numbered starting from
0
- the
mslSlides
directive applies100vw
width and100vh
height to each slide - slide change is performed with up and down arrow keys
- a
msl_slides_slide_change_start
AngularJS event is emitted when a slide change starts - a
msl_slides_slide_change_success
AngularJS event is emitted when a slide change is successfully completed msl_slides_slide_change_start
andmsl_slides_slide_change_success
handlers receive the "previous" and the "next" slide numbers (i.e. before and after the slide change) as second and third argument, e.g.function myHandler(event, old_slide, new_slide) { ... }
- the
slide_number
query parameter in the address bar is kept in sync with the current slide number (synchronization happens when the animation completes) - thus, slide changes can be driven by links too
All other behaviors are to be intended as implementation-specific and should not be depended on.
For contributors
Source code is divided into many files inside the src
directory. Here is
a short description of these files' responsibilities:
src/module.js
: provides the module that will host all the other componentssrc/directive/slides.js
: defines themsl-slides
directivesrc/service/scroll_detector.js
: handleswheel
andkeydown
events in order to prevent regular scrolling and detect the user's will to scroll through up and down arrow keyssrc/service/scroller.js
: implements a sort of animated scrollingsrc/service/config.js
: just a couple of values that control the animated scrollingsrc/service/location.js
: sets and gets the slide number from$location
src/service/viewport.js
: converts slide numbers into pixel offsets
Development tasks are handled with Grunt:
grunt test
: run testsgrunt build
: concat + minify (output inside thedist
folder)
Development dependencies are handled with npm
.