Formularios - Parte 1
Blueprints
¿Qué es un Blueprint?
Los Blueprints son un aspecto importante de Grav. Esencialmente, son la base de la interacción de un tema o plugin con el administrador de Grav. Le dicen a Grav qué es un tema o plugin, su nombre, dónde se puede encontrar en GitHub, etc. También generan las opciones de configuración para ese tema o plugin en el administrador de Grav.
Un Blueprint se define en un archivo YAML y puede alojar tanto propiedades como definiciones de formularios.
La gran mayoría de los usuarios de Grav nunca tendrán que trabajar con Blueprints. En pocas palabras, determinan cómo aparecen los plugins y temas en el backend del sitio. Para la mayoría de los usuarios, esto es donde se detienen, configurando sus temas y plugins usando el administrador de Grav o manipulando opciones dentro del archivo YAML principal del tema o plugin.
Las personas que trabajarán más con Blueprints son los desarrolladores que están creando nuevos temas y plugins y personalizando las opciones de un recurso en el backend. Son una herramienta poderosa que define qué es tu recurso, dónde puede encontrar Grav actualizaciones para él y qué opciones de configuración deberías poder establecer en el backend.
Tipos de Blueprints
Grav utiliza Blueprints para:
- definir la información de temas y plugins.
- definir opciones de configuración de tema/plugin para mostrarse en el Administrador.
- definir los formularios de Páginas en el Administrador.
- definir las opciones mostradas en la sección de Configuración del Administrador.
- definir directorios/objetos flexibles.
En este punto, desglosaremos detalles adicionales sobre cómo funcionan los Blueprints en Grav.
Temas y Plugins
Cuando se utilizan con temas y plugins, la convención es colocar un blueprints.yaml en el paquete. Hacer esto le dice a Grav los metadatos de ese recurso, lo que lo introduce al administrador de Grav.
Un archivo blueprints.yaml es una parte importante de cualquier tema y plugin. Es esencial para el sistema GPM (Grav Package Manager). GPM utiliza la información almacenada en el blueprint para poner el plugin a disposición de los usuarios.
En nuestro ejemplo de blueprint para un plugin, profundizamos en el blueprint del plugin Assets. Este blueprint establece el nombre, la información del autor, palabras clave, página de inicio, enlace para informes de errores y otros metadatos que no solo le dicen a Grav dónde puede localizar actualizaciones para el plugin, sino también proporcionar un recurso útil para el usuario accesible desde el Administrador de Grav.
Una vez dada esta información, más abajo en la página del Blueprint, encuentras información de formularios. Esta información crea los Formularios de Administración que son accesibles por el usuario en el backend de Grav. Por ejemplo, si quisieras añadir un toggle que habilite o deshabilite una característica particular de ese plugin, lo agregarías aquí.
El archivo blueprints.yaml funciona con el archivo YAML nombrado del plugin (por ejemplo: assets.yaml). El blueprint establece cuáles son las opciones configurables y el archivo YAML nombrado del recurso establece sus valores. Este archivo YAML nombrado es luego duplicado en la sección user/config de la instancia de Grav para sobrescribir estos valores predeterminados ya sea manualmente o a través del administrador de Grav.
Así que esencialmente, cuando se trata de cualquier opción de configuración para un tema o plugin, el archivo blueprints.yaml lo define, y el archivo YAML nombrado del recurso te dice en qué está configurado.
Páginas
Las Páginas de Grav pueden ser realmente cualquier cosa. Una página puede ser una lista de blog, una entrada de blog, una página de producto, una galería de imágenes, etc.
Lo que determina qué debe hacer una página y cómo debe aparecer es el Blueprint de Página.
Grav proporciona algunos Blueprints básicos de Página: Default y Modular. Esos son los dos principales bloques de construcción de Grav.
Los Blueprints de página adicionales son añadidos y configurados por el tema, que puede decidir agregar tantos Blueprints de página como sea posible, o enfocarse en algunos Blueprints de página específicos según lo que necesite hacer.
Un tema de Grav es mucho más flexible y poderoso de lo que podrías estar acostumbrado en otras plataformas.
Esto permite que los temas sean específicos de una aplicación. Por ejemplo, un tema podría especializarse en uno de estos objetivos:
- construir un sitio de documentación, como el que estás leyendo ahora.
- construir un sitio de comercio electrónico.
- construir un blog.
- construir un sitio de portafolio.
Un tema también puede permitir a sus usuarios construir todos ellos, pero por lo general un tema afinado creado para un solo propósito puede satisfacer ese objetivo mejor que un tema genérico.
Un archivo de página es usado por una página configurando su nombre de archivo markdown, por ejemplo blog.md, default.md o form.md.
Cada uno de esos archivos usará un archivo de página diferente. También puedes cambiar el tipo de archivo usando la propiedad de encabezado de la plantilla.
El template usado por una página no solo determina el "look and feel" en el frontend, sino que también determina cómo lo renderizará el Plugin Admin, permitiéndote agregar opciones, selectores, entradas personalizadas y toggles.
Cómo hacerlo: en tu tema, añade una carpeta blueprints/ y agrega un archivo YAML con el nombre del template de página que añadiste. Por ejemplo, si añades un template de página blog, agrega un archivo blueprints/blog.yaml. Puedes encontrar un ejemplo de este directorio en el tema Antimatter.
Componentes de un Blueprint
Hay dos conjuntos de información presentados en un archivo blueprints.yaml. El primer conjunto de información de metadatos es la identidad del recurso en sí, el segundo conjunto es sobre los formularios. Toda esta información se almacena en un único archivo blueprints.yaml almacenado en la raíz de cada plugin y tema.
Aquí tienes un ejemplo de la parte de metadatos de un archivo blueprints.yaml:
name: GitHub
slug: github
type: plugin
version: 1.0.1
description: "Este plugin envuelve la [API de GitHub v3](https://developer.github.com/v3/) y usa la biblioteca [php-github-api](https://github.com/KnpLabs/php-github-api/) para añadir un toque agradable de GitHub a tus páginas de Grav."
icon: github
author:
name: Team Grav
email: devs@getgrav.org
url: https://getgrav.org
homepage: https://github.com/getgrav/grav-plugin-github
keywords: github, plugin, api
bugs: https://github.com/getgrav/grav-plugin-github/issues
license: MITComo puedes ver aquí, esta área contiene mucha información general de identificación sobre el plugin, incluyendo su nombre, número de versión, descripción, información del autor, licencia, palabras clave y URL donde puedes encontrar más información o reportar errores. Puedes ver esta sección en acción en la captura de pantalla tomada del Administrador de Grav a continuación.
La siguiente sección es el área de formularios, que está solo un par de espacios debajo de los datos listados anteriormente. Esta área del blueprint genera formularios y campos usados para configurar el plugin desde el Administrador de Grav. Aquí hay un ejemplo rápido de esta área del archivo blueprints.yaml.
form:
validation: strict
fields:
enabled:
type: toggle
label: Plugin status
highlight: 1
default: 1
options:
1: Enabled
0: Disabled
validate:
type: boolEsta área del archivo crea opciones administrativas accesibles en el Administrador de Grav. En este caso particular, hemos creado un simple interruptor de estado de Plugin que permite al usuario habilitar o deshabilitar el plugin desde el administrador (como se muestra a continuación).
Depuración de Blueprints
Los errores en los archivos de Blueprint pueden causar resultados inesperados.
CONSEJO: Puedes ejecutar el comando CLI bin/grav yamllinter para obtener un informe sobre los errores en los archivos YAML. Esto puede ser invaluable al modificar archivos YAML.