jQuery.waterfall

Waterfall-Light 是一個 jQuery 的 plug-in

簡單、輕量的瀑布式排版，您可以簡單、快速的使用它。

Examples

假設您欲將 id 為 box 元素內的 div 以 Waterfall 型式排列

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

您只需指定欲使用 Waterfall 排列的元素，便可達到排列的效果。

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

如上所示，所有box 內的 div 元素會以 Waterfall 的形式排列。

Installation

因為 Waterfall 是一個 jQuery 的 plug-in，首先您需要先載入 jQuery library 接著載入 Waterfall library

<!-- 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>

或是下載 Waterfall starter kit 來引入這個 library，載入速度也會相較的快。

Advanced usage

如果您需要控制更多參數、細節，Waterfall 擁有幾個 methods 如下所示。

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
		}
	}
};

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

您可以傳入一個物件，其中的選項"全部"皆可選填，一覽如下：

gap(int): 排列物體彼此的間距(margin)，單位為像素 px
gridWidth(array): 宣告螢幕寬度所對應的欄位數量，上述設定表示螢幕寬度 (px)
- 0~400 呈現 1 欄
- 400~600 呈現 2 欄
- 600~800 呈現 3 欄
- 800~1200 呈現 4 欄
- >1200 呈現 5 欄
refresh(int): 偵測螢幕變化的時間間隔，單位為毫秒 (ms)
scrollbottom(object): 設定開啟偵測卷軸滾動到底部，要做的事情
- ele(element): 產生卷軸的元素，預設為 $('box') 的父元素
- endtxt(string): 捲動到底部後，顯示的文字
- gap(int): 若距離底部小於這個 gap 值，則會觸發 callback 執行
- callback(funciton): 回呼函式，您可以定義卷軸到底部時，會執行的其它功能

Stop,Restart Waterfall effect

Waterfall 是一個會不斷偵測螢幕變化的函式，若您需要暫時停止它的偵測功能，可以這樣呼叫

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

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

Waterfall 會以您 $('box') 容器做為識別的依據，若 wab 上同時存在 2 個以上的 Waterfall 容器，stop 也只會作用在您指定的容器上

Auto load more data on page scroll

若您有設定 scrollbottom 的話，表示您可能會加入新的元素到 $('box') 容器中，此時您可在 callback 中呼叫 sort 重新排列容器中的元素。在這個callback中，會傳入容器自身($('box'))方便您操控。

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

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

			});
		}
	}
};

$('box').waterfall(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');
			});
		}
	}
};

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

注意，如果您呼叫了$('box').waterfall("stop")，那麼 scrollbottom 不會被觸發，而且 $('box').waterfall("sort") 也會失效。

另外，呼叫了 container.waterfall('end') 並不會停止偵測，若需停止偵測，仍需呼叫 $('box').waterfall("stop") 才行。

Overwrite setting

如果您需要更新 Waterfall 的 setting，您可以直接傳入設定物件。Waterfall 不會覆蓋掉已經設定的參數

var setting = {
	gap: 10,
	gridWidth: [0,400,600,800,1200],
	refresh: 500,
};
$('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...

如果有 Waterfall 的建議可以發出 issue 讓我知道。

也歡迎您成為 Waterfall 的 contributer，讓這個 Plug-in 更加完善 (pull-request)

scandal0705/jquery.waterfall