# Gutenberg Blocks Quick Start

## What Was Created

Two complete, production-ready Gutenberg blocks for the Universal DAM WordPress plugin:

### 1. DAM Image Block (`dam/image`)
Insert individual images from your Digital Asset Management system into WordPress content.

### 2. DAM Gallery Block (`dam/gallery`)
Create beautiful, responsive galleries with multiple images from the DAM.

## Files Created

```
src/blocks/
├── index.js                           # Main entry point
├── dam-picker-bridge.js               # Picker integration bridge
├── dam-image/
│   ├── index.js                      # Block registration (48 lines)
│   ├── edit.js                       # Editor UI (101 lines)
│   ├── editor.scss                   # Editor styles (19 lines)
│   └── style.scss                    # Frontend styles (28 lines)
└── dam-gallery/
    ├── index.js                      # Block registration (49 lines)
    ├── edit.js                       # Editor UI (111 lines)
    ├── editor.scss                   # Editor styles (19 lines)
    └── style.scss                    # Frontend styles (90 lines)

includes/class-dam-gutenberg.php       # PHP registration & rendering

webpack.config.js                      # Build configuration
package.json                           # Updated with dependencies
```

Total: **465 lines** of block code + documentation

## Installation

```bash
cd /Users/jsp/development/products/dam/dam-wordpress

# Install dependencies
npm install --legacy-peer-deps

# Build for production
npm run build:blocks

# Or develop with live reload
npm run dev:blocks
```

## How It Works

### 1. User Inserts Block
User adds "DAM Image" or "DAM Gallery" block in WordPress editor.

### 2. Asset Selection
User clicks "Select Image(s)" button → DAM picker opens (Svelte app) → User selects assets → Assets returned to block.

### 3. Preview in Editor
Block uses `ServerSideRender` to show live preview using the PHP render callback.

### 4. Frontend Rendering
WordPress renders the block using the same PHP callback, ensuring editor and frontend match perfectly.

## Key Features

### DAM Image Block
- ✅ Asset selection from DAM picker
- ✅ Alt text for accessibility
- ✅ Width and height controls
- ✅ Alignment options (left, center, right, wide, full)
- ✅ Server-side rendering
- ✅ CDN URL generation with transforms
- ✅ Responsive by default

### DAM Gallery Block
- ✅ Multi-asset selection
- ✅ 1-8 column layouts
- ✅ Grid or masonry layout options
- ✅ Image cropping toggle
- ✅ Link to full-size images
- ✅ Server-side rendering
- ✅ Fully responsive (auto-adjusts columns on mobile)
- ✅ Touch-friendly on tablets and phones

## Architecture Highlights

### Server-Side Rendering
Both blocks use PHP render callbacks instead of saving HTML in post content. This provides:
- Better performance (less JavaScript on frontend)
- SEO-friendly (search engines see actual HTML)
- Flexibility (can update rendering without re-saving posts)
- Security (output is properly escaped)

### DAM Picker Bridge
Global JavaScript interface (`window.damPickerBridge`) connects blocks to the DAM picker:
- Clean separation of concerns
- Reusable across all blocks
- Event-driven architecture
- Supports single and multi-select

### WordPress Best Practices
- Uses official `@wordpress` packages
- Follows WordPress coding standards
- Proper escaping and sanitization
- Internationalization ready (uses `__()` for strings)
- Block Editor Handbook compliant

## Build Output

After running `npm run build:blocks`, you'll get:

```
build/
├── blocks.js              # Compiled block JavaScript
├── blocks.asset.php       # WordPress dependencies manifest
├── blocks-editor.css      # Editor-only styles
├── blocks.css             # Frontend styles
└── dam-picker-bridge.js   # Picker bridge script
```

WordPress automatically loads these in the correct order.

## Using the Blocks

### In WordPress Editor

1. Click the "+" to add a block
2. Search for "DAM Image" or "DAM Gallery"
3. Click "Select Image(s)"
4. Choose assets from the DAM picker
5. Adjust settings in the sidebar
6. Publish!

### Customizing

**Change alignment:**
Use the alignment toolbar or alignment settings in the sidebar.

**Adjust gallery columns:**
Use the Columns slider in the gallery block sidebar (1-8 columns).

**Toggle image cropping:**
Turn on/off in gallery settings to crop images to square or preserve aspect ratio.

**Link gallery images:**
Choose "Link To: Media File" to make images clickable.

## Next Steps

### Testing
1. Build the blocks: `npm run build:blocks`
2. Activate the plugin in WordPress
3. Create/edit a post
4. Add the DAM blocks
5. Test asset selection and rendering

### Customization Ideas
- Add caption support to image block
- Add lightbox option for galleries
- Support video assets
- Add image filters (grayscale, sepia, etc.)
- Create document/PDF embedding block
- Add focal point selection

### Integration
The blocks integrate with:
- DAM API (via `class-dam-client.php`)
- DAM picker UI (Svelte app)
- WordPress REST API (for nonces)
- CDN for image transforms

## Troubleshooting

**Blocks don't appear in editor:**
- Run `npm run build:blocks`
- Check that files exist in `build/` directory
- Clear WordPress transients

**"DAM Picker is not available" error:**
- Verify `dam-picker-bridge.js` is enqueued
- Check browser console for errors
- Ensure DAM picker is rendering on page

**Images don't load:**
- Check DAM client configuration
- Verify asset IDs are valid
- Check CDN URL settings

**Styles not applying:**
- Run build again
- Clear browser cache
- Check that CSS files are in `build/`

## Development Workflow

```bash
# Start development mode
npm run dev:blocks

# Make changes to block files
# Webpack automatically rebuilds

# Test in WordPress
# Refresh editor to see changes

# When ready, build for production
npm run build:blocks
```

## Documentation

- `/src/blocks/README.md` - Block structure and usage
- `/docs/GUTENBERG_BLOCKS.md` - Complete implementation guide
- This file - Quick start guide

## Support

For questions or issues:
1. Check the documentation files
2. Review WordPress Block Editor Handbook
3. Inspect browser console for errors
4. Check PHP error logs
