Freewall - jQuery plugin for creating grid layouts

# Free Wall

Creating dynamic grid layouts.

## What is Freewall?

Freewall is a cross-browser and responsive jQuery plugin to help you create many types of grid layouts: flexible layouts, images layouts, nested grid layouts, metro style layouts, pinterest like layouts ... with nice CSS3 animation effects and call back events. Freewall is all-in-one solution for creating dynamic grid layouts for desktop, mobile and tablet.

#### Some example layouts:

- ### Flex layout

- ### Window 8

- ### Images layout

- ### Pinterest layout

## How it works

Based on the width (or height) of a container and the width (height) of a cell unit, It will create a virtual matrix. Scaning the matrix at each cell will find a free cell around to made a free area, then try to fit a block element into it. In case no block can fit the gap, it will resize the block to fill the gap (that is one of the options).

## Share

Twitter
Google +
Facebook

## Download

Project Freewall.js
Buy me a beer :)

## Getting started

Freewall requires jQuery or Zepto framework. It requires browsers which support CSS3 for some nice animation effects.

    <!DOCTYPE html>
    <html>
    <head>
      <title> freewall demo getting started</title>
      <script src="js/jquery-1.10.2.min.js"></script>
      <script src="../freewall.js"></script>
      <style type="text/css">
        #container {
          width: 80%;
          margin: auto;
        }
        .item {
          background: rgb(135, 199, 135);
          width: 320px;
          height: 320px;
        }
      </style>
    </head>
    <body>
      <div id="container">
        <div class="item"></div>
        <div class="item"></div>
        <div class="item"></div>
        <div class="item"></div>
        <div class="item"></div>
        <div class="item"></div>
        <div class="item"></div>
      </div>
      <script>
        $(function() {
          var wall = new freewall("#container");
          wall.fitWidth();
        });
      </script>
    </body>
    </html>

View detail ...

## Features

- Draggable support
- Direction support
- Custom plugin
- Responsive grid
- Gaps control
- Filter items
- CSS3 animation (js fallback)
- Nested grid
- Images grid/layout
- Fit container
- Vertical grid/layout
- Horizontal grid/layout
- Window 8 metro style
- Pinterest like grid/layout

## Options

- draggable
- animate
- cellW
- cellH
- delay
- fixSize
- gutterX
- gutterY
- selector
- rightToLeft
- bottomToTop

View detail ...

## Options

### All options are parameters of Reset method

- ### draggable : boolean

  Default: false
  True: to make block can be drag & drop

- ### animate : boolean

  True: to make block move with animation

- ### cellW: mix

  Default: 100
  The width of unit, base on it will build grid container. It can be a function and return value.

  ### Example

      var wall = new freewall('.free-wall');
      wall.reset({
        selector: '.brick',
        cellW: function(width) {
            var cellWidth = width / 3;
            return cellWidth - 20;
          },
        cellH: 160
      });

- ### cellH: mix

  Default: 100
  The height of unit, base on it will build grid container. It can be a function and return value.

- ### delay : number

  Default: 0
  The time delay for show block. It will increase by each block.

- ### fixSize : boolean

  Default: null
  value is null or not set let blocks can adjust and resize to fill gap
  value is 0 or false let blocks can adjust size but can't resize to fill gap.
  value is 1 or true let blocks keep the size as init, can't resize to fill gap.
  Can override the fixSize option by set data-fixSize attribute in the block.

  ### Example

      <div class="brick size22" data-fixSize=true>
        <div class='cover'>
          <div class="item size12"></div>
          <div class="item size12"></div>
        </div>
      </div>

- ### gutterX : mixed

  Default: 10
  The horizon spacing between the column. Default is number, but can set it with 'auto' value.

- ### gutterY : mixed

  Default: 10
  The vertical spacing between the row. Default is number, but can set it with 'auto' value.

- ### selector : string

  Get all blocks to made layout

- ### Example

      var wall = new freewall('.free-wall');
      wall.reset({
        selector: '.brick',
        animate: true,
        cellW: 150,
        cellH: 150,
        gutterY: 10,
        gutterX: 'auto'
      });

- ### rightToLeft : boolean

  Default: false
  True: let layout start render from right to left

- ### bottomToTop : boolean

  Default: false
  True: let layout start render from bottom up to top

## Events

- onGapFound
- onComplete
- onResize
- onBlockReady
- onBlockActive
- onBlockFinish

View detail ...

## Events

- ### onGapFound

  Registry callback when a gap found.

- ### onComplete

  Registry callback when all block arrange.

- ### onResize

  Registry callback when browser resize.

- ### Example

      var wall = new freewall('.free-wall');
      wall.reset({
        selector: '.brick',
        onResize: function() {
          this.fitWidth();
        }
      });

- ### onBlockReady

  Fire when block adjusted.

- ### onBlockActive

  Fire before block show or hide in the layout.

- ### onBlockFinish

  Fire when block finish show or hide in the layout.

## Methods

- addCustomEvent
- appendBlock
- appendHoles
- fillHoles
- filter
- fireEvent
- fitHeight
- fitWidth
- fitZone
- fixPos
- fixSize
- prepend
- refresh
- reset
- setHoles
- unFilter

View detail ...

## Methods

- ### addCustomEvent(name, handler)

  Support create custom event when arrange layout

- ### appendBlock(items)

  Append one or more items into layout

- ### appendHoles(holes)

  Add one or more blank area into layout

- ### fillHoles()

  Let layout without gaps

- ### filter(selector)

  Fillter blocks to show

- ### fireEvent()

  Fire custom event

- ### fitHeight(height)

  Made the layout fit with limit height

- ### fitWidth(width)

  Made the layout fit with limit width

- ### fitZone(width, height)

  Made the layout fit with limit width and height

- ### fixPos(object)

  Set a block at fixed position, top/left is multiple of cell with/height

- ### fixSize(object)

  Set a block with special width or height

  ##### Example

      var wall = new freewall('.free-wall');
      var dna = $(".free-wall .flex-layout");
      wall.unsetFilter();
      wall.fixSize({
        block: dna,
        width: 150,
        height: 150
      });
      wall.fitWidth();

- ### prepend(items)

  Prepend one or more items into layout

- ### refresh()

  rearrange layout

- ### reset(options)

  Config options for render layout.

  ##### Example

      var ewall = new freewall(demo);
      var demo = $(".example");
      ewall.reset({
        selector: '.cell',
        animate: true,
        delay: 20,
        cellW: 15.5,
        cellH: 15,
        gutterX: 2,
        gutterY: 2
      });
      ewall.fitWidth(cwidth);

- ### setHoles(hole)

  Set the holes on layout

- ### unFilter()

  Made all block to show

## Supports

- Chrome
- Opera
- Safari
- IE 8.0+
- Firefox

## Example

Filter
View detail ...

## Example

Append item
View detail ...

## Example

Prepend item
View detail ...

## Example

CSS3 animation
View detail ...

## Example

Draggable
View detail ...

## Example

For Zeptojs
View detail ...

## Example

Fit height
View detail ...

## Example

Fit zone
View detail ...

## Example

Window 8 metro style
View detail ...

## Example

Images layout
View detail ...

## Example

Pinterest like layout
View detail ...

## Example

Flexible grid
View detail ...

## Example

Grid layout
View detail ...

## Example

Nested grid
View detail ...

## Copyright

© 2013 Minh Nguyen

Released under the MIT license