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