README.txt in GridStack 8

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


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

    /libraries/gridstack/dist/gridstack.min.js (required by js-driven front-end)
    /libraries/gridstack/dist/gridstack.all.js (required by admin UI)

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.4.0.

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, Layout Builder, 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:
https://www.drupal.org/docs/8/extending-drupal-8/installing-drupal-8-modules


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, Layout Builder, 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.
  Be sure to fill out the required Grid library to make it work with core Layout
  Builder. It won't be loaded at front-end, only needed at admin pages, so be
  sure you have a theme, or module, which loads it at front-end.

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".
    Disabled once saved to avoid issues.
  - 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.


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

THIRD PARTY MATERIALS
gridstack.js

The version of gridstack.js included in this project is a derived from
gridstack.js 0.3.0-dev
http://troolee.github.io/gridstack.js/
(c) 2014-2016 Pavel Reznikov, Dylan Weiss.
It was licensed under the MIT license.

It has been modified by Gaus Surahman to work with Drupal.
The modified version removed deprecated methods worth ~20Kb minified (half),
suitable only for static grid option as normally seen at static frontend.

gridstack.css

The version of gridstack.css included in this project is a derived from
gridstack.css 0.3.0-dev
http://troolee.github.io/gridstack.js/
(c) 2014-2016 Pavel Reznikov, Dylan Weiss.
It was licensed under the MIT license.

It has been modified by Gaus Surahman to work with Drupal.
The modified version provided modularity which is not accommodated by
the original file.


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/