/**
* Proto-Blocks Quick Reference Module
* Cheat sheet for common patterns
*/
export function getQuickReference() {
return `# Proto-Blocks Quick Reference Card
Essential patterns and syntax for rapid Proto-Blocks development.
---
## Block Structure
\`\`\`
my-block/
├── block.json ← Configuration
├── template.php ← PHP template
├── style.css ← Styles (optional)
└── view.js ← JS (optional)
\`\`\`
---
## Minimal block.json
\`\`\`json
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "proto-blocks/my-block",
"title": "My Block",
"category": "proto-blocks",
"icon": "admin-post",
"protoBlocks": {
"version": "1.0",
"template": "template.php",
"fields": {},
"controls": {}
}
}
\`\`\`
---
## Field Types
| Type | Config | Template |
|------|--------|----------|
| Text | \`{"type": "text", "tagName": "h2"}\` | \`<h2 data-proto-field="title">...\` |
| WYSIWYG | \`{"type": "wysiwyg"}\` | \`<div data-proto-field="content">...\` |
| Image | \`{"type": "image", "sizes": ["medium"]}\` | \`<img data-proto-field="image" ...>\` |
| Link | \`{"type": "link"}\` | \`<a data-proto-field="link" ...>\` |
| Repeater | \`{"type": "repeater", "fields": {...}}\` | See below |
| InnerBlocks | \`{"type": "innerblocks"}\` | \`<div data-proto-inner-blocks>\` |
---
## Repeater Pattern
**block.json:**
\`\`\`json
"items": {
"type": "repeater",
"fields": {
"title": {"type": "text"}
}
}
\`\`\`
**template.php:**
\`\`\`php
<ul data-proto-repeater="items">
<?php foreach ($items as $item) : ?>
<li data-proto-repeater-item>
<span data-proto-field="title"><?php echo esc_html($item['title']); ?></span>
</li>
<?php endforeach; ?>
</ul>
\`\`\`
---
## Control Types
| Type | Returns | Config Example |
|------|---------|----------------|
| text | string | \`{"type": "text", "label": "Label"}\` |
| textarea | string | \`{"type": "textarea", "label": "Label"}\` |
| select | string | \`{"type": "select", "options": [{"key": "a", "label": "A"}]}\` |
| toggle | boolean | \`{"type": "toggle", "label": "Label", "default": true}\` |
| checkbox | boolean | \`{"type": "checkbox", "label": "Label"}\` |
| range | number | \`{"type": "range", "min": 1, "max": 10, "default": 5}\` |
| number | number | \`{"type": "number", "min": 0, "max": 100}\` |
| color | string | \`{"type": "color", "default": "#000"}\` |
| color-palette | string | \`{"type": "color-palette"}\` |
| radio | string | \`{"type": "radio", "options": [...]}\` |
| image | object | \`{"type": "image", "sizes": [...]}\` |
---
## Conditional Controls
\`\`\`json
"controls": {
"layout": {"type": "select", "options": [...]},
"columns": {
"type": "range",
"conditions": {
"visible": {"layout": ["grid"]}
}
}
}
\`\`\`
---
## Template Variables
\`\`\`php
$attributes // All field/control values (camelCase)
$content // Inner blocks HTML
$block // WP_Block instance (null in preview)
\`\`\`
---
## Template Pattern
\`\`\`php
<?php
// 1. Extract with defaults
$title = $attributes['title'] ?? '';
$layout = $attributes['layout'] ?? 'default';
// 2. Build wrapper
$wrapper = get_block_wrapper_attributes([
'class' => "my-block my-block--{$layout}",
]);
?>
<!-- 3. Output with escaping -->
<div <?php echo $wrapper; ?>>
<h2 data-proto-field="title"><?php echo esc_html($title); ?></h2>
</div>
\`\`\`
---
## Escaping Functions
| Function | Use For |
|----------|---------|
| \`esc_html()\` | Plain text |
| \`esc_attr()\` | HTML attributes |
| \`esc_url()\` | URLs |
| \`wp_kses_post()\` | Rich HTML content |
---
## Data Attributes
| Attribute | Purpose |
|-----------|---------|
| \`data-proto-field="name"\` | Bind to field |
| \`data-proto-repeater="name"\` | Repeater container |
| \`data-proto-repeater-item\` | Repeater item |
| \`data-proto-inner-blocks\` | Inner blocks area |
---
## Image Handling
\`\`\`php
<?php $image = $attributes['image'] ?? null; ?>
<?php if ($image && !empty($image['url'])) : ?>
<img
src="<?php echo esc_url($image['url']); ?>"
alt="<?php echo esc_attr($image['alt'] ?? ''); ?>"
data-proto-field="image"
/>
<?php else : ?>
<div data-proto-field="image" class="placeholder">+</div>
<?php endif; ?>
\`\`\`
---
## Link Handling
\`\`\`php
<?php $link = $attributes['link'] ?? null; ?>
<a
href="<?php echo esc_url($link['url'] ?? '#'); ?>"
data-proto-field="link"
<?php echo !empty($link['target']) ? 'target="' . esc_attr($link['target']) . '"' : ''; ?>
>
<?php echo esc_html($link['text'] ?? 'Read More'); ?>
</a>
\`\`\`
---
## Common Supports
\`\`\`json
"supports": {
"html": false,
"anchor": true,
"customClassName": true,
"align": ["wide", "full"],
"color": {"background": true, "text": true},
"spacing": {"padding": true, "margin": true},
"interactivity": true
}
\`\`\`
---
## Tailwind Setup
\`\`\`json
"protoBlocks": {
"useTailwind": true
}
\`\`\`
Template:
\`\`\`php
<div class="flex gap-4 p-6 bg-white rounded-lg shadow-md">
\`\`\`
---
## Interactivity API Setup
**block.json:**
\`\`\`json
{
"supports": {"interactivity": true},
"viewScriptModule": "file:./view.js"
}
\`\`\`
**template.php:**
\`\`\`php
<div
data-wp-interactive="proto-blocks/my-block"
data-wp-context='{"isOpen": false}'
>
<button data-wp-on--click="actions.toggle">Toggle</button>
<div data-wp-bind--hidden="!context.isOpen">Content</div>
</div>
\`\`\`
**view.js:**
\`\`\`javascript
import { store, getContext } from '@wordpress/interactivity';
store('proto-blocks/my-block', {
actions: {
toggle() {
const ctx = getContext();
ctx.isOpen = !ctx.isOpen;
}
}
});
\`\`\`
---
## Preview Detection
\`\`\`php
<?php
$is_preview = !isset($block) || $block === null;
if ($is_preview && empty($items)) {
$items = [/* default items */];
}
?>
\`\`\`
---
## WP-CLI Commands
\`\`\`bash
wp proto-blocks list # List all blocks
wp proto-blocks validate # Validate configs
wp proto-blocks cache clear # Clear cache
wp proto-blocks create myblock # Create block
\`\`\`
---
## File Locations
Blocks are discovered in:
1. \`/your-theme/proto-blocks/\`
2. \`/your-child-theme/proto-blocks/\`
3. Custom paths via \`proto_blocks_paths\` filter
---
## Troubleshooting Checklist
1. ☐ block.json valid JSON?
2. ☐ template.php exists?
3. ☐ data-proto-field attributes added?
4. ☐ Escaping used correctly?
5. ☐ Defaults provided for all attributes?
6. ☐ Cache cleared?
7. ☐ WP_DEBUG enabled for errors?
`;
}
