Leaper is a simple javascript library to aid creation of single-page web-applications. It follows declarative way to define pages making the markings simpler and straightforward.

See it in action!

It will be improved and extended, feel free to share your wishes about it.

• it is very lightweight: only 6K
• depends on JQuery and animate.css.
• ready for large scale apps
• simple signatures and logic: one simple binding attribute and one css property to make it work
• very short learning curve: in a couple minutes you are ready to go!
• supports every major browsers: IE from v8, Chrome, Safari, FireFox, Opera
• animated transitions: 37 animations by animate.css to animate transitions
• multiplicity: you can nest page-container into other page-container or have multiple ones in a div allowing you to design menus, image galleries, tabs as pages, anynthing you want to be paged.
• callbacks: you can declare callbacks called when a page is hidden or shown or generally gone through a transition
• guards: to prevent unwanted transition, a page can be protected using guard functions
• parameters: data can be sent while transition is made. All guard and before* functions receive the parameters allowing you to react on - for example - environmental conditions
• flow-layout: pages can be ordered into a horizontal or vertical sequence to create pushed and pulled queues for cover flows or anything you want to.

Include the

leaper.min.js and leaper.min.css 

files from folder 'dist' to your project.

Define a container which will possess all pages:

<div class="l-unity" leap-bind="{ name:'bigFellow', navigate:'navigateBig' }">
</div>

The CSS class l-unity will let the lib which div can be considered as a page container. Property leap-bind defines basic attributes of the page like name or callbacks like navigate. Name is mandatory. One can give single string values as leap-bind, that would means the name of the given leap page.

Then add divs to this container as pages:

<div class="l-unity" leap-bind="{ name:'bigFellow', navigate:'navigateBig' }">
	<div class="l-page" leap-bind="{ name: 'Page1', title:'Page1', guard:'guardFunc', aftershow:'showFunc', afterhide:'hideFunc', beforeshow:'beforeshowFunc' }">
	<div class="l-page" leap-bind="{ name: 'Page2', title:'Page2', guard:'guardFunc', aftershow:'showFunc', afterhide:'hideFunc', beforehide: 'beforehideFunc', animation: 'fadeInLeftBig' }">
	...
</div>

Every page is a div with the CSS attribute l-page. Property leap-bind defines the attributes of the given page like name and title and callback functions.

Name must be present and unique. All other attributes are optional

Title if present will change the title of the browser window.

guard functions are called when transition is made to the given page. Those functions receives 3 parameters:

• page name transiting from
• page name transiting to and
• a callback.

You need to pass a boolean value to that callback. If it returns true, the transition is allowed, otherwise no transition is made.

afterhide function is called when a given page is hidden because a transition is made to another page.

aftershow function is executed whem the given page is selected as current.

beforehide function is called before any transition is made.

beforeshow function is called before any transition is made.

animation identifies which animation should be shown while transiting to the given page.

When page loading is done, just call:

leaper.init();

And you can start paging right away.

If you create leaper pages by dynamic content (ko binding or anything), the following function can be used after the DOM manipulation is finished:

leaper.makeLeap( domElement );

One can define multiple pages container in a single web-app. This way you can define pages for the main app, and control image galleries, menus, tab views through pages as well.

See pages.jade for an example...

By simple JS, the leaper can be controlled. 3 functions can be called from any JS code:

leaper.leapTo( unityName, pageRef, animation, parameters )

and

leaper.next( unityName, animation, parameters )

and

leaper.prev( unityName, animation, parameters )

First lets you to navigate to the page "pageRef" of the container "unityName" by the optional parameter: "animation" which specifies the transition animation. The 4th parameter is an array of parameters as described below.

The function next is a simple "nexter" which transit the given container to the next page in the order you defined them.

Function prev is a simple "prever" which transit the given container to the previous page in the order you defined them.

By extending an element with the attribute leap-link, Leaper makes a 'link' from it by adding a JS function performing the navigation defined.

<text leap-link="menu.Menu1">Back</text>

Path string should contain a container name and page name separated by a '.' Works by clicking on or touching that item or receiving and event 'leapTo'.

By extending the name of the links introduced above, you can bypass textual parameters as a declarative way, or giving a 4th array-type parameter to the leapTo method as an explicit way.

<text leap-link="menu.Menu1:doNotSave:doNotAnimate">Back</text>

All affected guard and before* functions receive the array

['doNotSave', 'doNotAnimate']

Or as an explicit example:

leaper.leapTo( 'containerName', 'pageName', ['doNotSave', 'doNotAnimate'] );

By extending an element with the attribute leap-eval, Leaper makes a 'link' from it by calling the JS function you give and consider the returning string value as a navigation link to be transited to. Leap-eval functions are async so the passed callback function has to be used for returning a value.

<text leap-eval="routing">Back</text>
...
function routing(callback){
	callback('menu.Menu2');
}

The string object given to the callback function must represent a real leap path which should contain a container name and page name separated by a '.' Works by clicking on or touching that item or receiving and event 'leapTo'.

You can define a function which is called when a transition is made in any of your page containers.

leaper.navigator( function(err, name, from, to, animation){
	console.log( 'Global navigation callback:', err, name, from, to, animation);
} );

Leapers can manage pages not just as cards but as a horizontal or vertical sequence where pages are ordered into a single flow and elements are scrolled in a bulk.

To define such leaper, you have to define the unity like this:

.l-unity.container(leap-bind="{ name:'footer', type:'sequence', angle: 0, elementCount: 3 }")
	.l-page.hcard(leap-bind="{ name: 'Page1' }")
	...
	.l-page.hcard(leap-bind="{ name: 'PageLast' }")
		[content]

The parameter

type:'sequence'

tells the Leaper to order the pages into a sequence, with the given angle.

0 means horizontal, 1 means vertical alignement.

The parameter elementCount defines how many pages can be seen in the container. This helps leaper to not scroll beyond the end of the pages.

Note: for such layout you have to define the necessary CSS properties of the given pages. Unities and pages must have fixed width or height like you can see in the CSS file of the example page.

You have the opportunity to add to a page an element with class .l-close which - by clicking or tapping on it - makes the given current page disappear. It is helpful if the leaper paging is added to popup-like solution.

...
.l-page(leap-bind="{ name: 'Info', animation: 'fadeIn' }")
		text.l-close OK 
...

Behavior of Leaper can be customized.

	leaper.randomAnimation( boolean );

defines if function next should take a random animation or the next one in the row. Default: true.

	leaper.allowOverlappingAnimation( boolean );

Sets if leaper allows paging before the previous animation ends. Default: false.

	leaper.callbackTimeout( millisec );

Defines the callback of the leaper for aftershow and afterhide callbacks. Due to the customizable animate.css, one can have custom animation duration. This functions allows you to set your own if have one.

	leaper.customAnimations( arra );

By custom animate.css one needs to able to set which animation is supported by the css created. This function lets the Leaper to know about it.