waterfall

Javascript waterfall effection with images preloader

Installation && Usage

Browser

In a browser, you can use fetch-waterfall as follows:

<script src='./lib/waterfall.js' charset='utf8'><script>

it also can be a AMD module while using require.js

NodeJS

Install for Node.js using npm

$ npm install fetch-waterfall

Require module use require

const waterfall = require('fetch-waterfall)

API

waterfall(config)

• config (Object) configure object

configure property details

Name	Type	Default-value	Description
container	String | HTMLElement	''	container element
itemClass	String	'item'	item's className
cols	Number	1	Waterfall effections columns
gutterWidth	String | Number	10	the gaps of horizonta with pixel or percentage unit refering to container width
gutterHeight	String | Number	10	the gaps of verticle with pixel or percentage unit refering to container width
gutterType	String	space-between	gaps types，space-around，space-between
preloadImage	Boolean	false	if need images preload(default to false)
defaultImage	String	undefined	the replace image url when target image loads failly(it effects when preloadImage is true)
preloadPercent	Function	function (state) {}	images preload function，payload state
preloadComplete	Function	function (promise) {}	images loaded calllback function, argument promise is a Promise Object
path	Function | String	undefined	request request url, when it is a function which return a string. it only supports the method GET request, it uses fetch API to request
maxPage	String	undefined	request the max number of request
template	String | HTMLElement	'no referering templates'	the Waterfall items rendering template, as follows template
callbacks	Object	{ loadingStart: fn, loadingFinished: fn, loadingError: fn }	request request callback function, see as follows

config.callbacks details

    callbacks: {
        /**
         *  the begining function of fetch request 
         */
        loadingStart: function () {},

        /**
         *  the end function of fetch request
         * @param {Object} res - return response
         */
        loadingFinished: function (res) {
            console.log(res)
        },

        /**
         *  fetch request error function
         * @param {Object} error - request error message
         */
        loadingError: function (error) {
            console.log(error)
        }
    }

Template

fetch-waterfall it supports a simple template rendering engine, in order to display the items in the waterfall it uses {{}} to contain variable, {{#}} contain the iterable array

template use DOM elements or string straightly.

    <script type="text/template" id="waterfall-tpl">
        {{#results}}
            <div class="item">
                <img src="{{url}}" />
                <p>name: {{name}}</p>
                <p>age: {{age}}</p>
            </div>
        {{/results}}
    </script>

a json data model

    {
        "results": [{
            "name": "Tom",
            "age": 20,
            "url": "./imgs/1.jpg"
        }, {
            "name": "Jack",
            "age": 22,
            "url": "./ims/2.jpg"
        },{
            "name": "Marry",
            "age": 16,
            "url": "./imgs/3.jpg"
        }]
    }

after rendering result, as follows:

    <div class="item">
        <img src="./imgs/1.jpg" />
        <p>name: Tom</p>
        <p>age: 20</p>
    </div>
    <div class="item">
        <img src="./ims/2.jpg" />
        <p>name: Jack</p>
        <p>age: 22</p>
    </div>
    <div class="item">
        <img src="./imgs/3.jpg" />
        <p>name: Marry</p>
        <p>age: 16</p>
    </div>

Examples

• html structure

    <div id="box"></div>
    <script src='./lib/waterfall.js'>
  

• script

    waterfall({
        container: '#box', // container
        itemClass: 'item', // item's className
        cols: 3, // columns
        gutterWidth: 10, // horizonal gutter
        gutterHeight: 20, // vertical gutter
        gutterType: 'space-around', // gutter type
        preloadImage: true, // preload images
        defaultImage: './imgs/default.jpg', // target image load error which to replace it
        preloadPercent: function (state) { // images preloading
            console.log('images has loaded ' + state.current/state.total)
            console.log(state)
        },
        preloadComplete: function (promise) { // images loaded
            promise.then(function (state) {
                console.log(state)
                document.getElementById('mask').style.display = 'none'
            })
        },
        path: function (curPage) { // fetch request url
            return './users.json?page=' + curPage
        },
        maxPage: 6, // request max count
        template: document.getElementById('waterfall-tpl'), // tempalte
        callbacks: {
            loadingStart: function () {
                console.log('ajax request ...')
                document.getElementById('mask').style.display = 'block'
            },
            loadingFinished: function (res) {
                console.log('ajax response', res)               
            },
            loadingError: function (error) {
                console.log(error)
            }
        }
    })
  

waterfall Demo

License

MIT