README.md 10.9 KB
Newer Older
Pavel Reznikov's avatar
Pavel Reznikov committed
1
2
3
gridstack.js
============

Pavel Reznikov's avatar
Pavel Reznikov committed
4
[![Build Status](https://travis-ci.org/troolee/gridstack.js.svg?branch=master)](https://travis-ci.org/troolee/gridstack.js)
Pavel Reznikov's avatar
Pavel Reznikov committed
5
[![Coverage Status](https://coveralls.io/repos/github/troolee/gridstack.js/badge.svg?branch=master)](https://coveralls.io/github/troolee/gridstack.js?branch=master)
Pavel Reznikov's avatar
Pavel Reznikov committed
6
7
[![Dependency Status](https://david-dm.org/troolee/gridstack.js.svg)](https://david-dm.org/troolee/gridstack.js)
[![devDependency Status](https://david-dm.org/troolee/gridstack.js/dev-status.svg)](https://david-dm.org/troolee/gridstack.js#info=devDependencies)
Pavel Reznikov's avatar
Pavel Reznikov committed
8

9
gridstack.js is a mobile-friendly Javascript library for dashboard layout and creation. Making a drag-and-drop, multi-column dashboard has never been easier. gridstack.js allows you to build draggable, responsive bootstrap v3-friendly layouts. It also works great with [knockout.js](http://knockoutjs.com), [angular.js](https://angularjs.org), [ember](https://www.emberjs.com/).
Pavel Reznikov's avatar
Pavel Reznikov committed
10

Pavel Reznikov's avatar
Pavel Reznikov committed
11
Join gridstack.js on Slack: https://gridstackjs.troolee.com
Pavel Reznikov's avatar
slack    
Pavel Reznikov committed
12

Pavel Reznikov's avatar
Pavel Reznikov committed
13
[![Slack Status](https://gridstackjs.troolee.com/badge.svg)](https://gridstackjs.troolee.com)
Pavel Reznikov's avatar
slack    
Pavel Reznikov committed
14

Pavel Reznikov's avatar
add TOC    
Pavel Reznikov committed
15
16
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
Pavel Reznikov's avatar
Pavel Reznikov committed
17
**Table of Contents**  *generated with [DocToc](http://doctoc.herokuapp.com/)*
Pavel Reznikov's avatar
add TOC    
Pavel Reznikov committed
18

19
20
- [gridstack.js News](#gridstackjs-news)
- [Demo and examples](#demo-and-examples)
Pavel Reznikov's avatar
add TOC    
Pavel Reznikov committed
21
22
- [Usage](#usage)
  - [Requirements](#requirements)
Pavel Reznikov's avatar
Pavel Reznikov committed
23
      - [Using gridstack.js with jQuery UI](#using-gridstackjs-with-jquery-ui)
Pavel Reznikov's avatar
Pavel Reznikov committed
24
  - [Install](#install)
Pavel Reznikov's avatar
add TOC    
Pavel Reznikov committed
25
  - [Basic usage](#basic-usage)
Pavel Reznikov's avatar
Pavel Reznikov committed
26
  - [Migrating to v0.3.0](#migrating-to-v030)
Pavel Reznikov's avatar
Pavel Reznikov committed
27
  - [API Documentation](#api-documentation)
Pavel Reznikov's avatar
add TOC    
Pavel Reznikov committed
28
  - [Touch devices support](#touch-devices-support)
29
  - [gridstack.js for specific frameworks](#gridstackjs-for-specific-frameworks)
Pavel Reznikov's avatar
add TOC    
Pavel Reznikov committed
30
  - [Change grid width](#change-grid-width)
Pavel Reznikov's avatar
Pavel Reznikov committed
31
32
  - [Extra CSS](#extra-css)
    - [Different grid widths](#different-grid-widths)
Pavel Reznikov's avatar
Pavel Reznikov committed
33
  - [Override resizable/draggable options](#override-resizabledraggable-options)
Pavel Reznikov's avatar
Pavel Reznikov committed
34
  - [IE8 support](#ie8-support)
Pavel Reznikov's avatar
Pavel Reznikov committed
35
  - [Use with require.js](#use-with-requirejs)
Pavel Reznikov's avatar
add TOC    
Pavel Reznikov committed
36
- [Changes](#changes)
37
- [The Team](#the-team)
Pavel Reznikov's avatar
add TOC    
Pavel Reznikov committed
38
39
40
41

<!-- END doctoc generated TOC please keep comment here to allow auto update -->


42
43
44
45
gridstack.js News
=====

Version 1.0 is coming! Check out the blog post here for more information:
Artem's avatar
Artem committed
46
[https://dylandreams.com/2017/04/26/gridstack-10-coming-soon/](https://dylandreams.com/2017/04/26/gridstack-10-coming-soon/) and [subscribe to the blog](https://dylandreams.com) for more gridstack news and tutorials.
47
48
49


Demo and examples
Pavel Reznikov's avatar
Pavel Reznikov committed
50
51
====

Pavel Reznikov's avatar
Pavel Reznikov committed
52
Please visit http://gridstackjs.com for a demo or check out [these examples](http://gridstackjs.com/demo/).
Pavel Reznikov's avatar
Pavel Reznikov committed
53
54
55
56


Usage
=====
Pavel Reznikov's avatar
readme    
Pavel Reznikov committed
57

Pavel Reznikov's avatar
Pavel Reznikov committed
58
59
## Requirements

Pavel Reznikov's avatar
Pavel Reznikov committed
60
* [lodash.js](https://lodash.com) (>= 3.5.0, full build)
Pavel Reznikov's avatar
Pavel Reznikov committed
61
* [jQuery](http://jquery.com) (>= 3.1.0)
Pavel Reznikov's avatar
license    
Pavel Reznikov committed
62

Pavel Reznikov's avatar
Pavel Reznikov committed
63
64
Note: You can still use [underscore.js](http://underscorejs.org) (>= 1.7.0) instead of lodash.js

Pavel Reznikov's avatar
Pavel Reznikov committed
65
66
67
68
69
#### Using gridstack.js with jQuery UI

* [jQuery UI](http://jqueryui.com) (>= 1.12.0). Minimum required components: Core, Widget, Mouse, Draggable, Resizable
* (Optional) [jquery-ui-touch-punch](https://github.com/furf/jquery-ui-touch-punch) for touch-based devices support

Pavel Reznikov's avatar
Pavel Reznikov committed
70
71
## Install

72
73
* In the browser:

Pavel Reznikov's avatar
Pavel Reznikov committed
74
```html
Pavel Reznikov's avatar
Pavel Reznikov committed
75
<link rel="stylesheet" href="gridstack.css" />
Pavel Reznikov's avatar
Pavel Reznikov committed
76
77
78
79
<script src="gridstack.js"></script>
<script src="gridstack.jQueryUI.js"></script>
```

Pavel Reznikov's avatar
Pavel Reznikov committed
80
81
82
* Using CDN:

```html
Alain Dumesny's avatar
Alain Dumesny committed
83
84
85
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/gridstack.js/0.3.0/gridstack.min.css" />
<script type="text/javascript" src='//cdnjs.cloudflare.com/ajax/libs/gridstack.js/0.3.0/gridstack.min.js'></script>
<script type="text/javascript" src='//cdnjs.cloudflare.com/ajax/libs/gridstack.js/0.3.0/gridstack.jQueryUI.min.js'></script>
Pavel Reznikov's avatar
Pavel Reznikov committed
86
87
88
89
90
91
92
93
94
95
```

* Using bower:

```bash
$ bower install gridstack
```

* Using npm:

Pavel Reznikov's avatar
Pavel Reznikov committed
96
97
[![NPM version](https://img.shields.io/npm/v/gridstack.svg)](https://www.npmjs.com/package/gridstack)

Pavel Reznikov's avatar
Pavel Reznikov committed
98
99
100
101
102
103
```bash
$ npm install gridstack
```

You can download files from `dist` directory as well.

Pavel Reznikov's avatar
Pavel Reznikov committed
104
105
## Basic usage

Pavel Reznikov's avatar
Pavel Reznikov committed
106
```html
107
<div class="grid-stack">
Pavel Reznikov's avatar
Pavel Reznikov committed
108
109
    <div class="grid-stack-item"
        data-gs-x="0" data-gs-y="0"
110
111
        data-gs-width="4" data-gs-height="2">
            <div class="grid-stack-item-content"></div>
Pavel Reznikov's avatar
Pavel Reznikov committed
112
    </div>
Pavel Reznikov's avatar
Pavel Reznikov committed
113
114
    <div class="grid-stack-item"
        data-gs-x="4" data-gs-y="0"
115
116
117
118
119
120
121
        data-gs-width="4" data-gs-height="4">
            <div class="grid-stack-item-content"></div>
    </div>
</div>

<script type="text/javascript">
$(function () {
122
    $('.grid-stack').gridstack();
123
124
});
</script>
Pavel Reznikov's avatar
Pavel Reznikov committed
125
126
```

127

Pavel Reznikov's avatar
Pavel Reznikov committed
128
## Migrating to v0.3.0
Pavel Reznikov's avatar
Pavel Reznikov committed
129

Pavel Reznikov's avatar
typo    
Pavel Reznikov committed
130
As of v0.3.0, gridstack introduces a new plugin system. The drag'n'drop functionality has been modified to take advantage of this system. Because of this, and to avoid dependency on core code from jQuery UI, the plugin was functionality was moved to a separate file.
Pavel Reznikov's avatar
Pavel Reznikov committed
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

To ensure gridstack continues to work, either include the additional `gridstack.jQueryUI.js` file into your HTML or use `gridstack.all.js`:

```html
<script src="gridstack.js"></script>
<script src="gridstack.jQueryUI.js"></script>
```

or

```html
<script src="gridstack.all.js"></script>
```

We're working on implementing support for other drag'n'drop libraries through the new plugin system.

Pavel Reznikov's avatar
Pavel Reznikov committed
147

Pavel Reznikov's avatar
Pavel Reznikov committed
148
## API Documentation
Pavel Reznikov's avatar
Pavel Reznikov committed
149

150
Documentation can be found [here](https://github.com/gridstack/gridstack.js/tree/develop/doc).
151

Pavel Reznikov's avatar
add faq    
Pavel Reznikov committed
152

Pavel Reznikov's avatar
Pavel Reznikov committed
153
154
## Touch devices support

Pavel Reznikov's avatar
Pavel Reznikov committed
155
Please use [jQuery UI Touch Punch](https://github.com/furf/jquery-ui-touch-punch) to make jQuery UI Draggable/Resizable
Pavel Reznikov's avatar
Pavel Reznikov committed
156
157
working on touch-based devices.

Pavel Reznikov's avatar
Pavel Reznikov committed
158
```html
Pavel Reznikov's avatar
Pavel Reznikov committed
159
<script src="lodash.min.js"></script>
Pavel Reznikov's avatar
Pavel Reznikov committed
160
<script src="jquery.min.js"></script>
Pavel Reznikov's avatar
Pavel Reznikov committed
161
162
163
164
165
166
<script src="jquery-ui.min.js"></script>
<script src="jquery.ui.touch-punch.min.js"></script>

<script src="gridstack.js"></script>
```

Pavel Reznikov's avatar
Pavel Reznikov committed
167
Also `alwaysShowResizeHandle` option may be useful:
Pavel Reznikov's avatar
Pavel Reznikov committed
168
169
170
171

```javascript
$(function () {
    var options = {
172
        alwaysShowResizeHandle: /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent)
Pavel Reznikov's avatar
Pavel Reznikov committed
173
174
175
176
177
    };
    $('.grid-stack').gridstack(options);
});
```

178
If you're still experiencing issues on touch devices please check [#444](https://github.com/gridstack/gridstack.js/issues/444)
Pavel Reznikov's avatar
Pavel Reznikov committed
179

Pavel Reznikov's avatar
Pavel Reznikov committed
180

181
## gridstack.js for specific frameworks
Pavel Reznikov's avatar
Pavel Reznikov committed
182

183
184
185
- AngularJS: [gridstack-angular](https://github.com/kdietrich/gridstack-angular)
- Rails: [gridstack-js-rails](https://github.com/randoum/gridstack-js-rails)
- ember: [gridstack-ember](https://github.com/yahoo/ember-gridstack)
Pavel Reznikov's avatar
readme    
Pavel Reznikov committed
186
187


188
189
## Change grid width

Pavel Reznikov's avatar
Pavel Reznikov committed
190
191
To change grid width (columns count), to addition to `width` option, CSS rules
for `.grid-stack-item[data-gs-width="X"]` and  `.grid-stack-item[data-gs-x="X"]` have to be changed accordingly.
192

193
For instance for 3-column grid you need to rewrite CSS to be:
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216

```css
.grid-stack-item[data-gs-width="3"]  { width: 100% }
.grid-stack-item[data-gs-width="2"]  { width: 66.66666667% }
.grid-stack-item[data-gs-width="1"]  { width: 33.33333333% }

.grid-stack-item[data-gs-x="2"]  { left: 66.66666667% }
.grid-stack-item[data-gs-x="1"]  { left: 33.33333333% }
```

For 4-column grid it should be:

```css
.grid-stack-item[data-gs-width="4"]  { width: 100% }
.grid-stack-item[data-gs-width="3"]  { width: 75% }
.grid-stack-item[data-gs-width="2"]  { width: 50% }
.grid-stack-item[data-gs-width="1"]  { width: 25% }

.grid-stack-item[data-gs-x="3"]  { left: 75% }
.grid-stack-item[data-gs-x="2"]  { left: 50% }
.grid-stack-item[data-gs-x="1"]  { left: 25% }
```

217
218
and so on.

219
Here is a SASS code snipped which can make life easier (Thanks to @ascendantofrain, [#81](https://github.com/gridstack/gridstack.js/issues/81)):
Pavel Reznikov's avatar
Pavel Reznikov committed
220

Pavel Reznikov's avatar
Pavel Reznikov committed
221
```sass
Pavel Reznikov's avatar
Pavel Reznikov committed
222
223
224
225
226
227
228
229
230
231
232
233
234
.grid-stack-item {

    $gridstack-columns: 12;

    @for $i from 1 through $gridstack-columns {
        &[data-gs-width='#{$i}'] { width: (100% / $gridstack-columns) * $i; }
        &[data-gs-x='#{$i}'] { left: (100% / $gridstack-columns) * $i; }
        &.grid-stack-item[data-gs-min-width='#{$i}'] { min-width: (100% / $gridstack-columns) * $i; }
        &.grid-stack-item[data-gs-max-width='#{$i}'] { max-width: (100% / $gridstack-columns) * $i; }
    }
}
```

Pavel Reznikov's avatar
Pavel Reznikov committed
235
236
237
238
239
Or you can include `gridstack-extra.css`. See below for more details.

## Extra CSS

There are few extra CSS batteries in `gridstack-extra.css` (`gridstack-extra.min.css`).
Pavel Reznikov's avatar
Pavel Reznikov committed
240

Pavel Reznikov's avatar
Pavel Reznikov committed
241
242
243
244
### Different grid widths

You can use other than 12 grid width:

Pavel Reznikov's avatar
Pavel Reznikov committed
245
```html
Pavel Reznikov's avatar
Pavel Reznikov committed
246
247
248
249
250
251
<div class="grid-stack grid-stack-N">...</div>
```
```javascript
$('.grid-stack').gridstack({width: N});
```

252
See example: [2 grids demo](http://gridstack.github.io/gridstack.js/demo/two.html)
Pavel Reznikov's avatar
Pavel Reznikov committed
253

Pavel Reznikov's avatar
Pavel Reznikov committed
254
255
256
## Override resizable/draggable options

You can override default `resizable`/`draggable` options. For instance to enable other then bottom right resizing handle
jhadenfeldt's avatar
jhadenfeldt committed
257
you can init gridstack like:
Pavel Reznikov's avatar
Pavel Reznikov committed
258
259
260
261
262
263
264
265
266
267
268

```javascript
$('.grid-stack').gridstack({
    resizable: {
        handles: 'e, se, s, sw, w'
    }
});
```

Note: It's not recommended to enable `nw`, `n`, `ne` resizing handles. Their behaviour may be unexpected.

Pavel Reznikov's avatar
Pavel Reznikov committed
269
270
271
## IE8 support

Support of IE8 is quite limited and is not a goal at this time. As far as IE8 doesn't support DOM Level 2 I cannot manipulate with
Pavel Reznikov's avatar
typo    
Pavel Reznikov committed
272
CSS stylesheet dynamically. As a workaround you can do the following:
Pavel Reznikov's avatar
Pavel Reznikov committed
273

274
- Create `gridstack-ie8.css` for your configuration (sample for grid with cell height of 60px can be found [here](https://gist.github.com/gridstack/6edfea5857f4cd73e6f1)).
Pavel Reznikov's avatar
Pavel Reznikov committed
275
276
- Include this CSS:

Pavel Reznikov's avatar
Pavel Reznikov committed
277
```html
Pavel Reznikov's avatar
Pavel Reznikov committed
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
<!--[if lt IE 9]>
<link rel="stylesheet" href="gridstack-ie8.css"/>
<![endif]-->
```

- You can use this python script to generate such kind of CSS:

```python
#!/usr/bin/env python

height = 60
margin = 20
N = 100

print '.grid-stack > .grid-stack-item { min-height: %(height)spx }' % {'height': height}

for i in range(N):
	h = height * (i + 1) + margin * i
	print '.grid-stack > .grid-stack-item[data-gs-height="%(index)s"] { height: %(height)spx }' % {'index': i + 1, 'height': h}

for i in range(N):
	h = height * (i + 1) + margin * i
	print '.grid-stack > .grid-stack-item[data-gs-min-height="%(index)s"] { min-height: %(height)spx }' % {'index': i + 1, 'height': h}

for i in range(N):
	h = height * (i + 1) + margin * i
	print '.grid-stack > .grid-stack-item[data-gs-max-height="%(index)s"] { max-height: %(height)spx }' % {'index': i + 1, 'height': h}

for i in range(N):
	h = height * i + margin * i
	print '.grid-stack > .grid-stack-item[data-gs-y="%(index)s"] { top: %(height)spx }' % {'index': i , 'height': h}
```

Pavel Reznikov's avatar
Pavel Reznikov committed
311
There are at least two more issues with gridstack in IE8 with jQueryUI resizable (it seems it doesn't work) and
312
droppable. If you have any suggestions about support of IE8 you are welcome here: https://github.com/gridstack/gridstack.js/issues/76
Pavel Reznikov's avatar
Pavel Reznikov committed
313

Pavel Reznikov's avatar
Pavel Reznikov committed
314
315
316
317
318
319
## Use with require.js

If you're using require.js and a single file jQueryUI please check out this
[Stackoverflow question](http://stackoverflow.com/questions/35582945/redundant-dependencies-with-requirejs) to get it
working properly.

320
321
Changes
=====
Pavel Reznikov's avatar
Pavel Reznikov committed
322

323
View our change log [here](https://github.com/gridstack/gridstack.js/tree/develop/doc/CHANGES.md).
Dylan Weiss's avatar
Dylan Weiss committed
324

325

Pavel Reznikov's avatar
team    
Pavel Reznikov committed
326
327
328
The Team
========

329
gridstack.js is currently maintained by [Pavel Reznikov](https://github.com/troolee) and [Dylan Weiss](https://github.com/radiolips). We appreciate [all contributors](https://github.com/gridstack/gridstack.js/graphs/contributors) for help.