summaryrefslogtreecommitdiffstats
path: root/README.txt
blob: 0dc29db0864a77b585f187cf5a2150ca64cf888e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
ABOUT
GridStack provides provides integration with gridstack.js as a dynamic layout
builder for both magazine layout, and static float grid layout like Bootstrap,
or Foundation, with drag-and-drop. A few optional field formatters, and Views
style plugin.
See https://troolee.github.io/gridstack.js/,
or https://github.com/troolee/gridstack.js


FEATURES
o Supports magazine layouts, identified by fixed heights.
o Supports static float layouts for Bootstrap, or Foundation, identified by
  auto heights. With Bootstrap 4 flexbox grid, limited magazine layout is
  possible with little CSS overrides.
o Supports optional core Field Layout, DS, Panelizer, Widget modules.
o Responsive grid displays, layout composition, image styles, or multiple unique
  image styles per grid/box.
o Drag and drop layout builder.
o Lazyloaded inline images, or CSS background images with multi-styled images.
o Field formatters for Image, and fieldable entities like File Entity Reference,
  and optional Media Entity and Paragraphs integration. Specific to fieldable
  entities, best when containing core image using Blazy formatters with CSS
  background option enabled. Requires Blazy post Beta5+, optional.
o Optional Views style plugin.
o Optional supports for Colorbox, Photobox, and Blazy Photoswip, or when using
  Blazy Views fields, or Blazy-related formatters from within Views.
o Modular and extensible skins.
o Easy captioning.
o A few simple box layouts.


INSTALLATION
Install the module as usual, more info can be found on:
http://drupal.org/documentation/install/modules-themes/modules-7


USAGE / CONFIGURATION
As Views style plugin:
o Visit admin/structure/gridstack to build a GridStack.
o Visit admin/structure/views, and create a new page or block with GridStack
  style, and assign the designated optionset.
o Use the provided sample to begin with, be sure to read its README.txt.

As field formatters:
o Go to "Manage display" page, e.g.:
  admin/structure/types/manage/page/display

o Find "GridStack" formatters under "Manage display" for supported fields:
  Image, File entity reference, Media Entity, Paragraphs.
  With complex fields like Media Entity or Paragraphs, you can combine GridStack
  formatters with Slick formatters to build unique grid layout for the slider.

As Bootstrap/ Foundation layouts:
This requires any of _optional core Field Layout, DS, Panelizer, or Widget
modules to function.
Please refer to their documentation for better words.

o Visit GridStack UI to enable the static grid support:
  /admin/structure/gridstack/ui

  Choose either Bootstrap, or Foundation under "Grid framework".
  Only one grid framework can exist globally.

o Visit GridStack optionset collection page:
  /admin/structure/gridstack

  - Create, or clone existing "Default Bootstrap", or "Default Foundation".
    The required option: "Use static Grid Bootstrap/Foundation framework".
  - Build a static grid layout with floating boxes in mind, say "Boostrap Hero".
    If a grid breaks, try putting them as nested grids within their own rows.
  - Leave "xl width" option empty if not desired, such as for Bootstrap 3.
    The "XL" grid class is only available at Bootstrap 4.
  - Clone existing optionsets to reduce steps.

o Clear cache whenever updating/ editing existing layouts.
  - Don't always do this when all needed layouts are in place.

o Assign the newly created layouts at any UI for Field, DS, Panels, Panelizer,
  Widget:
  /admin/structure/types/manage/article/display
  /admin/structure/panelizer/edit/node__article__default__default/layout?js=nojs
  /admin/structure/block
  - Put relevant contents to each GridStack region.

REQUIREMENTS
- Blazy module
- GridStack library:
  o Download GridStack from https://github.com/troolee/gridstack.js
  o Extract it as is, rename "gridstack.js-master" to "gridstack", so the assets
    are available at:

    /libraries/gridstack/dist/gridstack.min.js

Note:
GridStack 8.x-1.0-beta4 below requires v0.2.5.
GridStack 8.x-1.0-beta5+ and DEV versions require a minimum v0.3.0 available at
"master" release.


SIMILAR MODULES
http://dgo.to/mason
Both try to solve one problem: empty gaps within a compact grid layout.
Mason uses auto Fillers, or manual Promoted, options to fill in empty gaps.
GridStack uses manual drag and drop layout builder to fill in empty gaps.


ROADMAP
[x] Support multi-styled images to have various sizes, only if doable. Currently
    using CSS background images to solve sizes.
    2/29/16
[x] Multi-breakpoint responsive grid layouts.
    3/11/16
[x] Multi-breakpoint image styles.
    3/14/16
[x] Supports lightbox boxes.
    12/14/16 for Field formatter, or use Blazy for Views images.
[x] Decouple from Views to make GridStack a more generic layout builder.
    2/27/2017
[x] Optional integration with core layout_discovery (core >= 8.x-3) and
    layout_plugin (core < 8.x-3) so that gridstack layouts are exposed to DS,
    Panelizer, Panels, etc.
    3/22/2017
[x] Supports Bootstrap 4 for XL breakpoint.
    3/29/2017
o Use Vanilla JS for frontend.

The following may likely happen by some personal project, or sponsorship.
[x] Field formatter
    12/14/16
[x] Multimedia boxes.
    12/14/16
[x] A generic layout builder for Bootstrap, or Foundation.
    3/22/2017
o Field widget.
o Stamps.
o D7 port.

Feel free to get in touch if you'd like to chip in, or sponsor any. Thanks.


TROUBLESHOOTING
o Be sure the amount of Views results are matching the amount of the grid boxes.
o Follow the natural order keyed by index if trouble with multiple breakpoint
  image styles.
o Clear cache when updating cached Gridstack otherwise no changes are visible
  immediately. You can also disable the Gridstack cache during work.

Below are valid for v0.2.5 below:
o At admin UI, some grid/box may be accidentally hidden at smaller width. If
  that happens, try giving column and width to large value first to bring
  them back into the viewport. And when they are composed, re-adjust them.
  Or hit Clear, Load Grid, Save & Continue buttons to do the reset.
  At any rate saving the form as is with the mess can have them in place till
  further refinement.
o Use the resizable handlers to snap to grid if box dragging doesn't snap.
  Be gentle with it to avoid abrupt mess.
o If trouble at frontend till gridstack library is decoupled from jQuery UI or
  at least till jQuery related issues resolved, for its static grid, check the
  option "Load jQuery UI". If you are a JS guy, you know where the problem is.
  A temporary hacky solution is also available:
  /admin/structure/gridstack/ui


TIPS
To have re-usable different image styles at multiple breakpoints, create them
once based on grid dimensions to easily match them based on the given dimension
hintings, e.g.:
o Box 1x1
o Box 1x2
o Box 2x1
o etc.

Enable GridStack UI and visit "/admin/structure/gridstack" and edit
your working optionset to assign different image styles for each box of the
GridStack. Then you can match those image styles with the provided dimension
hints easily -- 2x2 for Box 2x2, etc. Try giving fair sizes so that they fit
well and have no artifacts at multiple breakpoints.

Or use more simplified image styles like below:
o Box square
o Box tall
o Box tower
o Box wide
o Box panorama

And assign the largest dimensions to avoid artifact.
With "Use CSS background" option enabled, those sizes don't matter much.

Use Blazy formatters to have Colorbox/Photobox/Photoswipe supports.


CURRENT DEVELOPMENT STATUS
A full release should be reasonable after proper feedbacks from the community,
some code cleanup, and optimization where needed. Patches are very much welcome.

Alpha and Beta releases are for developers only. Be aware of possible breakage.

However if it is broken, unless an update is explicitly required, clearing cache
should fix most issues during DEV phases. Prior to any update, open:
/admin/config/development/performance

Re-generate CSS and JS assets, and hit "Clear all caches" button.


KNOWN ISSUES
o Having the exact amount of items to match the optionset grids is a must.
o If you have more items than designated optionset grids, the surplus will not
  be displayed as otherwise broken grid anyway.
o If you have less items, the GridStack will not auto-fix it for you.
  Simply providing the exact amount of items should make it gapless grid again.
o Not compatible with Responsive image OOTB. GridStack has its own managed
  multi-styled images per breakpoint.
o Nested grids are only supported by static grid Bootstrap/ Foundation, not JS.


AUTHOR/MAINTAINER/CREDITS
gausarts

Contributors:
https://www.drupal.org/node/2672858/committers

READ MORE
See the project page on drupal.org: http://drupal.org/project/gridstack

See the GridStack JS docs at:
o https://github.com/troolee/gridstack.js
o http://troolee.github.io/gridstack.js/