=== FrameGrid ===
Contributors: sbinternet
Tags: gallery, image gallery, masonry, lightbox, photo gallery
Requires at least: 6.6
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Lightweight image galleries with grid, masonry and justified layouts, hover effects, filters and a built-in lightbox.

== Description ==

FrameGrid adds a gallery block, a native Divi 5 module, saved galleries, and a `[framegrid]` shortcode. It is built to stay small: the three layouts are pure CSS, and the only script (under 4 KB gzipped, no jQuery) is loaded only on pages whose galleries use the lightbox, filters or entrance animations.

Features:

* Grid, masonry and justified-row layouts
* Separate column counts for desktop, tablet and mobile
* Grid crop shapes: square, 4:3, 3:2, 16:9, 3:4, 2:3 or original
* Adjustable spacing and corner radius
* Hover effects: zoom, lift, grayscale to color, dim
* Soft or strong shadows
* Captions below the image, as an overlay, or as an overlay on hover
* Fade or fade-and-rise entrance animations (skipped when visitors prefer reduced motion)
* Built-in lightbox with keyboard, swipe, captions, a counter and preloading of the next and previous images
* Filter buttons built from per-image tags
* Per-image custom links
* Optional shuffled order
* Responsive `srcset` and native lazy loading from WordPress core
* Native Divi 5 module with a live Visual Builder preview
* Saved galleries under **Galleries** in wp-admin, placed anywhere with a short `[framegrid id="…"]` code
* No settings page, no custom tables, no external services

Native Divi 5 integration is included. Find **FrameGrid Gallery** in the Divi 5 module library; it has the same options as the block, with images chosen in Divi's own gallery picker. The builder preview is rendered by the same code as the published page. Justified rows use the CSS-only layout in the builder and are fine-tuned on the published page.

== Installation ==

1. Upload the `framegrid` folder to `/wp-content/plugins/`, or install the ZIP through Plugins > Add Plugin > Upload Plugin.
2. Activate FrameGrid.
3. Edit a post or page and add the **FrameGrid Gallery** block, or add the **FrameGrid Gallery** module in the Divi 5 Visual Builder.
4. Pick images, then set the layout, effects, captions, links and filters in the block sidebar or module settings.

For Divi 4, other page builders, widgets or the classic editor, go to **Galleries > Add New Gallery**, build the gallery, publish it, and paste its shortcode (shown in the sidebar and in the Galleries list) wherever you want it.

== Shortcode ==

Use the shortcode in classic content, widgets, Divi 4, or another page builder's text or code module.

The easiest way is a saved gallery. Create it under **Galleries**, then paste its shortcode:

`[framegrid id="42"]`

Editing the gallery updates every page that uses it. Only published galleries are shown to visitors; drafts are visible only to people who can edit them, so you can preview a draft inside your page builder.

You can also build a gallery inline, without saving it first:

`[framegrid ids="12,15,18,21" layout="masonry" columns="4" hover="grayscale" captions="hover"]`

Inline attributes and their defaults:

* `ids`: comma-separated attachment IDs (required)
* `layout`: `grid`, `masonry` or `justified` (default `grid`)
* `columns`, `columns_tablet`, `columns_mobile`: `3`, `2`, `1`
* `aspect_ratio`: `1/1`, `4/3`, `3/2`, `16/9`, `3/4`, `2/3` or `original` (grid layout only; default `1/1`)
* `row_height`: target row height in px for the justified layout (default `240`)
* `gap`: spacing in px (default `12`)
* `radius`: corner radius in px (default `4`)
* `image_size`: any registered image size (default `large`)
* `hover`: `zoom`, `lift`, `grayscale`, `dim` or `none` (default `zoom`)
* `captions`: `none`, `below`, `overlay` or `hover` (default `none`)
* `caption_source`: `caption` or `title` (default `caption`)
* `link`: `lightbox`, `file`, `attachment`, `custom` or `none` (default `lightbox`)
* `lightbox_captions`: `true` or `false` (default `true`)
* `new_tab`: open file, attachment and custom links in a new tab (default `false`)
* `filters`: show filter buttons (default `false`)
* `filter_all_label`: label for the "All" button
* `shadow`: `none`, `soft` or `strong` (default `none`)
* `animation`: `none`, `fade` or `rise` (default `none`)
* `random`: shuffle order on each page load (default `false`)

== Frequently Asked Questions ==

= How do I set a custom link or filter tags for an image? =

Open the image in the Media Library (or in the block's "Edit images" window) and fill in **Gallery link** and **Gallery filters**. Filters are comma-separated, e.g. "Weddings, Portraits". Both are saved on the image, so they apply in every gallery that uses it.

= Does it work without JavaScript? =

Yes. Layouts, hover effects and captions are CSS. Without JavaScript, lightbox images open as plain image files and filter buttons stay hidden.

= Does shuffled order work with page caching? =

The order is shuffled when the page is generated, so a cached page shows the same order until the cache is cleared.

= Why do masonry images run down the columns? =

Masonry uses CSS columns so it needs no layout script and doesn't jump around while images load. Images fill the first column top to bottom, then the next. Use the justified layout if you need left-to-right order.

= How do I change the colour of the active filter button? =

Set `--fg-accent` (background) and `--fg-accent-text` (text) on `.framegrid` in your theme CSS.

= Where is the build source? =

The Divi 5 Visual Builder bundle is built from editable source shipped in the plugin itself: `divi/visual-builder/src/` plus `package.json` and `webpack.config.js` in `divi/visual-builder/`. Run `npm install && npm run build` there to regenerate `divi/visual-builder/build/`. The Gutenberg block and front-end files (`block/index.js`, `assets/framegrid.js`) need no build step; edit them directly.

== Changelog ==

= 0.2.0 =
* Saved galleries: a Galleries screen in wp-admin with the full block editor and live preview, and a short `[framegrid id="…"]` code for Divi 4, other page builders, widgets and the classic editor.
* Gallery screens always use the block editor, even when Divi's Classic Editor setting is on.
* Stylesheet loads in the page head on pages using the shortcode, and in the Divi 4 Visual Builder.

= 0.1.0 =
* Initial release: Gutenberg block, native Divi 5 module and `[framegrid]` shortcode.
