jQuery.waterfall

Waterfall is a simple and light jQuery plug-in, you can use it easily and fluently! Enjoy!!!

Examples

If you want to WATERFALL div under #box

<!-- box is a container -->
<div id="box">
	<div>Card1</div>
	<div>Card2</div>
	<div>Card3</div>
	<div>Card4</div>
	<div>Card5</div>
</div>

Pick the target element

// waterfall have effect on #box
$(function(){
	$('#box').waterfall();
})

All div in #box will be showed in Waterfall as above.

More Examples

Installation

Just load jQuery library and then Waterfall library.

Basic

<!-- The jQuery library version >= 1.8 -->
<script src="//code.jquery.com/jquery-1.11.0.min.js"></script>;
<script src="//code.jquery.com/jquery-migrate-1.2.1.min.js"></script>
<!-- The core Waterfall library -->
<script src="//linzap.github.io/waterfall/waterfall-light.js"></script>

or download Waterfall starter kit to load the library which make loading speed faster.

Bower

bower install jquery.waterfall

Advanced usage

Here are some methods below, if you need better control !

Setting

var setting = {
	gap: 10,
	gridWidth: [0,400,600,800,1200],
	refresh: 500,
	scrollbottom : {
		ele: $('body'),
		endtxt : 'No More~~',
		gap: 300,
		callback: funciton(container){
			// do something
		}
	}
};
$(function(){
	$('box').waterfall(setting);
})

And more options if you like 😄

gap(int): distance between neighboring objects in pixels.
gridWidth(array): Grid system, column number is determined by device width, for example
animate (bool): Turn off animation.

5-column

gridWidth: [0,400,600,800,1200]

device_width	column number
0~400	1
400~600	2
600~800	3
800~1200	4
>1200	5

2-column

gridWidth: [0,400]

device_width	column number
0~400	1
>400	2

1-column

gridWidth: [0]

device_width	column number
>0	1

refresh(int): period of screen detection in millisecond
scrollbottom(object): some action setting as reached the end of scrollbar
- ele(element): owner of scrollbar, which is the parent element of $('box') by default.
- endtxt(string): reminding message as reached the end of scrollbar
- gap(int): if the distance to the bottom is smaller than gap, then will execute callback function.
- callback(funciton): user-defined action as reached the end of scrollbar

Stop,Restart Waterfall effect

Waterfall will continuingly detect your screen action. Therefore, if you want to stop its detection, method is showed as below.

$(function(){
	// Launch waterfall 
	$('box').waterfall();

	// Stop it
	$('box').waterfall('stop');
	
	// Restart it
	$('box').waterfall();	
})

Waterfall will distinguish the target by the container of $('box'). Therefore, stop action will only be activated to your specific container when there are two or more Waterfall container on Web.

Auto load more data on page scroll

As scrollbottom is used, it's very likely that you would load some new content to $('box'). Then, sort allows you to rearrange every elements in container. Also, $('box')(container itself) will be transfered to callback function for you to manipulate.

var setting = {
	scrollbottom : {
		callback: funciton(container){
			// if scroll to bottom, load more data...
			$.ajax({}).done(function(data){

				// resort elements
				container.waterfall('sort');

			});
		}
	}
};
$(function(){
	$('box').waterfall(setting);
})

If there is nothing more to be loaded in the container, then it means reaching the end of scrollbar. At this moment, you should remind user that there is "no more data", and you can create your own reminding message by setting endtxt.

var setting = {
	scrollbottom : {
		endtxt : 'No More Data !!',
		callback: funciton(container){
			// if scroll to bottom, load more data...
			$.ajax({}).done(function(data){
				if(data)	
					// resort elements
					container.waterfall('sort');
				else
					// done, show message
					container.waterfall('end');
			});
		}
	}
};

$(function(){
	$('box').waterfall(setting);
})

❗ Notice that if you execute $('box').waterfall("stop"), then scrollbottom and $('box').waterfall("sort") will be disabled.

Besides, container.waterfall('end') will not stop the detection but executing $('box').waterfall("stop") is the only way.

Overwrite setting

Waterfall setting accepts overwriten by importing the setting object. And nothing but the specific target will be updated by the transfered setting data.

var setting = {
	gap: 10,
	gridWidth: [0,400,600,800,1200],
	refresh: 500,
};

$(function(){
	$('box').waterfall(setting);

	// only update "gap" value
	$('box').waterfall( {gap:30} );
})

License

Waterfall is Apache License You can find it in the root directory of this source tree.

More...

If any suggestion, use issue! I will be glad to discuss with you.
Also, I welcome more contributers and hope to make this Plug-in even better(Pull-requests).

mopo922/jquery.waterfall