/**
* Proto-Blocks Troubleshooting Knowledge Module
* Common issues and solutions
*/
export function getTroubleshootingKnowledge() {
return `# Proto-Blocks Troubleshooting Guide
Common issues and their solutions when working with Proto-Blocks.
---
## Quick Diagnosis
| Symptom | Likely Cause | Solution |
|---------|--------------|----------|
| Block not appearing | Invalid block.json | Validate JSON syntax |
| Fields not editable | Missing data-proto-field | Add required attributes |
| Styles not loading | Wrong file path | Check style.css location |
| JavaScript errors | Syntax/import issues | Check console errors |
| White screen in editor | PHP fatal error | Enable WP_DEBUG |
---
${getRegistrationIssues()}
${getTemplateIssues()}
${getFieldIssues()}
${getControlIssues()}
${getStylingIssues()}
${getInteractivityIssues()}
${getPerformanceIssues()}
${getEditorIssues()}
`;
}
export function getTroubleshootingByCategory(category) {
const categories = {
registration: getRegistrationIssues(),
templates: getTemplateIssues(),
fields: getFieldIssues(),
controls: getControlIssues(),
styling: getStylingIssues(),
interactivity: getInteractivityIssues(),
performance: getPerformanceIssues(),
editor: getEditorIssues(),
};
return categories[category] || `Unknown category: ${category}. Available: registration, templates, fields, controls, styling, interactivity, performance, editor`;
}
function getRegistrationIssues() {
return `## Block Registration Issues
### Block Doesn't Appear in Inserter
**Symptoms:**
- Block is not visible in the block inserter
- Block search returns no results
**Solutions:**
1. **Validate block.json syntax**
\`\`\`bash
# Check for JSON syntax errors
cat block.json | python -m json.tool
\`\`\`
2. **Check block.json required fields**
\`\`\`json
{
"name": "proto-blocks/my-block", // Required: unique name
"title": "My Block", // Required: display title
"category": "proto-blocks", // Required: valid category
"protoBlocks": { // Required: Proto-Blocks config
"version": "1.0",
"template": "template.php"
}
}
\`\`\`
3. **Verify file locations**
\`\`\`
your-theme/proto-blocks/my-block/
├── block.json ← Must exist
└── template.php ← Must match "template" in block.json
\`\`\`
4. **Check block discovery paths**
\`\`\`php
// In your theme's functions.php, verify paths
add_filter('proto_blocks_paths', function($paths) {
error_log(print_r($paths, true));
return $paths;
});
\`\`\`
5. **Clear caches**
\`\`\`bash
wp cache flush
wp transient delete --all
\`\`\`
---
### Block Name Conflict
**Symptoms:**
- Block shows wrong content
- Multiple blocks with same behavior
**Solutions:**
1. **Use unique block names**
\`\`\`json
// Good - includes namespace
"name": "proto-blocks/my-custom-card"
// Bad - too generic
"name": "card"
\`\`\`
2. **Check for duplicate blocks**
\`\`\`bash
wp proto-blocks list
\`\`\`
---
### Invalid Block JSON Schema
**Symptoms:**
- Console warnings about schema
- Block works but shows warnings
**Solutions:**
1. **Use correct schema URL**
\`\`\`json
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3
}
\`\`\`
2. **Validate against WordPress schema**
- Visit the schema URL to see all valid properties
`;
}
function getTemplateIssues() {
return `## Template Issues
### Template Not Rendering
**Symptoms:**
- Block shows empty or broken content
- PHP errors in console/logs
**Solutions:**
1. **Check template file exists**
\`\`\`
my-block/
├── block.json
└── template.php ← Verify this file exists
\`\`\`
2. **Verify template path in block.json**
\`\`\`json
"protoBlocks": {
"template": "template.php" // Relative to block folder
}
\`\`\`
3. **Check for PHP syntax errors**
\`\`\`bash
php -l template.php
\`\`\`
4. **Enable WordPress debug mode**
\`\`\`php
// wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
\`\`\`
---
### Variables Not Available in Template
**Symptoms:**
- \`$attributes\` is empty or undefined
- Values don't appear in output
**Solutions:**
1. **Use correct variable names**
\`\`\`php
<?php
// Available variables:
$attributes // Array of all field/control values
$content // Inner blocks content
$block // WP_Block instance (or null in preview)
?>
\`\`\`
2. **Check attribute naming (camelCase)**
\`\`\`json
// block.json
"fields": {
"myTitle": { "type": "text" }
}
\`\`\`
\`\`\`php
// template.php - use same camelCase
$title = $attributes['myTitle'] ?? '';
\`\`\`
3. **Provide default values**
\`\`\`php
// Always use null coalescing
$title = $attributes['title'] ?? 'Default Title';
$items = $attributes['items'] ?? [];
$image = $attributes['image']['url'] ?? '';
\`\`\`
---
### HTML Showing as Text (Not Rendered)
**Symptoms:**
- HTML tags visible as text
- Content not formatted properly
**Solutions:**
1. **Use correct escaping function**
\`\`\`php
// For plain text
<?php echo esc_html($title); ?>
// For rich text / WYSIWYG content
<?php echo wp_kses_post($content); ?>
// For URLs
<?php echo esc_url($url); ?>
\`\`\`
---
### get_block_wrapper_attributes() Not Working
**Symptoms:**
- Block supports not applying
- Missing classes on wrapper
**Solutions:**
1. **Call it correctly**
\`\`\`php
<?php
$wrapper_attributes = get_block_wrapper_attributes([
'class' => 'my-custom-class',
]);
?>
<!-- Echo as attribute string, not array -->
<div <?php echo $wrapper_attributes; ?>>
\`\`\`
2. **Use on root element only**
\`\`\`php
<!-- Correct: on the outermost element -->
<section <?php echo $wrapper_attributes; ?>>
<div class="inner">...</div>
</section>
\`\`\`
`;
}
function getFieldIssues() {
return `## Field Issues
### Field Not Editable in Editor
**Symptoms:**
- Can't click to edit content
- Field appears as static text
**Solutions:**
1. **Add data-proto-field attribute**
\`\`\`php
<!-- Missing attribute - won't be editable -->
<h2><?php echo esc_html($title); ?></h2>
<!-- Correct - field is editable -->
<h2 data-proto-field="title"><?php echo esc_html($title); ?></h2>
\`\`\`
2. **Match field name exactly**
\`\`\`json
// block.json
"fields": {
"heroTitle": { "type": "text" }
}
\`\`\`
\`\`\`php
<!-- Must match exactly (case-sensitive) -->
<h1 data-proto-field="heroTitle"><?php echo esc_html($title); ?></h1>
\`\`\`
3. **Ensure element is visible**
\`\`\`php
<!-- Element must exist and be visible to be clickable -->
<h2 data-proto-field="title">
<?php echo esc_html($title); // Even if empty, element exists ?>
</h2>
\`\`\`
---
### Repeater Items Not Working
**Symptoms:**
- Can't add/remove/reorder items
- Items not displaying correctly
**Solutions:**
1. **Use correct repeater structure**
\`\`\`php
<!-- Container with data-proto-repeater -->
<ul data-proto-repeater="items">
<?php foreach ($items as $item) : ?>
<!-- Each item with data-proto-repeater-item -->
<li data-proto-repeater-item>
<!-- Fields inside items -->
<span data-proto-field="title"><?php echo esc_html($item['title']); ?></span>
</li>
<?php endforeach; ?>
</ul>
\`\`\`
2. **Provide default items for empty state**
\`\`\`php
<?php
$items = $attributes['items'] ?? [];
if (empty($items)) {
$items = [
['title' => 'Item 1'],
['title' => 'Item 2'],
];
}
?>
\`\`\`
---
### Image Field Not Showing
**Symptoms:**
- Image placeholder not clickable
- Selected image not displaying
**Solutions:**
1. **Handle empty image state**
\`\`\`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 : ?>
<!-- Placeholder must have data-proto-field to be clickable -->
<div data-proto-field="image" class="image-placeholder">
Click to add image
</div>
<?php endif; ?>
\`\`\`
2. **Check image sizes configuration**
\`\`\`json
"fields": {
"image": {
"type": "image",
"sizes": ["thumbnail", "medium", "large"]
}
}
\`\`\`
---
### Inner Blocks Not Rendering
**Symptoms:**
- Inner content not appearing
- Block inserter not showing inside block
**Solutions:**
1. **Use data-proto-inner-blocks and $content**
\`\`\`php
<div class="inner-content" data-proto-inner-blocks>
<?php echo $content; ?>
</div>
\`\`\`
2. **Only one inner blocks field per block**
\`\`\`json
// Only one innerblocks field allowed
"fields": {
"content": {
"type": "innerblocks"
}
}
\`\`\`
`;
}
function getControlIssues() {
return `## Control Issues
### Control Not Appearing in Sidebar
**Symptoms:**
- Control missing from inspector panel
- Settings not showing
**Solutions:**
1. **Check control configuration**
\`\`\`json
"controls": {
"layout": {
"type": "select", // Required
"label": "Layout", // Required
"default": "vertical", // Recommended
"options": [ // Required for select/radio
{ "key": "vertical", "label": "Vertical" }
]
}
}
\`\`\`
2. **Verify control type is valid**
Valid types: \`text\`, \`textarea\`, \`select\`, \`toggle\`, \`checkbox\`, \`range\`, \`number\`, \`color\`, \`color-palette\`, \`radio\`, \`image\`
---
### Conditional Control Not Showing/Hiding
**Symptoms:**
- Control always visible or always hidden
- Conditions not being evaluated
**Solutions:**
1. **Check condition syntax**
\`\`\`json
"controls": {
"layout": {
"type": "select",
"options": [
{ "key": "simple", "label": "Simple" },
{ "key": "advanced", "label": "Advanced" }
]
},
"advancedOption": {
"type": "toggle",
"conditions": {
"visible": {
"layout": ["advanced"] // Array of values
}
}
}
}
\`\`\`
2. **Use array for condition values**
\`\`\`json
// Correct
"conditions": {
"visible": {
"showExtra": [true] // Boolean in array
}
}
// Incorrect
"conditions": {
"visible": {
"showExtra": true // Not in array
}
}
\`\`\`
---
### Range Control Not Working
**Symptoms:**
- Slider stuck or not moving
- Value not updating
**Solutions:**
1. **Include required min/max**
\`\`\`json
"columns": {
"type": "range",
"label": "Columns",
"min": 1, // Required
"max": 6, // Required
"step": 1, // Optional, default 1
"default": 3
}
\`\`\`
`;
}
function getStylingIssues() {
return `## Styling Issues
### Styles Not Loading
**Symptoms:**
- Block unstyled in editor and frontend
- CSS file not being enqueued
**Solutions:**
1. **Check file name and location**
\`\`\`
my-block/
├── block.json
├── template.php
└── style.css ← Must be named exactly "style.css"
\`\`\`
2. **Clear caches**
- Browser cache
- WordPress cache
- Any caching plugins
---
### Tailwind Classes Not Working
**Symptoms:**
- Tailwind utility classes not applying
- Styles look wrong
**Solutions:**
1. **Enable Tailwind in block.json**
\`\`\`json
"protoBlocks": {
"useTailwind": true
}
\`\`\`
2. **Check Tailwind is enabled in Proto-Blocks settings**
- Go to Settings → Proto-Blocks
- Ensure Tailwind compilation is enabled
3. **Use valid Tailwind classes**
\`\`\`php
<!-- Valid Tailwind classes -->
<div class="flex items-center gap-4 p-6 bg-white rounded-lg shadow-md">
\`\`\`
---
### Editor Styles Different from Frontend
**Symptoms:**
- Block looks different in editor
- Styles only working on one side
**Solutions:**
1. **Check editor style inheritance**
\`\`\`css
/* Target both contexts */
.my-block {
/* These apply to both */
}
/* Editor-specific (if needed) */
.editor-styles-wrapper .my-block {
/* Editor overrides */
}
\`\`\`
2. **Verify style.css is loaded in editor**
- Proto-Blocks automatically adds styles to editor
- Check for CSS specificity conflicts
---
### Empty Elements Invisible in Editor
**Symptoms:**
- Can't click on empty fields
- Placeholder not showing
**Solutions:**
1. **Style empty elements**
\`\`\`css
.my-block__title:empty::before {
content: 'Click to add title';
color: #999;
}
.my-block__image:empty {
min-height: 150px;
background: #f0f0f0;
display: flex;
align-items: center;
justify-content: center;
}
\`\`\`
`;
}
function getInteractivityIssues() {
return `## Interactivity Issues
### JavaScript Not Running
**Symptoms:**
- Interactive features not working
- No console errors but no functionality
**Solutions:**
1. **Check script registration in block.json**
\`\`\`json
// For traditional scripts
"viewScript": "file:./view.js"
// For ES modules
"viewScriptModule": "file:./view.js"
\`\`\`
2. **For traditional scripts, wrap in DOMContentLoaded**
\`\`\`javascript
document.addEventListener('DOMContentLoaded', function() {
// Your code here
});
\`\`\`
3. **For modules, no wrapper needed**
\`\`\`javascript
// ES modules are deferred automatically
const blocks = document.querySelectorAll('.my-block');
blocks.forEach(initBlock);
\`\`\`
---
### Interactivity API Not Working
**Symptoms:**
- Directives not reactive
- Store not updating
**Solutions:**
1. **Enable interactivity support**
\`\`\`json
"supports": {
"interactivity": true
},
"viewScriptModule": "file:./view.js"
\`\`\`
2. **Add data-wp-interactive to container**
\`\`\`php
<div
data-wp-interactive="namespace/store-name"
data-wp-context='{"isOpen": false}'
>
\`\`\`
3. **Import from correct module**
\`\`\`javascript
import { store, getContext } from '@wordpress/interactivity';
\`\`\`
4. **Use getContext() inside actions**
\`\`\`javascript
store('my-namespace/block', {
actions: {
toggle() {
// Must use getContext() to access reactive context
const context = getContext();
context.isOpen = !context.isOpen;
}
}
});
\`\`\`
---
### Interactivity Context Not Updating
**Symptoms:**
- State changes not reflecting in UI
- Reactive bindings not working
**Solutions:**
1. **Mutate context directly, don't reassign**
\`\`\`javascript
// Correct - mutate existing context
const context = getContext();
context.count++;
// Incorrect - reassigning doesn't work
context = { ...context, count: context.count + 1 };
\`\`\`
2. **For arrays, create new arrays**
\`\`\`javascript
// Correct
context.items = [...context.items, newItem];
context.items = context.items.filter(i => i !== item);
// Incorrect
context.items.push(newItem); // Won't trigger reactivity
\`\`\`
`;
}
function getPerformanceIssues() {
return `## Performance Issues
### Block Editor Slow
**Symptoms:**
- Editor lag when selecting block
- Slow typing in fields
**Solutions:**
1. **Simplify template during preview**
\`\`\`php
<?php
$is_preview = !isset($block) || $block === null;
if ($is_preview) {
// Use simpler markup for editor
}
?>
\`\`\`
2. **Reduce repeater item count**
\`\`\`json
"fields": {
"items": {
"type": "repeater",
"max": 10 // Limit maximum items
}
}
\`\`\`
3. **Optimize images**
- Use appropriate image sizes
- Lazy load where possible
---
### Slow Page Load with Many Blocks
**Symptoms:**
- Frontend page loads slowly
- Many database queries
**Solutions:**
1. **Enable template caching**
- Proto-Blocks caches parsed templates automatically
- Verify cache is working:
\`\`\`bash
wp proto-blocks cache stats
\`\`\`
2. **Clear stale cache**
\`\`\`bash
wp proto-blocks cache clear
\`\`\`
3. **Optimize PHP template code**
\`\`\`php
<?php
// Avoid expensive operations in template
// Don't: query database, call external APIs
// Do: use attributes and simple logic
?>
\`\`\`
---
### Large CSS Bundle
**Symptoms:**
- Large stylesheet size
- Slow initial load
**Solutions:**
1. **Use Tailwind purging** (automatic with Proto-Blocks)
2. **Minimize custom CSS**
3. **Use Tailwind inline for one-off styles**
`;
}
function getEditorIssues() {
return `## Editor Issues
### Block Shows Error in Editor
**Symptoms:**
- "This block has encountered an error"
- Block replaced with error message
**Solutions:**
1. **Check browser console for errors**
- Open Developer Tools (F12)
- Look for JavaScript errors
2. **Validate block.json**
\`\`\`bash
cat block.json | python -m json.tool
\`\`\`
3. **Check for PHP errors in template**
\`\`\`php
// wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
\`\`\`
4. **Clear all caches and refresh**
---
### Block Preview Not Updating
**Symptoms:**
- Changes not reflected in editor
- Stale preview
**Solutions:**
1. **Check AJAX handler**
- Open Network tab in DevTools
- Look for failed AJAX requests
2. **Verify template returns valid HTML**
\`\`\`php
<?php
// Template must output something
// Even empty state needs HTML
?>
<div class="my-block">
<!-- Content here -->
</div>
\`\`\`
3. **Clear Proto-Blocks cache**
\`\`\`bash
wp proto-blocks cache clear
\`\`\`
---
### Block Inspector Panel Empty
**Symptoms:**
- No controls in sidebar
- Settings panel is blank
**Solutions:**
1. **Verify controls configuration**
\`\`\`json
"protoBlocks": {
"controls": {
"setting": {
"type": "toggle",
"label": "My Setting"
}
}
}
\`\`\`
2. **Check for JSON syntax errors**
- Missing commas
- Unclosed brackets
- Invalid property names
---
### Can't Select Block
**Symptoms:**
- Clicking block doesn't select it
- Can't access block toolbar
**Solutions:**
1. **Check z-index conflicts**
\`\`\`css
.my-block {
/* Avoid setting high z-index */
/* Don't use position: fixed/absolute without care */
}
\`\`\`
2. **Ensure wrapper element exists**
\`\`\`php
<?php
$wrapper = get_block_wrapper_attributes();
?>
<!-- Must have wrapper element -->
<div <?php echo $wrapper; ?>>
<!-- Content -->
</div>
\`\`\`
3. **Check for JavaScript errors** blocking interaction
`;
}
