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
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 millisecondscrollbottom
(object): some action setting as reached the end of scrollbarele
(element): owner of scrollbar, which is the parent element of$('box')
by default.endtxt
(string): reminding message as reached the end of scrollbargap
(int): if the distance to the bottom is smaller thangap
, 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); })
$('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).