Try it now!

Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat. Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat.

Usage

Setup

Nowadays griddable.js depends on jQuery and jQuery UI draggable, so you need to include this scripts in the head of your document.

Include dependencies

Download the latest release at jQuery and jQuery UI.

HTML Structure

The HTML required to make gridster works. Class names and tags are customizable but is needed to follow the structure below:

Let's go run gridster.js!

Gridster only accepts one argument with configuration options. Take a look at the documentation.

Playing with the API

The API can be accesed as in most jQuery plugins via the jQuery data method like so:

Add a new widget to the grid


Remove a widget from the grid


Get serialized array with the elements positions

Creates a JavaScript array of objects, ready to be encoded as a JSON string.

Documentation

Options



Methods

The methods listed here are the most common. If this is never enough take a look to the documentation generated from source.

Options

gridder configuration object.

widget_selector: "> li"

Define who are the widgets. Can be a CSS Selector string or a jQuery collection of HTMLElement

widget_margins: [10, 10]

Horizontal and vertical margins respectively for widgets.

widget_base_dimensions: [140, 140]

Base widget dimensions in pixels. The first index for the width and the second for the height.

extra_rows: 0

Add more rows in addition to those that have been calculated.

extra_cols: 0

Add more rows in addition to those that have been calculated.

min_cols: 1

The minimum required columns.

min_rows: 10

The minimum required rows.

autogenerate_stylesheet: true

If true, all the CSS required to position all widgets in their respective columns and rows will be generated automatically and injected to the <head> of the document. You can set this to false, and write your own CSS targeting rows and cols via data-attributes like so: [data-col="1"] { left: 10px; }

serialize_params: function($w, wgd) { return { col: wgd.col, row: wgd.row } }

Return the data you want for each widget in the serialize method. Two arguments are passed: `$w`: the jQuery wrapped HTMLElement, and `wgd`: the grid coords object (`col`, `row`, `size_x`, `size_y`).

draggable: {}

The configuration object of the jQuery UI Draggable Plugin. See http://jqueryui.com/demos/draggable/ for more information.

collision.on_overlap_start: function(collider_data) { }

Executes a function first time a widget overlaps with a "faux" grid cell.

collision.on_overlap: function(collider_data) { }

Executes a function each time a widget overlaps with a "faux" grid cell.

collision.on_overlap_stop: function(collider_data) { }

Executes a function last time a widget overlaps with a "faux" grid cell.

.add_widget( html, [size_x], [size_y] )

Create a new widget with the given html and add it to the grid.

Parameters

html String
The string that represents the HTML of the widget.
size_x Number
The number of rows that the widget occupies. Default is 1.
size_y Number
The number of columns that the widget occupies. Default is 1.

Returns

Returns the jQuery wrapped HTMLElement representing the widget that was just created.

.remove_widget( el )

Remove a widget from the grid

Parameters

el HTMLElement
The jQuery wrapped HTMLElement representing the widget that you want to remove.

Returns

Returns the instance of the Gridster Class.

.serialize( [$widgets] )

Creates an array of objects representing the current position of all widgets in the grid.

Parameters

$widgets HTMLElement
The collection of jQuery wrapped HTMLElements you want to serialize. If no argument is passed all widgets will be serialized.

Returns

Returns an Array of Objects (ready to be encoded as a JSON string) with the data specified in the serialize_params option.

.serialize_changed( )

Creates an array of objects representing the current position of the widgets who have changed position.

Returns

Returns an Array of Objects (ready to be encoded as a JSON string) with the data specified in the serialize_params option.

Download

Browser support

Gridster supports Internet Explorer 9+, Firefox, Chrome, Safari and Opera.