Waterfall

jquery waterfall plugin,like Pinterest.

This project is maintained by bingdian

Waterfall

jquery waterfall plugin,like Pinterest、huaban.com、faxianla.com

En 中文

Documentation

Download

Download the latest waterfall plugin。

Getting started

Markup:

<div id="container"></div>

Add jQuery, handlebars and the Waterfall script. (You can also use other javascript template,see demo)

<script src="/path/jquery.min.js"></script>
<script src="/path/handlebars.js"></script>
<script src="/path/waterfall.min.js"></script>

template:

<script id="waterfall-tpl" type="text/x-handlebars-template">
    //template content
</script>

script:

$('#container').waterfall({
	itemCls: 'waterfall-item', 
	prefix: 'waterfall',
	fitWidth: true, 
	colWidth: 240, 
	gutterWidth: 10,
	gutterHeight: 10,
	align: 'center',
	minCol: 1, 
	maxCol: undefined, 
	maxPage: undefined, 
	bufferPixel: -50, 
	containerStyle: {
		position: 'relative'
	},
	resizable: true, 
	isFadeIn: false,
	isAnimated: false,
	animationOptions: { 
	},
	isAutoPrefill: true,
	checkImagesLoaded: true,
	path: undefined,
	dataType: 'json', 
	params: {}, 
	
	loadingMsg: '<div style="text-align:center;padding:10px 0; color:#999;"><img src="data:image/gif;base64,R0lGODlhEAALAPQAAP///zMzM+Li4tra2u7u7jk5OTMzM1hYWJubm4CAgMjIyE9PT29vb6KiooODg8vLy1JSUjc3N3Jycuvr6+Dg4Pb29mBgYOPj4/X19cXFxbOzs9XV1fHx8TMzMzMzMzMzMyH5BAkLAAAAIf4aQ3JlYXRlZCB3aXRoIGFqYXhsb2FkLmluZm8AIf8LTkVUU0NBUEUyLjADAQAAACwAAAAAEAALAAAFLSAgjmRpnqSgCuLKAq5AEIM4zDVw03ve27ifDgfkEYe04kDIDC5zrtYKRa2WQgAh+QQJCwAAACwAAAAAEAALAAAFJGBhGAVgnqhpHIeRvsDawqns0qeN5+y967tYLyicBYE7EYkYAgAh+QQJCwAAACwAAAAAEAALAAAFNiAgjothLOOIJAkiGgxjpGKiKMkbz7SN6zIawJcDwIK9W/HISxGBzdHTuBNOmcJVCyoUlk7CEAAh+QQJCwAAACwAAAAAEAALAAAFNSAgjqQIRRFUAo3jNGIkSdHqPI8Tz3V55zuaDacDyIQ+YrBH+hWPzJFzOQQaeavWi7oqnVIhACH5BAkLAAAALAAAAAAQAAsAAAUyICCOZGme1rJY5kRRk7hI0mJSVUXJtF3iOl7tltsBZsNfUegjAY3I5sgFY55KqdX1GgIAIfkECQsAAAAsAAAAABAACwAABTcgII5kaZ4kcV2EqLJipmnZhWGXaOOitm2aXQ4g7P2Ct2ER4AMul00kj5g0Al8tADY2y6C+4FIIACH5BAkLAAAALAAAAAAQAAsAAAUvICCOZGme5ERRk6iy7qpyHCVStA3gNa/7txxwlwv2isSacYUc+l4tADQGQ1mvpBAAIfkECQsAAAAsAAAAABAACwAABS8gII5kaZ7kRFGTqLLuqnIcJVK0DeA1r/u3HHCXC/aKxJpxhRz6Xi0ANAZDWa+kEAA7" alt=""><br />Loading...</div>',
	
	state: { 
		isDuringAjax: false, 
		isProcessingData: false, 
		isResizing: false,
		curPage: 1 
	},

	// callbacks
	callbacks: {
		/*
		 * loadingStart
		 * @param {Object} loading $('#waterfall-loading')
		 */
		loadingStart: function($loading) {
			$loading.show();
			//console.log('loading', 'start');
		},
		
		/*
		 * loadingFinished
		 * @param {Object} loading $('#waterfall-loading')
		 * @param {Boolean} isBeyondMaxPage
		 */
		loadingFinished: function($loading, isBeyondMaxPage) {
			if ( !isBeyondMaxPage ) {
				$loading.fadeOut();
				//console.log('loading finished');
			} else {
				//console.log('loading isBeyondMaxPage');
				$loading.remove();
			}
		},
		
		/*
		 * loadingError
		 * @param {String} xhr , "end" "error"
		 */
		loadingError: function($message, xhr) {
			$message.html('Data load faild, please try again later.');
		},
		
		/*
		 * renderData
		 * @param {String} data
		 * @param {String} dataType , "json", "jsonp", "html"
		 */
		renderData: function (data, dataType) {
			var tpl,
				template;
				
			if ( dataType === 'json' ||  dataType === 'jsonp'  ) { // json or jsonp format
				tpl = $('#waterfall-tpl').html();
				template = Handlebars.compile(tpl);
				
				return template(data);
			} else { // html format
				return data;
			}
		}
	},
	
	debug: false
});

options

Name Type Default value Description
itemCls String 'waterfall-item' the waterfall brick element class
prefix String 'waterfall' waterfall elements prefix
fitWidth Boolean true fit the parent element width
colWidth Integer 240 column width
gutterWidth Integer 10 the waterfall brick element horizontal gutter
gutterHeight Integer 10 the waterfall brick element vertical gutter
align String 'center' 'align', 'left', 'right'
minCol Integer 1 min columns
maxCol Integer undefined max columns
maxPage Integer undefined max page
bufferPixel Integer -50 decrease this number if you want scroll to fire quicker
containerStyle Object {position: 'relative'} the waterfall container style
resizable Boolean true triggers layout when browser window is resized
isFadeIn Boolean false append html effect
isAnimated Boolean false triggers animate when browser window is resized
animationOptions Object {} animation options
isAutoPrefill Boolean true When the document is smaller than the window, load data until the document is larger
checkImagesLoaded Boolean true triggers layout when images loaded. Suggest false
path Array, Function undefined Either parts of a URL as an array (e.g. ["/popular/page/", "/"] or a function that takes in the page number and returns a URL(e.g. function(page) { return '/populr/page/' + page; })
dataType String 'json' 'json', 'jsonp', 'html'
params Object {} params,{type: "popular", tags: "travel", format: "json"} => "type=popular&tags=travel&format=json"
loadingMsg html loading html
callbacks Object callback
debug Boolean false enable debug

loadingMsg:

'&lt;div style="text-align:center;padding:10px 0; color:#999;">&lt;img src="data:image/gif;base64,R0lGODlhEAALAPQAAP///zMzM+Li4tra2u7u7jk5OTMzM1hYWJubm4CAgMjIyE9PT29vb6KiooODg8vLy1JSUjc3N3Jycuvr6+Dg4Pb29mBgYOPj4/X19cXFxbOzs9XV1fHx8TMzMzMzMzMzMyH5BAkLAAAAIf4aQ3JlYXRlZCB3aXRoIGFqYXhsb2FkLmluZm8AIf8LTkVUU0NBUEUyLjADAQAAACwAAAAAEAALAAAFLSAgjmRpnqSgCuLKAq5AEIM4zDVw03ve27ifDgfkEYe04kDIDC5zrtYKRa2WQgAh+QQJCwAAACwAAAAAEAALAAAFJGBhGAVgnqhpHIeRvsDawqns0qeN5+y967tYLyicBYE7EYkYAgAh+QQJCwAAACwAAAAAEAALAAAFNiAgjothLOOIJAkiGgxjpGKiKMkbz7SN6zIawJcDwIK9W/HISxGBzdHTuBNOmcJVCyoUlk7CEAAh+QQJCwAAACwAAAAAEAALAAAFNSAgjqQIRRFUAo3jNGIkSdHqPI8Tz3V55zuaDacDyIQ+YrBH+hWPzJFzOQQaeavWi7oqnVIhACH5BAkLAAAALAAAAAAQAAsAAAUyICCOZGme1rJY5kRRk7hI0mJSVUXJtF3iOl7tltsBZsNfUegjAY3I5sgFY55KqdX1GgIAIfkECQsAAAAsAAAAABAACwAABTcgII5kaZ4kcV2EqLJipmnZhWGXaOOitm2aXQ4g7P2Ct2ER4AMul00kj5g0Al8tADY2y6C+4FIIACH5BAkLAAAALAAAAAAQAAsAAAUvICCOZGme5ERRk6iy7qpyHCVStA3gNa/7txxwlwv2isSacYUc+l4tADQGQ1mvpBAAIfkECQsAAAAsAAAAABAACwAABS8gII5kaZ7kRFGTqLLuqnIcJVK0DeA1r/u3HHCXC/aKxJpxhRz6Xi0ANAZDWa+kEAA7" alt="">&lt;br />Loading...&lt;/div>'

callbacks:

callbacks: {
    /*
     * loading start 
     * @param {Object} loading $('#waterfall-loading')
     */
    loadingStart: function($loading) {
        $loading.show();
    },

    /*
     * loading finished
     * @param {Object} loading $('#waterfall-loading')
     * @param {Boolean} isBeyondMaxPage
     */
    loadingFinished: function($loading, isBeyondMaxPage) {
        if ( !isBeyondMaxPage ) {
            $loading.fadeOut();
        } else {
            $loading.remove();
        }
    },

    /*
     * loading error
     * @param {String} xhr , "end" "error"
     */
    loadingError: function($message, xhr) {
        $message.html('Data load faild, please try again later.');
    },

    /*
     * render data
     * @param {String} data
     * @param {String} dataType , "json", "jsonp", "html"
     */
    renderData: function (data, dataType) {
        var tpl,
            template;

        if ( dataType === 'json' ||  dataType === 'jsonp'  ) { // json or jsonp format
            tpl = $('#waterfall-tpl').html();
            template = Handlebars.compile(tpl);

            return template(data);
        } else { // html format
            return data;
        }
    }
}

method

$('#container').waterfall( 'methodName', [optionalParameters] );

prepend

$('#container').waterfall('prepend', $content, callback);

append

$('#container').waterfall('append', $content, callback);

removeItems

$('#container').waterfall('removeItems', $items, callback);

reLayout

$('#container').waterfall('reLayout', $content, callback);

pause

$('#container').waterfall('pause', callback);

resume

$('#container').waterfall('resume', callback);

option

$('#container').waterfall('option', options, callback);

Demos