# FooBox Gutenberg Usage Guide

This guide explains how to set up FooBox content from the WordPress block editor using the Gutenberg features added in this branch. It focuses on editor workflows, not hand-written HTML. For raw HTML examples and lower-level attributes, see `docs/usage.md`.

## Requirements

- Edit content in the WordPress block editor.
- Use one of the supported core blocks:
  - Button
  - Image
  - Gallery
  - Group
- Select the block, open the block inspector sidebar, and use the "FooBox" panel.
- For Image and Gallery blocks, make sure images link to the media file unless you use the WordPress Lightbox override described below.

## Global Setup

Before building examples, review these settings in FooBox settings.

### Default Image Link

Location: General > Compatibility > Default Image Link.

Use this to set WordPress's default image link behavior. FooBox works best when inserted images link to the media file.

### Auto Link Existing Images

Location: General > Compatibility > Auto Link Existing Images.

Use this for older content where attachment images were inserted without media links. FooBox can automatically wrap eligible attachment images so they open in the lightbox.

### WordPress Lightbox

Location: General > Compatibility > WordPress Lightbox.

This setting is off by default for upgrade safety. When enabled, FooBox takes over core Image and Gallery blocks that are configured with WordPress's own "Open in lightbox" option. FooBox disables the core lightbox for those blocks, switches them to media links, and applies FooBox attributes.

This covers:

- Image blocks with `lightbox.enabled`.
- Gallery blocks with `linkTo: "lightbox"`.
- Existing content on render, through a frontend fallback.

## The FooBox Panel

The block editor adds a "FooBox" panel to supported core blocks.

Common fields:

- "Enable FooBox" turns a Button, Image, or Gallery block into a FooBox trigger.
- "Use as hidden FooBox content" turns a Group block into inline content that another trigger can open.
- "Style" sets the modal style: Default, Rounded, Flat, Metro, or Glass.
- "Theme" sets the modal theme: Default, Light, or Dark.
- "Opening effect" sets the open/close effect. Pro exposes the full effect list.
- "Gallery group" groups multiple FooBox items together.
- "Width" and "Height" set item dimensions.

Image-only fields:

- "Link image to media file" updates the Image block to link to the full media file.
- "Enable large image panning" enables overflow/panning behavior for large images.
- "Maximum image width" and "Maximum image height" set image sizing limits.
- "Caption title" and "Caption description" set explicit FooBox captions.

Button-only fields:

- "Content type" sets the link type: Auto-detect from URL, Image, HTML content, Iframe, or Video.
- "Lightbox URL or target" sets the URL or selector opened by FooBox.
- "Select from media library" opens the WordPress media modal and fills "Lightbox URL or target" with the selected attachment URL.
- "Poster image URL" appears for Video content and is used for self-hosted video posters.
- "Choose poster image", "Replace poster image", and "Remove poster image" manage the poster image through the media library.

Gallery-only fields:

- "Link gallery images to media files" updates the Gallery block to link nested images to media files.
- Gallery style, theme, effect, and group settings are mirrored onto the child Image blocks before save.

Group-only fields:

- "HTML id" sets the inline content target id.
- "Generate id" creates a stable id such as `foobox-content-abc12345`.
- "Hide on front end" hides the content container on the frontend.

## Single Image

Use the core Image block.

Steps:

1. Add an Image block and choose an image.
2. Select the Image block.
3. Open the FooBox panel.
4. Enable FooBox.
5. If shown, click "Link image to media file".
6. Choose optional Style, Theme, Opening effect, Caption title, and Caption description.
7. Save or preview the page.

Saved behavior:

- The figure receives the `foobox` class and FooBox data attributes.
- The image link receives FooBox link attributes such as captions, group, and sizing.
- If the WordPress Lightbox compatibility setting is enabled, an Image block using "Open in lightbox" is converted to this same FooBox setup.

## Multiple Images

Use the core Gallery block.

Steps:

1. Add a Gallery block and select multiple images.
2. Select the Gallery block, not an individual image inside the gallery.
3. Open the FooBox panel.
4. Enable FooBox.
5. If shown, click "Link gallery images to media files".
6. Set a Gallery group, or leave it blank and let the editor generate one when converting from WordPress lightbox.
7. Choose optional Style, Theme, and Opening effect.
8. Save or preview the page.

Saved behavior:

- The Gallery remains normal core Gallery markup.
- FooBox settings are mirrored onto the nested Image blocks.
- Gallery images are grouped with `data-foobox-group`, which avoids relying on global REL Grouping.
- If the WordPress Lightbox compatibility setting is enabled, a Gallery block using "Open in lightbox" is converted to media links and grouped for FooBox.

## HTML Content

Use a hidden Group block for the content and a Button block for the trigger.

Steps:

1. Add a Group block.
2. Build the content inside the Group using normal blocks.
3. Select the Group block.
4. Open the FooBox panel.
5. Enable "Use as hidden FooBox content".
6. Set an HTML id, or click "Generate id".
7. Leave "Hide on front end" enabled unless the content should also be visible on the page.
8. Add a Button block where users should click.
9. Select the Button block.
10. Open the FooBox panel and enable FooBox.
11. Set Content type to "HTML content".
12. Set "Lightbox URL or target" to the Group id with a leading `#`, for example `#demo-hidden-html`.
13. Set Width and Height as needed.

Saved behavior:

- The Group block receives a frontend id and hidden-content class.
- The Button block opens that Group content in FooBox.
- The Button wrapper receives `foobox`; the inner link receives `target="foobox"` and size attributes.

## YouTube Video

Use a Button block.

Steps:

1. Add a Button block.
2. Select the Button block.
3. Open the FooBox panel and enable FooBox.
4. Set Content type to "Video" or leave it as "Auto-detect from URL".
5. Set "Lightbox URL or target" to the YouTube URL.
6. Set Width and Height, usually `960` by `540` for 16:9 video.
7. Choose optional Style, Theme, Opening effect, and captions.

Saved behavior:

- The Button opens the YouTube URL in FooBox.
- FooBox detects the video handler from the URL when the content type is auto.

## Self Hosted Video

Use a Button block.

Steps:

1. Upload or select the video in the media library.
2. Add a Button block.
3. Select the Button block.
4. Open the FooBox panel and enable FooBox.
5. Set Content type to "Video".
6. Set "Lightbox URL or target" to the video file URL, or click "Select from media library" and choose the uploaded video.
7. Set Width and Height.
8. Add a Poster image URL, or use "Choose poster image".
9. Choose optional Style, Theme, Opening effect, and captions.

Saved behavior:

- The Button opens the uploaded video in FooBox.
- The poster image is saved as `data-cover` on the link.

## HTML Content With A Form

Use a hidden Group block containing a Shortcode block, then open it from a Button block.

Steps:

1. Add a Group block.
2. Inside the Group, add a Shortcode block.
3. Add the form shortcode, for example `[gravityform id="10" ajax="true" title="true"]`.
4. Select the Group block.
5. Open the FooBox panel.
6. Enable "Use as hidden FooBox content".
7. Set an HTML id such as `demo-hidden-form`.
8. Keep "Hide on front end" enabled.
9. Add a Button block.
10. Select the Button block and enable FooBox.
11. Set Content type to "HTML content".
12. Set "Lightbox URL or target" to `#demo-hidden-form`.
13. Set Width and Height, for example `550` by `550`.
14. Choose optional Style, Theme, and Opening effect.

Saved behavior:

- The form remains editable as normal block content.
- FooBox opens the rendered hidden Group content.
- AJAX forms can continue to work inside the lightbox when the form plugin supports inline rendering.

## Iframe

Use a Button block.

Steps:

1. Add a Button block.
2. Select the Button block.
3. Open the FooBox panel and enable FooBox.
4. Set Content type to "Iframe".
5. Set "Lightbox URL or target" to the page URL.
6. Set Width and Height.
7. Choose optional Style, Theme, Opening effect, and captions.

Saved behavior:

- The Button link receives `target="foobox"`.
- FooBox opens the URL as iframe content.

## FooGallery Shortcode In HTML Content

Use a hidden Group block containing a Shortcode block, then open it from a Button block.

Steps:

1. Add a Group block.
2. Inside the Group, add a Shortcode block.
3. Add the FooGallery shortcode, for example `[foogallery id="123"]`.
4. Select the Group block.
5. Open the FooBox panel.
6. Enable "Use as hidden FooBox content".
7. Set an HTML id such as `demo-hidden-foogallery`.
8. Keep "Hide on front end" enabled.
9. Add a Button block.
10. Select the Button block and enable FooBox.
11. Set Content type to "HTML content".
12. Set "Lightbox URL or target" to `#demo-hidden-foogallery`.
13. Set Width and Height large enough for the gallery content, for example `900` by `650`.

Saved behavior:

- The FooGallery shortcode remains in normal WordPress content.
- FooBox opens the rendered shortcode output as hidden inline content.

## Large Image With Panning

Use the core Image block.

Steps:

1. Add an Image block and choose a large image.
2. Select the Image block.
3. Open the FooBox panel and enable FooBox.
4. If shown, click "Link image to media file".
5. Enable "Enable large image panning".
6. Set Width and Height to the intended lightbox size.
7. Set Maximum image width and Maximum image height if the image should be capped.
8. Choose optional Style, Theme, Opening effect, and captions.
9. In FooBox Pro settings, set "Panning Overview Position" to a visible position if the overview control should show.

Saved behavior:

- The image link receives `data-overflow`.
- FooBox Pro's panning add-on can show the panning overview and allow the large image to be dragged/scrolled in the lightbox.

## Image Themes, Captions, And Effects

Use Image or Button blocks when you need per-item visual overrides.

Steps:

1. Select the block that opens FooBox.
2. Open the FooBox panel and enable FooBox.
3. Choose Style:
   - Default
   - Rounded
   - Flat
   - Metro
   - Glass
4. Choose Theme:
   - Default
   - Light
   - Dark
5. Choose Opening effect:
   - Default
   - None
   - Zoom in
   - Slide from right
   - Slide from bottom
   - Newspaper
   - Fall
   - Slide fall
   - Flip horizontal
   - Flip vertical
   - Fold down
   - Super scaled
   - Swing from bottom
   - Swing from left
6. For Image and Button blocks, fill Caption title and Caption description when the caption should be explicit.

Saved behavior:

- Style is saved as `data-style`.
- Theme is saved as `data-theme`.
- Opening effect is saved as `data-effect`.
- Captions are saved as `data-caption-title` and `data-caption-desc`.
- Empty optional settings are not serialized.

## Grouping Rules

Gutenberg-created galleries use `data-foobox-group` instead of relying on `rel`.

Use the same Gallery group value when independent Image or Button triggers should open as one FooBox gallery. For Gallery blocks, set the group on the Gallery block so the editor can mirror it to child Image blocks.

Important behavior:

- `data-foobox-group` takes precedence over legacy `rel` grouping.
- The same group value on separate items makes them part of one lightbox collection.
- Leaving the group blank creates independent items unless a Gallery conversion generates a group.

## Hidden Content Pattern

The branch introduces a first-class hidden-content pattern using core blocks.

Use this pattern when a visible Button should open content that exists elsewhere on the page:

1. Create the content in a Group block.
2. Enable "Use as hidden FooBox content" on the Group.
3. Give the Group a unique HTML id.
4. Keep "Hide on front end" enabled.
5. Create a Button.
6. Enable FooBox on the Button.
7. Set Content type to "HTML content".
8. Point the Button target to `#the-group-id`.

This replaces the old workflow of writing a hidden `div` by hand in a Custom HTML block.

## WordPress Lightbox Takeover

The WordPress Lightbox compatibility setting is off by default and must be enabled intentionally. Once enabled, it makes core lightbox choices route through FooBox.

Image behavior:

- If an Image block has WordPress "Open in lightbox" enabled, FooBox enables itself on that image.
- The image is switched to media-link mode.
- The core lightbox setting is disabled for that block to prevent duplicate lightboxes.

Gallery behavior:

- If a Gallery block has WordPress lightbox linking enabled, FooBox enables itself on the gallery.
- The gallery is switched to media-link mode.
- A FooBox group is assigned and mirrored to all child Image blocks.
- Child image lightbox flags are disabled to prevent duplicate lightboxes.

Fallback behavior:

- The editor performs the conversion while editing.
- A frontend render fallback also converts existing saved content that still contains core lightbox intent.

## Features Added In This Branch

- Native FooBox block inspector panel for Button, Image, Gallery, and Group blocks.
- Button block support for image, HTML content, iframe, video, and auto-detected lightbox targets.
- Button block media-library picker for filling the Lightbox URL or target field.
- Image block support for media linking, captions, per-item style/theme/effect, grouping, max dimensions, and large-image panning.
- Gallery block support with parent-level controls mirrored to child Image blocks.
- Group block support for hidden inline HTML content.
- Generated HTML ids for hidden content Groups.
- Frontend hiding for hidden content Groups.
- Visual editor outlines for FooBox-enabled blocks and hidden-content Groups.
- Editor-enqueued FooBox frontend assets so the block editor can initialize and preview FooBox behavior.
- `data-foobox-group` grouping support in the FooBox client runtime.
- WordPress Lightbox compatibility setting for Image and Gallery blocks.
- Frontend render fallback for existing core Image/Gallery lightbox content.
- Settings entries for Default Image Link, Auto Link Existing Images, and WordPress Lightbox compatibility.
- Documentation updates for HTML usage, Gutenberg architecture, and this block-editor usage guide.

## Troubleshooting

If an image does not open in FooBox:

- Select the Image block and confirm FooBox is enabled.
- Confirm the image links to the media file.
- Use the "Link image to media file" button if it appears.
- Confirm FooBox assets are not excluded for the post.

If a gallery opens as separate items:

- Select the Gallery block and set a Gallery group.
- Confirm all child images are linked to media files.
- Avoid relying on the global REL Grouping setting for block-editor galleries.

If hidden content does not open:

- Confirm the Group has "Use as hidden FooBox content" enabled.
- Confirm the Group has a unique HTML id.
- Confirm the Button target includes the leading `#`.
- Confirm the Button Content type is "HTML content".

If WordPress's core lightbox opens instead of FooBox:

- Enable the "WordPress Lightbox" compatibility setting.
- Reopen the post in the editor so the block attributes can sync.
- Save the post again.
- Check that another theme or plugin is not forcing its own lightbox.