=== Forma Grid Gallery ===
Contributors: vlthemes
Tags: portfolio, grid, masonry, gallery, filter
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 8.0
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Portfolio and saved grid layouts: grid, masonry, metro, justified, freeform and slider, with AJAX filters, search, pagination and a lightbox.

== Description ==

🌐 [Presentation](https://forma.vlthemes.me/) · 📖 [Documentation](https://vlthemes.me/docs/forma/) · 🧪 [Try it in WordPress Playground](https://playground.wordpress.net/?blueprint-url=https%3A%2F%2Fraw.githubusercontent.com%2Fvlthemes%2Fforma-playground%2Fmain%2Fblueprint.json) · 💬 [Ideas or bugs? Tell us](https://wordpress.org/support/plugin/forma-grid-gallery/)

Forma builds portfolio and gallery grids for any WordPress site. You set a layout up once in a visual editor with a live preview, then place it with a block, an Elementor or WPBakery element, or a shortcode. It comes with a Portfolio of its own, and it shows posts, pages, products or Media Library images just as well.

= 🧱 Six layouts =

* Grid, Masonry and Justified rows.
* Metro: repeating patterns of wide, tall and small tiles.
* Freeform: a scattered collage, arranged on its own for each device.
* Slider: slide, fade or coverflow, with autoplay and loop, and slides as wide as their content if you like.

= 🗂️ Any content =

* Portfolio projects, posts, pages, WooCommerce products or any public post type.
* Images picked from the Media Library, each with its own title, caption, link and categories for this grid.
* The categories and tags themselves, as a grid of terms.
* Narrow it down by categories, tags, post formats (Video, Gallery…) and authors, pick or leave out items, match words, or skip what a grid above on the page already shows.

= 🔎 Filters, search and sorting =

* Filter by category or tag and search as you type, without reloading the page.
* Sorting for visitors: newest, A to Z, most viewed, most commented, random and more.
* Page numbers or a Load More button, both keeping the current filter and search.
* Filters and sorting as pills or a dropdown, placed by drag and drop on a toolbar of two rows.
* The chosen filter and order go into the page address, ready to share and bookmark. Filters and pages are real links that search engines follow, and Back and Forward step through them.

= 🎨 Nine card styles =

Default, Fade, Overlay, Caption, Minimal, Magazine, Polaroid, Glass and Mono. Each has settings of its own, and all of them take your theme's colors and fonts.

= 📱 Set per device =

Columns, gaps, the image ratio, tile patterns and row heights for desktop, tablet landscape, tablet and phone, each seen in the live preview.

= 🖼️ Lightbox =

A PhotoSwipe lightbox with swipe, zoom, captions and a share menu, for your grids and, if you like, for WordPress galleries and Image blocks too.

= 📁 A ready portfolio =

* Projects with categories, tags and an archive page you can build with blocks or any page builder.
* View counts: each project's page counts its visits, a Views column shows them, and grids can sort by most viewed.
* The Migration tab moves projects from another portfolio plugin into Forma's in one click. Their IDs, content, images and comments stay, and the move can be undone.

= ⚡ Small and fast =

* Scripts and styles load only on pages that show a grid. A grid needs about 12 KB gzipped: its script, its styles and the card style.
* The slider's script and the lightbox (about 25 KB) load only for grids that use them.
* The front end needs no jQuery or other framework, and filters, search and pages fetch only the new items' HTML.
* Images are served at the size the layout needs, from the sizes WordPress already makes.

= 🔍 SEO-friendly =

Filters and pages are real links. Portfolio category and tag pages get their own canonical address, title and description, with WordPress alone or with Yoast SEO, Rank Math or AIOSEO.

= 🧩 Works with your theme =

Cards, filters, search and pagination are templates your theme can restyle or replace, and a theme can switch Forma's own look off. Custom CSS can be added to one layout only.

= 🤖 Works with AI assistants =

Forma's actions are WordPress abilities: AI tools connected to your site can list, build and change Forma Layouts and projects, with the rights of your user.

= 🌍 Every language =

Translation ready, and right-to-left languages are supported: layouts, the slider and the lightbox follow the page direction.

= 👥 Roles =

Choose which roles add projects, build Forma Layouts or change the settings.

= ✨ Forma Pro =

[Forma Pro](https://vlthemes.gumroad.com/l/forma-pro) is a separate plugin that includes everything above, and adds:

* 🪄 Describe your grid: write a sentence about the grid you want, and the AI connected to your WordPress sets it up.
* 🌀 Six animated card styles: Tilt, Drift, Cursor, Brush, Cube and Glide.
* 🎞️ Marquee layout: items in a row that moves on by itself, turning round as the page scrolls up; visitors can drag and throw it.
* 📋 List layout: an index of your projects, each row's image following the pointer.
* 💖 Client proofing: clients pick their favorite photos from a link and send you the selection.
* 🎬 Video and audio: YouTube, Vimeo, TikTok, Instagram, Spotify, SoundCloud and more in the lightbox; your own video files play in the card.
* 🖼️ Image tools: add images by their address, crop one for a grid, set a featured image from a URL, and save the sizes WordPress makes of your uploads as WebP or AVIF.
* 📷 Camera details under each photo, and image protection per grid.
* 🔧 Also: more entrance animations, inserts (a banner or any shortcode between the items), custom image ratios, drag and drop ordering, several post types in one grid, date and custom field filters, infinite scroll and faster filtering.

= Shortcodes =

Each layout has its shortcode on the Forma Layouts screen. show="filter", "search", "sort" or "pagination" places that control anywhere on the page:

    [forma_grid id="123"]
    [forma_grid id="123" show="filter"]

With the layout on the page more than once, instance="2" makes a control work on its second grid. By default "Output search, filter, sorting and pagination with the grid" is on and the grid prints them around itself; turn it off to place them yourself.

The Grid Layout block, the Elementor widget and the WPBakery element do the same, with the layout and the part picked from a list.

= Theme templates =

Copy any file from the plugin's `templates/` folder to `your-theme/forma/` (same path) to change it. Skins live in `your-theme/forma/skins/{name}/skin.php`, with an optional `style.css` and `script.js` next to it.

= Source code =

Everything the plugin runs is readable in the plugin itself. The block editor scripts in `assets/build` are built with `@wordpress/scripts` (webpack) from the sources shipped next to them: `assets/src` and the `editor.js` of each layout type in `src/Layouts`. The minified stylesheets in `assets/css` are compiled from the Sass in `assets/scss`, and each card style's `style.css` from the `style.scss` beside it in `templates/`. The third-party libraries below are included as their authors publish them.

== Installation ==

= From your dashboard =

1. Go to Plugins → Add New and search for "Forma Grid Gallery".
2. Click Install Now, then Activate.

= By upload =

1. Download the zip, then go to Plugins → Add New → Upload Plugin and choose it (or unzip it into `/wp-content/plugins/`).
2. Activate it on the Plugins screen.

= Your first grid =

1. Go to Forma → Forma Layouts → Add New.
2. Pick the content, the layout and the card style; the preview shows the result as you go.
3. Publish, then add the Forma block, the Elementor widget or the WPBakery element to a page, or paste the layout's shortcode.

Forma needs WordPress 6.5 or later and PHP 8.0 or later.

== Frequently Asked Questions ==

= Does Forma work with my theme? =

Yes. Forma works with any theme, and its card styles take your theme's colors and fonts. To change how something looks, copy its template into `your-theme/forma/`, or add Custom CSS to one layout.

= Does it work with Elementor, WPBakery or the block editor? =

Yes. Forma has a block, an Elementor widget and a WPBakery element, and a shortcode for anything else. Each can place the whole grid, or only its filter, search, sorting or pagination.

= I already use another portfolio plugin. Can I keep my projects? =

Yes. Forma → Settings → Migration moves the items of another plugin's post type into Forma's portfolio, keeping their IDs, content, featured images and comments, and merging their categories and tags. Undo puts everything back. If your theme or another plugin already registers a "portfolio" post type, Forma leaves it alone and shows its items like any other content.

= Can I turn the portfolio post type off? =

Yes, in Forma → Settings → Portfolio. Forma Layouts then get a menu of their own and work with any other content; your projects are kept. The same tab sets the project, category and tag addresses.

= My project pages show "Page not found" =

Go to Settings → Permalinks and click Save Changes once. WordPress then rebuilds its addresses. Forma does this by itself whenever you change the portfolio addresses.

= Can a grid show WooCommerce products, posts or pages? =

Yes. Any public post type can be a grid's content, and so can Media Library images or the categories and tags themselves.

= Is it mobile friendly? =

Yes. Columns, gaps, the image ratio and the patterns can be set for tablets and phones on their own, and the slider and the lightbox follow swipes.

= Will it slow down my site? =

No. Forma loads its scripts and styles only on pages that show a grid, and only what that grid needs: about 12 KB gzipped for a grid, plus about 25 KB for the lightbox where a grid opens one. The front end needs no jQuery.

= How are project views counted? =

When someone opens a project's page, the browser counts one view, so cached pages count too. A visitor counts once per browser session, and your own visits to projects you can edit don't count. Forma stores only the number on the project, nothing about the visitor, and sets no cookies. You can switch it off in Forma → Settings → Portfolio.

= Does Forma work with AI? =

Yes. Forma registers its actions with the WordPress Abilities API (WordPress 6.9 and later), so AI assistants connected to your site can list, create and change Forma Layouts and portfolio items, with the rights of your user. Forma Pro's Describe your grid turns a sentence into a layout's settings with the AI service you connected to WordPress. Forma itself sends nothing to any AI service.

= The lightbox does not open =

Check that it is enabled in Forma → Settings → Lightbox, and that the layout's Click action is set to Lightbox.

= Can I translate Forma? =

Yes. Forma is ready for translation on translate.wordpress.org or with a plugin such as Loco Translate, and it supports right-to-left languages.

= What is the difference between Forma and Forma Pro? =

Forma Pro is a separate plugin that includes everything in Forma and adds the features listed under Forma Pro above. When you activate Pro, it takes over from the free plugin, and your layouts and settings stay as they are.

= I found a bug or have an idea. Where do I tell you? =

In this plugin's [support forum](https://wordpress.org/support/plugin/forma-grid-gallery/). Bug reports and ideas are welcome: say what you did, what you expected and what happened.

= Where can I find the documentation and get help? =

The documentation is at [vlthemes.me/docs/forma](https://vlthemes.me/docs/forma/). For help with the free plugin, open a topic in this plugin's support forum on WordPress.org.

== Screenshots ==

1. Settings: turn the portfolio on, pick its archive page, count project views and set its addresses. Breakpoints, images, filters, the lightbox, messages, roles and migration have tabs of their own.
2. Forma Layouts: each layout's type, content, parts and the pages it is used on, with its shortcode ready to copy.
3. The layout editor: a blog grid with its category filter in the live preview, and its settings in the sidebar.
4. A Metro portfolio grid and its entrance animation, set per device from the bar above the settings.
5. Media Library images: each one gets its own title, description, link and categories for this grid. Adding images from a URL and the Video and Audio formats come with Forma Pro.
6. Client proofing, a Forma Pro feature: visitors pick their favorite images and send you the selection.

== External services ==

The plugin uses no external service: nothing is sent by it, and fonts and scripts are all served from your site.

== Third-party libraries ==

* PhotoSwipe 5.4.4, https://photoswipe.com/, MIT License.
* Swiper 14.3.0, https://swiperjs.com/, MIT License (used only when the theme doesn't load its own).
* Bricolage Grotesque (Fontsource 5.3.0), https://github.com/ateliertriay/bricolage, SIL Open Font License 1.1 (the admin pages' headings).

== Changelog ==

= 1.0.0 =
* First release.
