Páginas en Grav
Como escribir su contenido en Grav
En Grav, Páginas son los bloques fundamentales de construcción de tu sitio. Son cómo escribes contenido y proporcionas navegación en el sistema Grav.
Combinar contenido y navegación asegura que el sistema sea intuitivo de usar incluso para los autores de contenido más inexpertos. Sin embargo, este sistema, junto con potentes capacidades de taxonomía, sigue siendo lo suficientemente potente como para manejar requisitos de contenido complejos.
Grav admite nativamente 3 tipos de Páginas que te permiten crear una amplia selección de contenido web. Esos tipos son:
Página Estándar
Una Página estándar es generalmente una sola página como una publicación de blog, formulario de contacto, página de error, etc. Este es el tipo más común de página que crearás. Por defecto, una Página se considera una página estándar a menos que le indiques lo contrario a Grav.
Cuando descargas e instalas el paquete Núcleo Grav, te recibe una página estándar. Cubrimos la creación de una Página estándar simple en el Tutorial Básico.
Página de Listado
Esta es una extensión de una Página estándar. Esta es una página que tiene una referencia a una colección de páginas.
El enfoque más directo para configurar esto es crear páginas hijas debajo de la Página de Listado. Un ejemplo de esto sería una página de listado de blog, donde mostrarías un resumen de las publicaciones de blog que existen como páginas hijas.
También hay algunas configuraciones para controlar el orden de la lista, así como un límite en el número de elementos, y si se debe habilitar o no la paginación.
Un Esqueleto de Blog de muestra usando una Página de Listado se puede encontrar en las Descargas de Grav.
Página Modular
Una Página Modular es un tipo especial de página de listado porque construye una página única a partir de sus páginas hijas o módulos. Esto permite la capacidad de construir diseños de una sola página muy complejos a partir de Módulos. Esto se logra construyendo la Página Modular a partir de múltiples Módulos encontrados en la carpeta principal de la página modular.
Un Esqueleto de Página Única de muestra usando una Página Modular se puede encontrar en las Descargas de Grav.
Cada uno de estos tipos de páginas sigue la misma estructura básica, así que antes de entrar en los detalles de cada tipo, debemos explicar cómo se construyen las páginas en Grav.
Un Módulo, porque está destinado a ser parte de otra página, es inherentemente una página a la que no se puede llegar directamente a través de una URL. Debido a esto, todas las páginas de módulos se establecen de forma predeterminada como no enrutable.
Carpetas
Todas las páginas de contenido se encuentran en la carpeta /user/pages. Cada Página debe colocarse en su propia carpeta.
Los nombres de carpetas también deben ser slugs válidos. Los slugs son completamente en minúsculas, con caracteres acentuados reemplazados por letras del alfabeto latino y los caracteres de espacio en blanco reemplazados por un guión o un guión bajo, para evitar que se codifiquen.
Grav entiende que cualquier valor entero seguido de un punto será únicamente para ordenar, y se elimina internamente en el sistema. Por ejemplo, si tienes una carpeta llamada 01.home, Grav tratará esta carpeta como home, pero se asegurará de que con el orden predeterminado, aparezca antes que 02.blog.
/user
└── /pages
├── /01.home
│ ├── /_header
│ ├── /_features
│ ├── /_body
├── /02.blog
│ ├── /blog-item-1
│ ├── /blog-item-2
│ ├── /blog-item-3
│ ├── /blog-item-4
│ └── /blog-item-5
├── /03.about-us
└── /errorTu sitio debe tener un punto de entrada para que sepa dónde ir cuando apuntes tu navegador a la raíz de tu sitio. Por ejemplo, si escribieras http://tusitio.com en tu navegador, por defecto Grav espera un alias home/, pero puedes anular la ubicación de inicio cambiando la opción home.alias en el archivo de configuración de Grav.
Módulos se identifican con un guion bajo (_) antes del nombre de la carpeta. Este es un tipo de carpeta especial que está destinada a ser utilizada solo con contenido modular. Estos no son enrutables y no son visibles en la navegación. Un ejemplo de configuración de página modular sería una carpeta como user/pages/01.home. Home está configurado como una página modular que contendría una colección de módulos, y se construiría a partir de las carpetas _header, _features y _body dentro de la carpeta home.
El nombre textual de cada carpeta por defecto es el slug que el sistema utiliza como parte de la URL. Por ejemplo, si tienes una carpeta como /user/pages/02.blog, el slug para esta página sería por defecto blog, y la URL completa sería http://tusitio.com/blog. Una página de ítem de blog, ubicada en /user/pages/02.blog/blog-item-5 sería accesible a través de http://tusitio.com/blog/blog-item-5.
Si no se proporciona ningún número como prefijo del nombre de la carpeta, la página se considera invisible y no aparecerá en la navegación. Un ejemplo de esto sería la página error en la estructura de carpetas anterior.
Esto se puede anular en la página misma configurando el parámetro visible en los encabezados.
Ordenación
Cuando se trata de colecciones, hay varias opciones disponibles para controlar cómo se ordenan las carpetas. La opción más importante se establece en content.order.by de la configuración de la página. Las opciones son:
| Propiedad | Descripción |
|---|---|
| default | El orden se basa en el sistema de archivos, es decir, 01.home antes de 02.advark |
| title | El orden se basa en el título definido en cada página |
| basename | El orden se basa en la carpeta alfabética sin orden numérico |
| date | El orden se basa en la fecha definida en cada página |
| modified | El orden se basa en la marca de tiempo modificada de la página |
| folder | El orden se basa en el nombre de la carpeta con cualquier prefijo numérico, es decir, 01., eliminado |
| header.x | El orden se basa en cualquier campo de encabezado de página. es decir, header.taxonomy.year. También se puede agregar un valor predeterminado a través de una tubería. es decir, header.taxonomy.year|2015 |
| manual | El orden se basa en la variable order_manual |
| random | El orden se aleatoriza |
Puedes definir específicamente un orden manual proporcionando una lista de opciones para la configuración de content.order.custom. Esto funcionará en conjunto con content.order.by porque primero intenta ordenar las páginas manualmente, pero cualquier página no especificada en el orden manual, pasará y se ordenará por el orden proporcionado.
Puedes anular el comportamiento predeterminado para la ordenación de carpetas y la dirección en la que ocurre la ordenación configurando las opciones pages.order.dir y pages.order.by en el archivo de configuración del sistema Grav.
Archivo de Página
Dentro de la carpeta de la página, creamos el archivo de página real. El nombre de archivo debe terminar con .md para indicar que es un archivo formateado en Markdown. Técnicamente, es Markdown con FrontMatter YAML, lo que suena impresionante pero realmente no es gran cosa. Cubriremos los detalles de la estructura del archivo pronto.
Lo importante es entender que el nombre del archivo hace referencia directa al nombre del archivo de plantilla del tema que se utilizará para renderizar. El nombre estándar para el archivo de plantilla principal es default, por lo que el archivo se llamaría default.md.
Por supuesto, puedes nombrar tu archivo como quieras, por ejemplo: documento.md, lo que haría que Grav busque un archivo de plantilla en el tema que coincida, como la plantilla Twig document.html.twig.
Este comportamiento se puede anular en la página configurando el parámetro de plantilla en los encabezados.
Un archivo de página de ejemplo podría verse así:
---
title: Título de la Página
taxonomy:
category: blog
---# Título de la Página
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque porttitor eu
felis sed ornare. Sed a mauris venenatis, pulvinar velit vel, dictum enim. Phasellus
ac rutrum velit. **Nunc lorem** purus, hendrerit sit amet augue aliquet, iaculis
ultricies nisl. Suspendisse tincidunt euismod risus, _quis feugiat_ arcu tincidunt
eget. Nulla eros mi, commodo vel ipsum vel, aliquet congue odio. Class aptent taciti
sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Pellentesque
velit orci, laoreet at adipiscing eu, interdum quis nibh. Nunc a accumsan purus.Las configuraciones entre los marcadores --- se conocen como FrontMatter YAML, y está compuesto de configuraciones YAML básicas para la página.
En este ejemplo, estamos estableciendo explícitamente el título, así como la taxonomía a blog para poder filtrarla más tarde. El contenido después del segundo --- es el contenido real que se compilará y se renderizará como HTML en tu sitio. Esto está escrito en Markdown, que se cubrirá en detalle en un capítulo futuro. Solo debes saber que los marcadores #, ** y _ se traducen a título 1, negrita y cursiva, respectivamente.
Asegúrate de guardar tus archivos .md como archivos codificados en UTF-8. Esto garantizará que funcionen con caracteres especiales específicos del idioma.
Tamaño del Resumen y Separador
Hay un ajuste en el archivo site.yaml que te permite definir un tamaño predeterminado (en caracteres) del resumen que se puede usar a través de page.summary() para mostrar un resumen o sinopsis de la página. Esto es particularmente útil para blogs donde deseas tener una lista que contenga solo información de resumen y no el contenido completo de la página.
Por defecto, este valor es de 300 caracteres. Puedes anular esto en tu archivo user/config/site.yaml, pero un enfoque aún más útil es usar el separador de resumen manual también conocido como delimitador de resumen: ===.
Debes asegurarte de poner esto en tu contenido con líneas en blanco arriba y abajo. Por ejemplo:
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat.
===
Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
proident, sunt in culpa qui officia deserunt mollit anim id est laborum.Esto utilizará el texto arriba del separador cuando se haga referencia por page.summary() y el contenido completo de la página cuando se haga referencia por page.content().
Cuando uses page.summary(), se utilizará el ajuste de tamaño de resumen si no se encuentra el separador en el contenido de la página.
Encontrar Otras Páginas
Grav tiene una característica útil que te permite encontrar otra página y realizar acciones en esa página. Esto se puede lograr con el método find() que simplemente toma la ruta y devuelve un nuevo objeto Página.
Esto te permite realizar una amplia variedad de funcionalidades desde cualquier página en tu sitio Grav. Por ejemplo, es posible que desees proporcionar una lista de todos los proyectos actuales en una página de detalle de proyecto en particular:
# Todos los Proyectos
<ul>
{% for p in pages.find('/projects').children if p != page %}
<li><a href="{{ p.url|e }}">{{ p.title|e }}</a></li>
{% endfor %}
</ul>El objeto pages no está disponible cuando se procesa Twig directamente en el contenido Markdown. Sin embargo, el objeto page y su método find() heredado sí lo están, por lo que podrías usar {% for p in page.find('/projects').children %} como reemplazo para lo anterior. Ten en cuenta que pages se refiere a todas las Páginas disponibles para Grav, y page se refiere a una sola, y a menudo la página actual, Página.
En las siguientes secciones, continuaremos profundizando en los detalles de una página y las colecciones de páginas en detalle.
contentMeta
Referenciar páginas y contenido es sencillo, pero ¿qué hay del contenido que no se renderiza en el frente junto con el resto de la página?
Cuando Grav lee el contenido de la página, almacena este contenido en caché. De esta manera, la próxima vez que se renderice la página, no tiene que leer todo el contenido del archivo .md. Generalmente, este contenido se renderiza todo al frente. Sin embargo, hay casos en los que tener algunos datos adicionales almacenados junto a la página en caché es útil.
Aquí es donde entra en juego contentMeta(). Usamos ContentMeta en nuestro complemento Shortcode para recuperar secciones de otras páginas usando shortcodes. Por ejemplo:
<div id="author">{{ page.find('/my/custom/page').contentMeta.shortcodeMeta.shortcode.section.author|e }}</div>Usamos esto en Shortcode Core para almacenar activos CSS y JS que el shortcode en la página requiere, sin embargo, esta característica se puede usar para almacenar casi cualquier estructura de datos que necesites.