=== Post and Product Grid for Elementor – Blog & WooCommerce Layout Addon ===
Contributors: maidulcu
Tags: post grid, elementor, woocommerce, posts, grid
Requires at least: 5.0
Tested up to: 7.0.2
Stable tag: 1.6.0
Requires PHP: 5.6
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Build advanced post and product layouts with grid, masonry, list, and slider modes. Includes a standalone Shortcode Builder with drag-and-drop blocks, 10 hover effects, AJAX filtering, transient caching, REST API, and Abilities API. Works with Elementor or any page builder.

== Description ==

Dynamic Post Grid is a powerful and flexible plugin for displaying posts, pages, custom post types, and WooCommerce products in beautiful grid, masonry, list, and slider layouts. It works as an Elementor addon and also includes a standalone Shortcode Builder so you can create post grids anywhere — in the Block Editor, classic themes, widgets, or page builders.

**What makes this plugin different?** Unlike other grid plugins that give you fixed templates to pick from, Dynamic Post Grid uses a block-based layout builder. Each grid is a JSON document describing individual blocks — this makes layouts serializable, exportable, shareable, and composable in ways fixed templates cannot match.

### Core Features

* **Elementor Widget** — Drag-and-drop post/product grids directly inside Elementor with 7 layout styles and full styling controls.
* **Standalone Shortcode Builder** — Build custom post grids with a visual drag-and-drop block editor. No Elementor required.
* **3 Layout Modes** — Grid, Masonry, and List layouts with responsive columns.
* **14 Block Types** — Thumbnail, title, meta, excerpt, read more, terms, divider, spacer, custom HTML, button, price, rating, custom field, and slider.
* **10 Hover Effects** — Zoom In, Zoom Out, Grayscale to Color, Blur, Brightness, Overlay Fade, Overlay Slide Up, Overlay Slide Left, Overlay Scale, and Border Draw.
* **AJAX Category Filtering** — Category filter buttons that reload the grid without page refresh.
* **Load More Pagination** — AJAX-powered load more button for paginated grids.
* **8 Style Presets** — Built-in layout presets plus save and reuse your own custom presets.
* **WooCommerce Ready** — Display products with price, ratings, add-to-cart buttons, and sale badges.
* **Transient Caching** — Server-side caching for grid output with automatic invalidation.
* **REST API** — Full API access to grid data for headless/decoupled usage.
* **Abilities API** — WordPress 6.9+ AI-agent-ready abilities for programmatic grid operations.

== Installation ==

1. Go to **Plugins > Add New** and search for "Dynamic Post Grid Elementor Addon".
2. Install and activate the plugin.
3. **Elementor users:** The widget appears under "WPC Elements" in the Elementor panel.
4. **Shortcode users:** Go to **Grid Shortcodes > Add New** in your admin to create a layout, then copy the shortcode.

== Frequently Asked Questions ==

= Does the plugin require Elementor? =

The Elementor widget requires Elementor 3.0 or higher. However, the **Standalone Shortcode Builder** works independently — you can use the `[depg_grid]` shortcode in the Block Editor, classic editor, widgets, or any page builder.

= How do I use the Shortcode Builder? =

Go to **Grid Shortcodes > Add New** in your WordPress admin. Give your layout a title, configure the query settings (post type, columns, etc.), drag blocks into the layout builder, and publish. Copy the generated shortcode and paste it into any post, page, or widget area.

= What layout modes are available? =

Three layout modes are available in the Post Query settings:

* **Grid** — Classic column-based grid layout.
* **Masonry** — Pinterest-style layout with CSS columns (no JavaScript dependency).
* **List** — Horizontal layout with featured image on the left and content on the right.

You can also override the layout mode via shortcode attribute:

`[depg_grid id="123" layout_mode="masonry"]`

= How do hover effects work? =

Hover effects are configured per Thumbnail block. In the Layout Builder, click **Settings** on a Thumbnail block and select a hover effect from the dropdown. Available effects:

* **Zoom In** — Image scales up on hover.
* **Zoom Out** — Image starts zoomed and scales to normal on hover.
* **Grayscale to Color** — Image transitions from black-and-white to full color.
* **Blur** — Image blurs on hover.
* **Brightness** — Image brightens on hover.
* **Overlay Fade** — Dark overlay with link icon fades in.
* **Overlay Slide Up** — Dark overlay slides up from bottom.
* **Overlay Slide Left** — Dark overlay slides in from the right.
* **Overlay Scale** — Circular overlay expands from center (Material Design style).
* **Border Draw** — Blue border appears on hover.

= How does AJAX filtering work? =

Enable filtering in the Post Query section by checking "Show category filter buttons". On the frontend, clicking a filter button reloads the grid content via AJAX without a page refresh. The filter respects your category restrictions — if you limit the grid to specific categories, only those categories appear as filter buttons.

You can also enable it via shortcode attribute:

`[depg_grid id="123" filter="yes" filter_tax="category"]`

= How does Load More work? =

Enable Load More in the Post Query section by checking "Show Load More button". A "Load More (X remaining)" button appears below the grid. Clicking it loads the next page of posts via AJAX and appends them to the grid. The button disappears when all posts are loaded.

You can also enable it via shortcode attribute:

`[depg_grid id="123" load_more="yes"]`

= How does caching work? =

Grid output is cached using WordPress transients for 1 hour by default. Cache is automatically invalidated when:

* A post is saved, deleted, or its status changes.
* A grid shortcode is updated.
* You click "Clear All Grid Cache" in the Shortcode Builder.

You can change the cache duration with the `depg_cache_duration` filter:

`add_filter( 'depg_cache_duration', function() { return 30 * MINUTE_IN_SECONDS; } );`

= What is the REST API? =

All grid data is available via REST API for headless/decoupled usage:

`GET /wp-json/depg/v1/grid/{id}`

Optional parameters: `page`, `per_page`, `filter` (term ID), `taxonomy`, `layout_mode`.

The response includes structured post data (title, permalink, excerpt, author, featured image, terms) and paging information. No authentication required.

= What is the Abilities API? =

On WordPress 6.9+, the plugin registers 5 AI-agent-ready abilities that can be discovered and executed by AI agents, automation tools (Zapier, n8n), and MCP servers:

* `dynamic-post-grid/render-grid` — Render a grid as HTML.
* `dynamic-post-grid/get-grid-data` — Get structured post data as JSON.
* `dynamic-post-grid/create-shortcode` — Create a new grid programmatically.
* `dynamic-post-grid/export-layout` — Export a grid layout as portable JSON.
* `dynamic-post-grid/import-layout` — Import a layout JSON.

= Can I override shortcode settings in the shortcode itself? =

Yes. You can pass any of these attributes to override the saved settings:

`[depg_grid id="123" layout_mode="masonry" columns="2" per_page="12" orderby="title" order="ASC" filter="yes" load_more="yes"]`

Available attributes: `id` (required), `layout_mode` (grid/masonry/list), `columns` (1-4), `per_page` (number of posts), `orderby` (date, title, ID, modified, rand, menu_order), `order` (ASC or DESC), `filter` (yes/1/true), `filter_tax` (taxonomy slug), `load_more` (yes/1/true).

= Can I save my own layout presets? =

Yes. Build a layout in the Shortcode Builder, click **Save Current as Preset**, enter a name, and save. Your custom presets appear in the **My Presets** dropdown alongside the built-in presets.

= Can I export and import grid layouts? =

Yes. Use the REST API or Abilities API to export a grid configuration as JSON. The JSON contains the full settings and block configuration. Import it on another site to create an identical grid.

= Does it work with WooCommerce products? =

Yes. Select "Product" as the post type in the query settings. The shortcode builder includes Price and Rating blocks specifically for WooCommerce products.

= Does this plugin work with all themes? =

Yes. It works with all WordPress themes.

== Shortcode Reference ==

### Basic Usage

`[depg_grid id="123"]`

### All Attributes

`[depg_grid id="123" layout_mode="grid" columns="3" per_page="6" orderby="date" order="DESC" filter="yes" filter_tax="category" load_more="yes"]`

| Attribute | Type | Default | Description |
|---|---|---|---|
| `id` | integer | (required) | Shortcode post ID |
| `layout_mode` | string | grid | Layout mode: `grid`, `masonry`, or `list` |
| `columns` | integer | 3 | Number of columns (1-4) |
| `per_page` | integer | 6 | Posts per page (-1 for all) |
| `orderby` | string | date | Sort by: `date`, `title`, `ID`, `modified`, `rand`, `menu_order` |
| `order` | string | DESC | Sort direction: `ASC` or `DESC` |
| `filter` | string | no | Show filter buttons: `yes`, `1`, or `true` |
| `filter_tax` | string | auto | Taxonomy for filter buttons |
| `load_more` | string | no | Show Load More button: `yes`, `1`, or `true` |

### REST API

**Endpoint:** `GET /wp-json/depg/v1/grid/{id}`

**Parameters:** `page`, `per_page`, `filter` (term ID), `taxonomy`, `layout_mode`

**Response:**
```json
{
  "settings": {
    "post_type": "post",
    "layout_mode": "grid",
    "columns": 3,
    "per_page": 6,
    "orderby": "date",
    "order": "DESC"
  },
  "blocks": [...],
  "posts": [
    {
      "id": 123,
      "title": "Hello World",
      "permalink": "https://example.com/hello-world/",
      "excerpt": "This is a sample post...",
      "date": "2026-07-18T10:00:00+00:00",
      "author": { "id": 1, "name": "Admin" },
      "featured_image": { "src": "...", "alt": "..." },
      "terms": [{ "taxonomy": "category", "name": "Uncategorized" }]
    }
  ],
  "paging": {
    "current_page": 1,
    "max_num_pages": 5,
    "total_posts": 48,
    "remaining": 42
  }
}
```

### Abilities API (WordPress 6.9+)

| Ability | Type | Description |
|---|---|---|
| `dynamic-post-grid/render-grid` | Read-only | Render a grid as HTML |
| `dynamic-post-grid/get-grid-data` | Read-only | Get structured post data as JSON |
| `dynamic-post-grid/create-shortcode` | Write | Create a new grid programmatically |
| `dynamic-post-grid/export-layout` | Read-only | Export layout as portable JSON |
| `dynamic-post-grid/import-layout` | Write | Import a layout JSON |

Execute via: `POST /wp-json/wp-abilities/v1/execute/{ability-name}`

== Screenshots ==

1. Elementor Grid Layout
2. Elementor List Layout
3. Elementor Slider Layout
4. Shortcode Builder — Post Query and Layout Mode selector
5. Shortcode Builder — Layout Canvas with Drag-and-Drop Blocks
6. Style Presets Dropdown
7. Frontend — Grid Layout with Filter Buttons
8. Frontend — Masonry Layout
9. Frontend — List Layout
10. Frontend — Hover Effects Showcase
11. Frontend — Load More Button
12. Cache Controls in Admin

== Changelog ==

= 1.6.0 =
* [Feature] Masonry layout mode — Pinterest-style CSS column layout, responsive (3/2/1 columns).
* [Feature] List layout mode — horizontal layout with featured image on left, content on right, responsive stacking on mobile.
* [Feature] 10 thumbnail hover effects — Zoom In, Zoom Out, Grayscale to Color, Blur, Brightness, Overlay Fade, Overlay Slide Up, Overlay Slide Left, Overlay Scale, Border Draw.
* [Feature] Transient-based caching for grid output (1 hour default, filterable).
* [Feature] Auto cache invalidation on post save, delete, and status change.
* [Feature] "Clear All Grid Cache" button in Shortcode Builder.
* [Feature] REST API endpoint — `GET /wp-json/depg/v1/grid/{id}` for headless/decoupled usage.
* [Feature] Abilities API — 5 AI-agent-ready abilities for WordPress 6.9+ (render-grid, get-grid-data, create-shortcode, export-layout, import-layout).
* [Feature] Shortcode attribute `layout_mode` — override layout mode via `[depg_grid id="123" layout_mode="masonry"]`.
* [Fix] Exclude IDs, Offset, Ignore Sticky Posts, Post Parent, and Meta Query fields now save correctly in the Shortcode Builder.
* [Fix] `$featured_image` undefined variable notice for posts without thumbnails in REST API response.
* [Fix] Help page now documents current shortcode attributes instead of legacy Elementor widget attributes.
* [Security] Abilities API — all block types individually sanitized with proper escaping (wp_kses_post for HTML, esc_url_raw for URLs, sanitize_key for keys, etc.).
* [Security] Abilities API — import-layout now passes blocks through `sanitize_block_for_ability()` before storage.
* [Security] Abilities API — block type whitelist prevents unknown types from being stored.
* [Security] Abilities API — layout_mode values sanitized with `sanitize_key()` in create-shortcode and import-layout.
* [Security] Admin save logic — layout_mode sanitized with `sanitize_key()` on save.
* [UI] Admin form modernized with flexbox grid layout (no more table-based form).
* [UI] Renamed "Query Settings" to "Post Query" for clarity.
* [Performance] Cache layer reduces database queries for repeated grid renders.

= 1.5.0 =
* [Feature] AJAX category filtering — category filter buttons that reload posts without page refresh.
* [Feature] Load More pagination — AJAX-powered load more button with remaining post count.
* [Feature] Reset to Default — one-click reset in the layout builder restores the default block configuration.
* [Feature] New `filter`, `filter_tax`, and `load_more` shortcode attributes.
* [Feature] Frontend filter and load more settings configurable from the Shortcode Builder UI.
* [UI] Redesigned Post Query section with modern flexbox form grid layout.
* [UI] Renamed "Query Settings" to "Post Query" for clarity.
* [Fix] Removed unused auto-preset detection that cleared the dropdown on block changes.

= 1.4.0 =
* [Feature] Slider carousel block — Swiper 11 carousel with configurable slides per view, autoplay, loop, arrows, and dots.
* [Feature] Button block — customizable text, optional custom URL, and target selection.
* [Feature] Price block — WooCommerce product price with optional prefix/suffix.
* [Feature] Rating block — WooCommerce star rating with optional review count.
* [Feature] Custom Field block — display any post meta value with an optional label.
* [Fix] Shortcode builder now works without Elementor.
* [Fix] Meta block date checkbox label missing opening tag in JS palette template.

= 1.3.0 =
* [Feature] Standalone Shortcode Builder with visual drag-and-drop layout blocks.
* [Feature] 8 built-in style presets and custom user presets.
* [Feature] Category/taxonomy filtering in the shortcode builder.
* [Fix] Block settings now save correctly on every input change.
* [Fix] Block settings keys map correctly between JS and PHP.

= 1.2.6 =
* [Fix] Restore Slick core stylesheet registration.
* [Fix] Respect taxonomy relation setting and harden term markup escaping.

= 1.2.5 =
* [Fix] Add to Cart button icon overwrite fix.

= 1.2.4 =
* [Fix] Category, tag, and status-based filtering issues.
* [Style] Product grid, list, and slider layout improvements.

= 1.2.3 =
* [Fix] Product grid bug fix.
* [Style] CSS updates.

= 1.2.2 =
* [Feature] WooCommerce product grid support with layout template.

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.6.0 =
Masonry and List layouts, 10 hover effects, transient caching, REST API, Abilities API (AI-agent-ready), security hardening, and multiple bug fixes.

= 1.5.0 =
AJAX filtering, Load More pagination, Reset to Default, and a modernized admin form layout.

= 1.4.0 =
New block types: Slider carousel (Swiper), Button, Price, Rating, and Custom Field. The shortcode builder now loads independently of Elementor.

= 1.3.0 =
Major update — new standalone Shortcode Builder with drag-and-drop blocks, style presets, and WooCommerce support. No changes required for existing Elementor widget users.