/**
* Proto-Blocks Controls Knowledge Module
* Complete documentation for all control types
*/
export function getControlsKnowledge() {
return `# Proto-Blocks Control Types: Complete Reference
Controls appear in the WordPress block inspector panel (sidebar) and allow users to configure block settings without editing content directly.
---
## Controls vs Fields
| Aspect | Fields | Controls |
|--------|--------|----------|
| Location | In the block content | In the sidebar |
| Purpose | Editable content | Settings/options |
| Examples | Titles, images, text | Layout, colors, toggles |
| Editing | Direct manipulation | Form inputs |
---
## Control Types Overview
| Type | Returns | UI Element |
|------|---------|------------|
| \`text\` | string | Text input |
| \`textarea\` | string | Multi-line textarea |
| \`select\` | string | Dropdown menu |
| \`toggle\` | boolean | On/off switch |
| \`checkbox\` | boolean | Checkbox |
| \`range\` | number | Slider |
| \`number\` | number | Number input |
| \`color\` | string | Color picker (any color) |
| \`color-palette\` | string | WordPress palette picker |
| \`radio\` | string | Radio button group |
| \`image\` | object | Image picker |
---
## Text Control
Single-line text input for short string values.
### Configuration
\`\`\`json
{
"controls": {
"buttonText": {
"type": "text",
"label": "Button Text",
"default": "Learn More",
"help": "Text displayed on the button"
}
}
}
\`\`\`
### Options
| Option | Type | Required | Description |
|--------|------|----------|-------------|
| \`type\` | string | Yes | Must be \`"text"\` |
| \`label\` | string | Yes | Display label |
| \`default\` | string | No | Default value |
| \`help\` | string | No | Help text below input |
### Template Usage
\`\`\`php
<?php
$button_text = $attributes['buttonText'] ?? 'Learn More';
?>
<button class="cta-button">
<?php echo esc_html($button_text); ?>
</button>
\`\`\`
---
## Textarea Control
Multi-line text input for longer content.
### Configuration
\`\`\`json
{
"controls": {
"customCss": {
"type": "textarea",
"label": "Custom CSS",
"default": "",
"help": "Add custom CSS for this block"
}
}
}
\`\`\`
### Template Usage
\`\`\`php
<?php
$custom_css = $attributes['customCss'] ?? '';
if ($custom_css) {
echo '<style>' . wp_strip_all_tags($custom_css) . '</style>';
}
?>
\`\`\`
---
## Select Control
Dropdown menu for selecting from predefined options.
### Configuration
\`\`\`json
{
"controls": {
"layout": {
"type": "select",
"label": "Layout",
"default": "vertical",
"options": [
{ "key": "vertical", "label": "Vertical" },
{ "key": "horizontal", "label": "Horizontal" },
{ "key": "grid", "label": "Grid" }
]
}
}
}
\`\`\`
### Options
| Option | Type | Required | Description |
|--------|------|----------|-------------|
| \`type\` | string | Yes | Must be \`"select"\` |
| \`label\` | string | Yes | Display label |
| \`default\` | string | No | Default option key |
| \`options\` | array | Yes | Array of {key, label} objects |
| \`help\` | string | No | Help text |
### Template Usage
\`\`\`php
<?php
$layout = $attributes['layout'] ?? 'vertical';
$layout_classes = [
'vertical' => 'flex flex-col',
'horizontal' => 'flex flex-row',
'grid' => 'grid grid-cols-3',
];
$class = $layout_classes[$layout] ?? $layout_classes['vertical'];
?>
<div class="<?php echo esc_attr($class); ?>">
<!-- Content -->
</div>
\`\`\`
---
## Toggle Control
On/off switch for boolean values.
### Configuration
\`\`\`json
{
"controls": {
"showImage": {
"type": "toggle",
"label": "Show Image",
"default": true,
"help": "Display the featured image"
},
"enableAnimation": {
"type": "toggle",
"label": "Enable Animation",
"default": false
}
}
}
\`\`\`
### Template Usage
\`\`\`php
<?php
$show_image = $attributes['showImage'] ?? true;
$image = $attributes['image'] ?? null;
?>
<?php if ($show_image && $image) : ?>
<img src="<?php echo esc_url($image['url']); ?>" alt="" />
<?php endif; ?>
\`\`\`
---
## Checkbox Control
Checkbox for boolean values (alternative to toggle).
### Configuration
\`\`\`json
{
"controls": {
"openInNewTab": {
"type": "checkbox",
"label": "Open in new tab",
"default": false
}
}
}
\`\`\`
### Template Usage
\`\`\`php
<?php
$new_tab = $attributes['openInNewTab'] ?? false;
?>
<a
href="<?php echo esc_url($link); ?>"
<?php echo $new_tab ? 'target="_blank" rel="noopener"' : ''; ?>
>
Link Text
</a>
\`\`\`
---
## Range Control
Slider for numeric values within a range.
### Configuration
\`\`\`json
{
"controls": {
"columns": {
"type": "range",
"label": "Columns",
"min": 1,
"max": 6,
"step": 1,
"default": 3
},
"opacity": {
"type": "range",
"label": "Overlay Opacity",
"min": 0,
"max": 100,
"step": 5,
"default": 50,
"help": "Opacity percentage for the overlay"
}
}
}
\`\`\`
### Options
| Option | Type | Required | Description |
|--------|------|----------|-------------|
| \`type\` | string | Yes | Must be \`"range"\` |
| \`label\` | string | Yes | Display label |
| \`min\` | number | Yes | Minimum value |
| \`max\` | number | Yes | Maximum value |
| \`step\` | number | No | Step increment (default: 1) |
| \`default\` | number | No | Default value |
### Template Usage
\`\`\`php
<?php
$columns = $attributes['columns'] ?? 3;
$opacity = ($attributes['opacity'] ?? 50) / 100;
?>
<div class="grid grid-cols-<?php echo esc_attr($columns); ?>">
<!-- Items -->
</div>
<div class="overlay" style="opacity: <?php echo esc_attr($opacity); ?>;">
</div>
\`\`\`
---
## Number Control
Precise number input with optional min/max.
### Configuration
\`\`\`json
{
"controls": {
"minHeight": {
"type": "number",
"label": "Minimum Height (px)",
"min": 100,
"max": 1000,
"default": 400
},
"itemsToShow": {
"type": "number",
"label": "Items to Show",
"min": 1,
"max": 20,
"default": 5
}
}
}
\`\`\`
### Template Usage
\`\`\`php
<?php
$min_height = $attributes['minHeight'] ?? 400;
?>
<section style="min-height: <?php echo esc_attr($min_height); ?>px;">
<!-- Content -->
</section>
\`\`\`
---
## Color Control
Full color picker allowing any color selection.
### Configuration
\`\`\`json
{
"controls": {
"backgroundColor": {
"type": "color",
"label": "Background Color",
"default": "#ffffff"
},
"textColor": {
"type": "color",
"label": "Text Color",
"default": "#000000"
}
}
}
\`\`\`
### Template Usage
\`\`\`php
<?php
$bg_color = $attributes['backgroundColor'] ?? '#ffffff';
$text_color = $attributes['textColor'] ?? '#000000';
$style = sprintf(
'background-color: %s; color: %s;',
esc_attr($bg_color),
esc_attr($text_color)
);
?>
<div style="<?php echo $style; ?>">
Content
</div>
\`\`\`
### Using with RGBA
\`\`\`php
<?php
// Proto-Blocks provides a helper function
$color = $attributes['overlayColor'] ?? '#000000';
$opacity = ($attributes['overlayOpacity'] ?? 50) / 100;
// If helper available:
// $rgba = proto_blocks_hex_to_rgba($color, $opacity);
// Manual conversion:
$hex = ltrim($color, '#');
$r = hexdec(substr($hex, 0, 2));
$g = hexdec(substr($hex, 2, 2));
$b = hexdec(substr($hex, 4, 2));
$rgba = "rgba($r, $g, $b, $opacity)";
?>
<div style="background-color: <?php echo esc_attr($rgba); ?>;">
</div>
\`\`\`
---
## Color Palette Control
Color picker using WordPress theme palette colors.
### Configuration
\`\`\`json
{
"controls": {
"accentColor": {
"type": "color-palette",
"label": "Accent Color",
"default": ""
}
}
}
\`\`\`
### Template Usage
\`\`\`php
<?php
$accent = $attributes['accentColor'] ?? '';
$style = $accent ? "color: $accent;" : '';
?>
<span style="<?php echo esc_attr($style); ?>">
Accented text
</span>
\`\`\`
### Difference from Color Control
| Color | Color Palette |
|-------|---------------|
| Any hex color | Theme-defined colors |
| Custom picker | Preset swatches |
| Full flexibility | Brand consistency |
---
## Radio Control
Radio button group for mutually exclusive options.
### Configuration
\`\`\`json
{
"controls": {
"alignment": {
"type": "radio",
"label": "Content Alignment",
"default": "left",
"options": [
{ "key": "left", "label": "Left" },
{ "key": "center", "label": "Center" },
{ "key": "right", "label": "Right" }
]
}
}
}
\`\`\`
### Template Usage
\`\`\`php
<?php
$alignment = $attributes['alignment'] ?? 'left';
$align_classes = [
'left' => 'text-left',
'center' => 'text-center',
'right' => 'text-right',
];
?>
<div class="<?php echo esc_attr($align_classes[$alignment] ?? 'text-left'); ?>">
Content
</div>
\`\`\`
---
## Image Control
Image picker for sidebar-based image selection.
### Configuration
\`\`\`json
{
"controls": {
"icon": {
"type": "image",
"label": "Block Icon",
"sizes": ["thumbnail", "medium"]
}
}
}
\`\`\`
### Return Value
\`\`\`javascript
{
"id": 123,
"url": "https://...",
"alt": "Alt text",
"size": "thumbnail"
}
\`\`\`
### Template Usage
\`\`\`php
<?php
$icon = $attributes['icon'] ?? null;
?>
<?php if ($icon && !empty($icon['url'])) : ?>
<img
src="<?php echo esc_url($icon['url']); ?>"
alt="<?php echo esc_attr($icon['alt'] ?? ''); ?>"
class="block-icon"
/>
<?php endif; ?>
\`\`\`
### Image Control vs Image Field
| Image Control | Image Field |
|---------------|-------------|
| In sidebar | In block content |
| Settings context | Content context |
| Icons, backgrounds | Featured images |
| No direct editing | Click to edit |
---
## Conditional Controls
Show or hide controls based on other control values.
### Configuration
\`\`\`json
{
"controls": {
"hasOverlay": {
"type": "toggle",
"label": "Enable Overlay",
"default": false
},
"overlayColor": {
"type": "color",
"label": "Overlay Color",
"default": "#000000",
"conditions": {
"visible": {
"hasOverlay": [true]
}
}
},
"overlayOpacity": {
"type": "range",
"label": "Overlay Opacity",
"min": 0,
"max": 100,
"default": 50,
"conditions": {
"visible": {
"hasOverlay": [true]
}
}
}
}
}
\`\`\`
### Condition Syntax
\`\`\`json
{
"conditions": {
"visible": {
"controlName": [allowedValue1, allowedValue2]
}
}
}
\`\`\`
### Multiple Conditions
\`\`\`json
{
"controls": {
"layout": {
"type": "select",
"options": [
{ "key": "simple", "label": "Simple" },
{ "key": "advanced", "label": "Advanced" }
]
},
"showSidebar": {
"type": "toggle",
"default": true
},
"sidebarWidth": {
"type": "range",
"min": 200,
"max": 400,
"conditions": {
"visible": {
"layout": ["advanced"],
"showSidebar": [true]
}
}
}
}
}
\`\`\`
---
## Control Groups
Organize controls with panels (automatically handled by WordPress):
\`\`\`json
{
"controls": {
"layout": {
"type": "select",
"label": "Layout",
"options": [...]
},
"columns": {
"type": "range",
"label": "Columns"
},
"backgroundColor": {
"type": "color",
"label": "Background"
},
"textColor": {
"type": "color",
"label": "Text"
}
}
}
\`\`\`
Controls appear in the order defined.
---
## Complete Example
\`\`\`json
{
"protoBlocks": {
"controls": {
"layout": {
"type": "select",
"label": "Card Layout",
"default": "vertical",
"options": [
{ "key": "vertical", "label": "Vertical" },
{ "key": "horizontal", "label": "Horizontal" },
{ "key": "overlay", "label": "Overlay" }
]
},
"imagePosition": {
"type": "radio",
"label": "Image Position",
"default": "left",
"options": [
{ "key": "left", "label": "Left" },
{ "key": "right", "label": "Right" }
],
"conditions": {
"visible": {
"layout": ["horizontal"]
}
}
},
"showMeta": {
"type": "toggle",
"label": "Show Meta Info",
"default": true
},
"columns": {
"type": "range",
"label": "Grid Columns",
"min": 1,
"max": 4,
"default": 3,
"conditions": {
"visible": {
"layout": ["vertical"]
}
}
},
"overlayOpacity": {
"type": "range",
"label": "Overlay Opacity",
"min": 0,
"max": 100,
"default": 60,
"conditions": {
"visible": {
"layout": ["overlay"]
}
}
},
"overlayColor": {
"type": "color",
"label": "Overlay Color",
"default": "#000000",
"conditions": {
"visible": {
"layout": ["overlay"]
}
}
}
}
}
}
\`\`\`
---
## Best Practices
1. **Meaningful Labels**: Use clear, descriptive labels
2. **Sensible Defaults**: Always provide default values
3. **Help Text**: Add help for non-obvious controls
4. **Logical Order**: Group related controls together
5. **Conditional Display**: Hide irrelevant controls
6. **Reasonable Limits**: Set appropriate min/max for ranges
7. **Consistent Naming**: Use camelCase for control names
`;
}
export function getControlDetails(controlType) {
const details = {
text: `# Text Control - Detailed Documentation
Single-line text input for short string values.
## Configuration
\`\`\`json
{
"controls": {
"subtitle": {
"type": "text",
"label": "Subtitle",
"default": "",
"help": "Optional subtitle below the main heading"
}
}
}
\`\`\`
## All Options
| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| \`type\` | string | Yes | — | Must be \`"text"\` |
| \`label\` | string | Yes | — | Label shown above input |
| \`default\` | string | No | \`""\` | Default value |
| \`help\` | string | No | — | Help text below input |
## Template Pattern
\`\`\`php
<?php
$subtitle = $attributes['subtitle'] ?? '';
?>
<?php if ($subtitle) : ?>
<p class="subtitle"><?php echo esc_html($subtitle); ?></p>
<?php endif; ?>
\`\`\`
## Use Cases
- Button labels
- Alternative text
- CSS class names
- Custom titles
- Short descriptions
`,
textarea: `# Textarea Control - Detailed Documentation
Multi-line text input for longer content.
## Configuration
\`\`\`json
{
"controls": {
"customScript": {
"type": "textarea",
"label": "Custom JavaScript",
"default": "",
"help": "Add custom JavaScript for this block"
}
}
}
\`\`\`
## Template Pattern
\`\`\`php
<?php
$custom_script = $attributes['customScript'] ?? '';
?>
<?php if ($custom_script) : ?>
<script>
<?php echo wp_kses($custom_script, []); ?>
</script>
<?php endif; ?>
\`\`\`
## Use Cases
- Custom CSS
- Custom JavaScript
- Long descriptions
- Code snippets
- Multi-line configuration
`,
select: `# Select Control - Detailed Documentation
Dropdown menu for selecting from predefined options.
## Configuration
\`\`\`json
{
"controls": {
"size": {
"type": "select",
"label": "Size",
"default": "medium",
"options": [
{ "key": "small", "label": "Small" },
{ "key": "medium", "label": "Medium" },
{ "key": "large", "label": "Large" },
{ "key": "full", "label": "Full Width" }
],
"help": "Select the component size"
}
}
}
\`\`\`
## Template Pattern
\`\`\`php
<?php
$size = $attributes['size'] ?? 'medium';
$size_classes = [
'small' => 'max-w-sm',
'medium' => 'max-w-md',
'large' => 'max-w-lg',
'full' => 'w-full',
];
$class = $size_classes[$size] ?? $size_classes['medium'];
?>
<div class="<?php echo esc_attr($class); ?>">
Content
</div>
\`\`\`
## Use Cases
- Layout variations
- Size options
- Style presets
- Animation types
- Any enumerated choice
`,
toggle: `# Toggle Control - Detailed Documentation
On/off switch for boolean values.
## Configuration
\`\`\`json
{
"controls": {
"showAuthor": {
"type": "toggle",
"label": "Show Author",
"default": true,
"help": "Display author information"
}
}
}
\`\`\`
## Template Pattern
\`\`\`php
<?php
$show_author = $attributes['showAuthor'] ?? true;
?>
<?php if ($show_author) : ?>
<div class="author-info">
<?php echo get_the_author(); ?>
</div>
<?php endif; ?>
\`\`\`
## Toggle vs Checkbox
| Toggle | Checkbox |
|--------|----------|
| Visual switch | Standard checkbox |
| On/Off states | Checked/unchecked |
| More prominent | More compact |
| Modern UI | Traditional UI |
Both return boolean values.
`,
checkbox: `# Checkbox Control - Detailed Documentation
Standard checkbox for boolean values.
## Configuration
\`\`\`json
{
"controls": {
"isSticky": {
"type": "checkbox",
"label": "Make sticky",
"default": false
}
}
}
\`\`\`
## Template Pattern
\`\`\`php
<?php
$is_sticky = $attributes['isSticky'] ?? false;
$sticky_class = $is_sticky ? 'position-sticky top-0' : '';
?>
<div class="<?php echo esc_attr($sticky_class); ?>">
Content
</div>
\`\`\`
`,
range: `# Range Control - Detailed Documentation
Slider for numeric values within a defined range.
## Configuration
\`\`\`json
{
"controls": {
"spacing": {
"type": "range",
"label": "Spacing",
"min": 0,
"max": 100,
"step": 5,
"default": 20,
"help": "Spacing in pixels"
}
}
}
\`\`\`
## All Options
| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| \`type\` | string | Yes | — | Must be \`"range"\` |
| \`label\` | string | Yes | — | Display label |
| \`min\` | number | Yes | — | Minimum value |
| \`max\` | number | Yes | — | Maximum value |
| \`step\` | number | No | \`1\` | Step increment |
| \`default\` | number | No | \`min\` | Default value |
| \`help\` | string | No | — | Help text |
## Template Pattern
\`\`\`php
<?php
$spacing = $attributes['spacing'] ?? 20;
?>
<div style="padding: <?php echo esc_attr($spacing); ?>px;">
Content
</div>
\`\`\`
## Use Cases
- Opacity values (0-100)
- Column counts (1-6)
- Spacing/padding
- Font sizes
- Animation duration
`,
number: `# Number Control - Detailed Documentation
Precise number input with optional constraints.
## Configuration
\`\`\`json
{
"controls": {
"maxItems": {
"type": "number",
"label": "Maximum Items",
"min": 1,
"max": 50,
"default": 10
}
}
}
\`\`\`
## Range vs Number
| Range | Number |
|-------|--------|
| Slider UI | Input field |
| Approximate | Precise |
| Visual feedback | Exact entry |
| Better for visual properties | Better for counts/limits |
## Template Pattern
\`\`\`php
<?php
$max_items = $attributes['maxItems'] ?? 10;
$items = array_slice($all_items, 0, $max_items);
?>
\`\`\`
`,
color: `# Color Control - Detailed Documentation
Full color picker allowing any color selection.
## Configuration
\`\`\`json
{
"controls": {
"brandColor": {
"type": "color",
"label": "Brand Color",
"default": "#0073aa"
}
}
}
\`\`\`
## Template Patterns
### Direct Usage
\`\`\`php
<?php
$brand_color = $attributes['brandColor'] ?? '#0073aa';
?>
<div style="background-color: <?php echo esc_attr($brand_color); ?>;">
Content
</div>
\`\`\`
### With Opacity
\`\`\`php
<?php
$color = $attributes['overlayColor'] ?? '#000000';
$opacity = ($attributes['overlayOpacity'] ?? 50) / 100;
// Convert hex to rgba
$hex = ltrim($color, '#');
$r = hexdec(substr($hex, 0, 2));
$g = hexdec(substr($hex, 2, 2));
$b = hexdec(substr($hex, 4, 2));
$rgba = "rgba($r, $g, $b, $opacity)";
?>
<div style="background-color: <?php echo esc_attr($rgba); ?>;">
</div>
\`\`\`
### CSS Variable
\`\`\`php
<?php
$accent = $attributes['accentColor'] ?? '#0073aa';
?>
<div style="--accent-color: <?php echo esc_attr($accent); ?>;">
<span style="color: var(--accent-color);">Accent text</span>
</div>
\`\`\`
`,
'color-palette': `# Color Palette Control - Detailed Documentation
Color picker restricted to WordPress theme palette.
## Configuration
\`\`\`json
{
"controls": {
"highlightColor": {
"type": "color-palette",
"label": "Highlight Color"
}
}
}
\`\`\`
## Benefits
1. **Brand Consistency**: Only theme-approved colors
2. **Theme Integration**: Works with theme.json colors
3. **User Friendly**: Limited, curated choices
4. **Accessibility**: Theme can ensure contrast
## Template Pattern
\`\`\`php
<?php
$highlight = $attributes['highlightColor'] ?? '';
$style = $highlight ? "--highlight: $highlight;" : '';
?>
<div style="<?php echo esc_attr($style); ?>">
Content
</div>
\`\`\`
`,
radio: `# Radio Control - Detailed Documentation
Radio button group for mutually exclusive options.
## Configuration
\`\`\`json
{
"controls": {
"position": {
"type": "radio",
"label": "Position",
"default": "left",
"options": [
{ "key": "left", "label": "Left" },
{ "key": "center", "label": "Center" },
{ "key": "right", "label": "Right" }
]
}
}
}
\`\`\`
## Select vs Radio
| Select | Radio |
|--------|-------|
| Dropdown menu | Visible buttons |
| Compact | Takes more space |
| Many options | Few options (2-4) |
| Hidden until clicked | Always visible |
## Template Pattern
\`\`\`php
<?php
$position = $attributes['position'] ?? 'left';
$position_styles = [
'left' => 'justify-content: flex-start;',
'center' => 'justify-content: center;',
'right' => 'justify-content: flex-end;',
];
?>
<div style="display: flex; <?php echo esc_attr($position_styles[$position]); ?>">
Content
</div>
\`\`\`
`,
image: `# Image Control - Detailed Documentation
Image picker in the sidebar for configuration images.
## Configuration
\`\`\`json
{
"controls": {
"backgroundImage": {
"type": "image",
"label": "Background Image",
"sizes": ["medium", "large", "full"]
}
}
}
\`\`\`
## Return Value
\`\`\`javascript
{
"id": 123,
"url": "https://site.com/wp-content/uploads/image.jpg",
"alt": "Image description",
"size": "large"
}
\`\`\`
## Template Pattern
\`\`\`php
<?php
$bg = $attributes['backgroundImage'] ?? null;
$bg_style = '';
if ($bg && !empty($bg['url'])) {
$bg_style = "background-image: url('" . esc_url($bg['url']) . "');";
}
?>
<section
class="hero"
style="<?php echo esc_attr($bg_style); ?>"
>
Content
</section>
\`\`\`
## Image Control vs Image Field
Use **Image Control** for:
- Background images
- Decorative images
- Configuration images
- Icons
Use **Image Field** for:
- Content images
- Featured images
- Images user edits in content area
`,
};
return details[controlType] || `Unknown control type: ${controlType}. Available types: text, textarea, select, toggle, checkbox, range, number, color, color-palette, radio, image`;
}
