/**
* Proto-Blocks Basics Knowledge Module
* Comprehensive introduction and getting started guide
*/
export function getBasicsKnowledge() {
return `# Proto-Blocks: Complete Getting Started Guide
## What is Proto-Blocks?
Proto-Blocks is a next-generation WordPress plugin that enables developers to create Gutenberg blocks using **PHP/HTML templates** instead of React. It's designed for WordPress developers who want to leverage their existing PHP and theme development skills while creating modern, fully-featured Gutenberg blocks.
### Key Benefits
1. **PHP-First Development**: Write blocks using familiar PHP templates
2. **Single Source of Truth**: Everything defined in \`block.json\`
3. **Full WordPress Integration**: Supports all WordPress block features
4. **Optional Tailwind CSS**: Built-in Tailwind support for rapid styling
5. **WordPress Interactivity API**: Full support for reactive frontend features
6. **Template Caching**: Optimized performance with intelligent caching
7. **Extensible Architecture**: Register custom field types and controls
---
## Requirements
- **WordPress**: 6.3 or higher
- **PHP**: 8.0 or higher
- **Node.js**: 18+ (for development with Tailwind)
---
## Installation
### Via WordPress Admin
1. Download the Proto-Blocks plugin zip
2. Go to Plugins → Add New → Upload Plugin
3. Upload the zip file and click "Install Now"
4. Activate the plugin
### Via Composer
\`\`\`bash
composer require proto-blocks/proto-blocks
\`\`\`
### Via WP-CLI
\`\`\`bash
wp plugin install proto-blocks --activate
\`\`\`
---
## Core Concepts
### 1. Block Structure
Every Proto-Blocks block requires these files:
\`\`\`
your-theme/proto-blocks/my-block/
├── block.json ← Required: Block configuration (single source of truth)
├── template.php ← Required: PHP template for rendering
├── style.css ← Optional: Block styles
├── view.js ← Optional: Frontend JavaScript
└── preview.png ← Optional: Block inserter preview image
\`\`\`
### 2. Block Discovery
Proto-Blocks automatically discovers blocks in these locations:
1. **Active Theme**: \`/your-theme/proto-blocks/\`
2. **Child Theme**: \`/your-child-theme/proto-blocks/\`
3. **Plugin Examples**: \`/plugins/proto-blocks/examples/\`
4. **Custom Paths**: Via \`proto_blocks_paths\` filter
### 3. The block.json File
The \`block.json\` file is the single source of truth for your block. It defines:
- Block metadata (name, title, description, icon)
- WordPress supports (colors, spacing, alignment)
- **Proto-Blocks fields** (editable content regions)
- **Proto-Blocks controls** (inspector panel settings)
\`\`\`json
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "proto-blocks/example",
"title": "Example Block",
"category": "proto-blocks",
"icon": "admin-post",
"description": "An example Proto-Blocks block",
"supports": {
"html": false,
"anchor": true,
"customClassName": true
},
"protoBlocks": {
"version": "1.0",
"template": "template.php",
"useTailwind": false,
"fields": {
"title": {
"type": "text",
"tagName": "h2"
}
},
"controls": {
"showTitle": {
"type": "toggle",
"label": "Show Title",
"default": true
}
}
}
}
\`\`\`
### 4. Template Variables
Your PHP template receives these variables:
| Variable | Type | Description |
|----------|------|-------------|
| \`$attributes\` | array | All field and control values (camelCase keys) |
| \`$content\` | string | Inner blocks HTML content (if using inner blocks) |
| \`$block\` | WP_Block\\|null | Block instance (null during editor preview) |
### 5. Data Binding Attributes
Proto-Blocks uses special \`data-proto-*\` attributes to make elements editable:
| Attribute | Purpose | Example |
|-----------|---------|---------|
| \`data-proto-field="name"\` | Binds element to a field | \`<h2 data-proto-field="title">\` |
| \`data-proto-repeater="name"\` | Container for repeater items | \`<ul data-proto-repeater="items">\` |
| \`data-proto-repeater-item\` | Individual repeater item | \`<li data-proto-repeater-item>\` |
| \`data-proto-inner-blocks\` | Inner blocks container | \`<div data-proto-inner-blocks>\` |
---
## Your First Block
### Step 1: Create the Directory
\`\`\`bash
mkdir -p your-theme/proto-blocks/greeting
\`\`\`
### Step 2: Create block.json
\`\`\`json
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "proto-blocks/greeting",
"title": "Greeting Block",
"category": "proto-blocks",
"icon": "format-quote",
"description": "A simple greeting block",
"supports": {
"html": false,
"anchor": true,
"customClassName": true,
"color": {
"background": true,
"text": true
}
},
"protoBlocks": {
"version": "1.0",
"template": "template.php",
"fields": {
"name": {
"type": "text",
"tagName": "span"
},
"message": {
"type": "wysiwyg"
}
},
"controls": {
"greeting": {
"type": "text",
"label": "Greeting Text",
"default": "Hello"
}
}
}
}
\`\`\`
### Step 3: Create template.php
\`\`\`php
<?php
/**
* Greeting Block Template
*
* @var array $attributes Block attributes
* @var string $content Inner blocks content
* @var WP_Block $block Block instance
*/
// Get values with defaults
$name = $attributes['name'] ?? 'World';
$message = $attributes['message'] ?? '';
$greeting = $attributes['greeting'] ?? 'Hello';
// Get block wrapper attributes (includes WordPress supports)
$wrapper_attributes = get_block_wrapper_attributes([
'class' => 'greeting-block',
]);
?>
<div <?php echo $wrapper_attributes; ?>>
<h2 class="greeting-block__heading">
<?php echo esc_html($greeting); ?>,
<span data-proto-field="name"><?php echo esc_html($name); ?></span>!
</h2>
<?php if ($message) : ?>
<div class="greeting-block__message" data-proto-field="message">
<?php echo wp_kses_post($message); ?>
</div>
<?php endif; ?>
</div>
\`\`\`
### Step 4: Create style.css (Optional)
\`\`\`css
.greeting-block {
padding: 2rem;
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
border-radius: 8px;
color: white;
}
.greeting-block__heading {
margin: 0 0 1rem;
font-size: 2rem;
font-weight: 700;
}
.greeting-block__message {
font-size: 1.125rem;
line-height: 1.6;
opacity: 0.9;
}
\`\`\`
### Step 5: Use Your Block
1. Open the WordPress block editor
2. Click the "+" inserter
3. Search for "Greeting Block"
4. Add it to your page
5. Click on the name to edit it inline
6. Use the sidebar controls to change the greeting text
---
## Field Types Overview
| Type | Purpose | Returns |
|------|---------|---------|
| \`text\` | Single-line plain text | \`string\` |
| \`wysiwyg\` | Rich text with formatting | \`string\` (HTML) |
| \`image\` | Media library image picker | \`object { id, url, alt, size }\` |
| \`link\` | URL with text and options | \`object { url, text, target, rel }\` |
| \`repeater\` | Repeatable group of fields | \`array\` of objects |
| \`innerblocks\` | Nested WordPress blocks | \`string\` (HTML) |
---
## Control Types Overview
| Type | Returns | Use Case |
|------|---------|----------|
| \`text\` | string | Short text inputs |
| \`textarea\` | string | Multi-line text |
| \`select\` | string | Dropdown selection |
| \`toggle\` | boolean | On/off switches |
| \`checkbox\` | boolean | Yes/no options |
| \`range\` | number | Numeric sliders |
| \`number\` | number | Precise numbers |
| \`color\` | string | Color picker (any color) |
| \`color-palette\` | string | WordPress theme colors |
| \`radio\` | string | Radio button groups |
| \`image\` | object | Image selection |
---
## WordPress Block Supports
Proto-Blocks fully supports WordPress block features:
\`\`\`json
{
"supports": {
"html": false,
"anchor": true,
"customClassName": true,
"align": ["wide", "full"],
"color": {
"background": true,
"text": true,
"gradients": true
},
"spacing": {
"padding": true,
"margin": true,
"blockGap": true
},
"typography": {
"fontSize": true,
"lineHeight": true
}
}
}
\`\`\`
These WordPress features are automatically applied via \`get_block_wrapper_attributes()\`.
---
## Development Workflow
### 1. Create Block Structure
\`\`\`bash
# Using WP-CLI (if available)
wp proto-blocks create my-block
# Or manually create the directory and files
\`\`\`
### 2. Define in block.json
- Set up metadata
- Define fields for editable content
- Add controls for settings
- Configure WordPress supports
### 3. Create PHP Template
- Use \`get_block_wrapper_attributes()\` for root element
- Add \`data-proto-field\` attributes to editable elements
- Always escape output appropriately
- Provide sensible defaults
### 4. Add Styling
- Create \`style.css\` for vanilla CSS
- Or enable Tailwind with \`useTailwind: true\`
### 5. Test in Editor
- Add block to a post/page
- Test all fields and controls
- Verify frontend rendering
---
## Next Steps
1. **Learn Field Types**: Use \`proto_blocks_field_types\` tool for detailed field documentation
2. **Learn Control Types**: Use \`proto_blocks_control_types\` tool for control documentation
3. **See Examples**: Use \`proto_blocks_examples\` tool for complete working examples
4. **Template Patterns**: Use \`proto_blocks_templates\` tool for template best practices
5. **Add Styling**: Use \`proto_blocks_styling\` tool for styling approaches
6. **Add Interactivity**: Use \`proto_blocks_interactivity\` tool for frontend interactions
---
## Quick Tips
1. **Always use \`get_block_wrapper_attributes()\`** - This applies WordPress block supports
2. **Escape all output** - Use \`esc_html()\`, \`esc_attr()\`, \`wp_kses_post()\`
3. **Provide defaults** - Use null coalescing: \`$title ?? 'Default'\`
4. **Keep elements visible** - Even empty elements need to be clickable in editor
5. **Use camelCase** - Attribute keys in PHP are camelCase (matching block.json)
6. **Check for preview** - Use \`!isset($block) || $block === null\` to detect editor preview
`;
}
