Primeros pasos
Esta guía te ayudará a configurar Blockstudio y crear tu primer bloque personalizado.
Instalación
Mediante Composer (recomendado)
composer require blockstudio/blockstudio
Blockstudio se puede instalar como plugin mediante composer/installers o incluir directamente en un tema. Consulta la documentación de Composer para conocer todos los métodos de instalación.
Las instalaciones de Composer reciben actualizaciones mediante Composer. El actualizador integrado de GitHub se desactiva automáticamente.
Instalación manual
Descarga la última versión desde GitHub
Sube el archivo zip al directorio de plugins de WordPress y activa el plugin. Las instalaciones manuales reciben notificaciones automáticas de actualización en el escritorio de WordPress mediante el actualizador integrado de GitHub.
Ambos métodos de instalación incluyen copias privadas de las bibliotecas Markdown, YAML y de actualización, junto con sus dependencias. No usan ni reemplazan las versiones proporcionadas por otro plugin o tema. Instale su propia dependencia Composer si su aplicación usa directamente alguna de esas bibliotecas; las copias incluidas en Blockstudio son internas y no constituyen una PHP API pública.
Comprobaciones de actualizaciones autenticadas
Por defecto, las instalaciones manuales comprueban GitHub de forma anónima. Varios sitios que comparten una misma IP saliente pueden agotar el límite anónimo de API de GitHub y recibir respuestas HTTP 403 al buscar actualizaciones. En 7.7.4, configure un token de acceso personal GitHub en wp-config.php antes de que se cargue WordPress:
define('BLOCKSTUDIO_GITHUB_TOKEN', 'your-github-token');
El token solo necesita acceso a la información de repositorios públicos. No conceda permisos de escritura. Guárdelo en la configuración del servidor, fuera del control de versiones, de blockstudio.json, de los atributos de bloque y del código del frontend. El actualizador se lo pasa al cliente GitHub incluido para realizar comprobaciones autenticadas y descargar versiones. Las solicitudes a otros repositorios y a otros hosts de descarga no reciben el token.
Para secretos gestionados mediante el entorno, un plugin MU puede proporcionar o anular el token:
<?php
add_filter('blockstudio/updater/token', function ($token) {
return getenv('BLOCKSTUDIO_GITHUB_TOKEN') ?: $token;
});
El filtro se ejecuta cuando Blockstudio inicializa su actualizador, antes de que se cargue el tema. Regístrelo en un plugin MU en lugar de en functions.php. Si devuelve una cadena vacía, se desactiva la autenticación aunque la constante esté definida. Los valores vacíos o que no sean cadenas mantienen las comprobaciones anónimas. Los tokens son opcionales; sin uno, el comportamiento actual de las actualizaciones no cambia. Las instalaciones Composer siguen usando Composer para las actualizaciones y no inicializan este actualizador.
Cómo crear tu primer bloque
1. Crea un directorio para el bloque
Crea un directorio nuevo en tu tema:
my-theme/
blockstudio/
my-first-block/
block.json
index.php
2. Define el esquema del bloque
Crea block.json con la configuración del bloque:
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/my-first-block",
"title": "My First Block",
"category": "common",
"icon": "star-filled",
"blockstudio": {
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Hello World"
},
{
"id": "content",
"type": "textarea",
"label": "Content"
}
]
}
}
3. Crea la plantilla
Crea index.php para el renderizado:
<div class="my-first-block">
<h2><?php echo $a['heading']; ?></h2>
<p><?php echo $a['content']; ?></p>
</div>
Uso de plantillas Twig
Blockstudio admite plantillas Twig de forma nativa. Solo tienes que usar index.twig:
<div class="my-first-block">
<h2>{{ a.heading }}</h2>
<p>{{ a.content }}</p>
</div>
Cómo añadir estilos
Crea un archivo style.css en la misma carpeta:
.my-first-block {
padding: 2rem;
background: #f5f5f5;
}
Blockstudio pondrá automáticamente esta hoja de estilos en cola cuando se use el bloque.
Traducciones
Los controles del editor y la vista general de administración de Blockstudio cargan traducciones JavaScript para el dominio de texto blockstudio mediante WordPress. Instala un paquete de idioma compatible o genera archivos JSON de traducción de scripts con tu herramienta de traducción en wp-content/languages/plugins/. Las cadenas sin traducción disponible se mantienen en inglés. Esto traduce la propia interfaz de Blockstudio, no el contenido ni las etiquetas de campo que defines en tus bloques.
Próximos pasos
Tu bloque ya está listo para usarse en el editor WordPress. Sigue explorando la documentación para aprender sobre:
- Tipos de campo – Todos los tipos de campo disponibles
- Componentes – InnerBlocks, RichText y más
- Integración con Tailwind – Cómo usar Tailwind CSS
- Hooks – Cómo ampliar la funcionalidad con filtros y acciones
Cómo crear una biblioteca de bloques
Pasa de un solo bloque a una biblioteca completa: tokens de diseño, el patrón de secciones, campos repetidores, imágenes y composición de páginas.