ApostropheCMS y Astro
ApostropheCMS es un sistema de gestión de contenido que admite la edición en la página en Astro.
Integración con Astro
Sección titulada Integración con AstroEn esta sección, utilizarás la integración de Apostrophe para conectar ApostropheCMS con Astro.
Prerrequisitos
Sección titulada PrerrequisitosPara comenzar, necesitarás lo siguiente:
-
Un proyecto de Astro renderizado bajo demanda con el adaptador Node.js instalado y configurado con
output: 'server'
- Si aún no tienes un proyecto de Astro, nuestra guía de instalación te pondrá en marcha en poco tiempo. -
Un proyecto de ApostropheCMS con una variable de entorno configurada llamada
APOS_EXTERNAL_FRONT_KEY
- Esta variable de entorno puede configurarse con cualquier cadena aleatoria. Si aún no tienes un proyecto de ApostropheCMS, la guía de instalación te ayudará a configurar uno rápidamente. Recomendamos encarecidamente utilizar la herramienta de línea de comandos de Apostrophe para facilitar este proceso.
Configuración de la comunicación entre proyectos
Sección titulada Configuración de la comunicación entre proyectosTu proyecto de Astro necesita tener una variable de entorno APOS_EXTERNAL_FRONT_KEY
configurada con el mismo valor que la de tu proyecto de ApostropheCMS para permitir la comunicación entre ambos. Esta clave compartida actúa como un medio para verificar las solicitudes entre el frontend (Astro) y el backend (ApostropheCMS).
Crea un archivo .env
en la raíz de tu proyecto de Astro con la siguiente variable:
Tu directorio raíz ahora debería incluir este nuevo archivo:
Directorysrc/
- …
- .env
- astro.config.mjs
- package.json
Instalación de dependencias
Sección titulada Instalación de dependenciasPara conectar Astro con tu proyecto de ApostropheCMS, instala la integración oficial de Apostrophe en tu proyecto de Astro usando el siguiente comando para tu gestor de paquetes preferido.
Configuración de Astro
Sección titulada Configuración de AstroConfigura ambas integraciones apostrophe-astro
y vite
en tu archivo astro.config.mjs
.
El siguiente ejemplo proporciona la URL base de tu instancia de Apostrophe y las rutas a las carpetas de tu proyecto para mapear entre los widgets y los tipos de plantilla de página de ApostropheCMS y tu proyecto de Astro. También configura el renderizado del lado del servidor de Vite.
Para opciones de configuración completas y explicaciones, consulta la documentación de apostrophe-astro
.
Conexión de widgets de ApostropheCMS a componentes de Astro
Sección titulada Conexión de widgets de ApostropheCMS a componentes de AstroLos widgets de ApostropheCMS son bloques de contenido estructurado que se pueden agregar a la página, como columnas de diseño, imágenes y bloques de texto. Necesitarás crear un componente de Astro para cada widget en tu proyecto de Apostrophe, además de un archivo para mapear esos componentes al widget de Apostrophe correspondiente.
Crea un nuevo directorio en src/widgets/
para tus componentes de Astro y el archivo de mapeo, index.js
.
Componentes mapeados ubicados en esta carpeta reciben una propiedad widget
que contiene los campos del esquema de tu widget, y cualquier propiedad personalizada, a través de Astro.props
. Estos valores están disponibles para la edición en la página.
El siguiente ejemplo muestra un componente RichTextWidget.astro
accediendo al contenido de su widget correspondiente de ApostropheCMS para permitir la edición en contexto:
Algunos widgets estándar de Apostrophe, como imágenes y videos, requieren marcadores de posición porque no contienen contenido editable de forma predeterminada. El siguiente ejemplo crea un componente estándar ImageWidget.astro
que establece el valor de src
condicionalmente al valor de la imagen aposPlaceholder
pasada por el widget, una imagen de respaldo del proyecto Astro, o la imagen seleccionada por el administrador de contenido utilizando el ayudante attachment
de Apostrophe:
Para más ejemplos, consulta los ejemplos de widgets del proyecto de inicio astro-frontend
.
Cada componente .astro
debe mapearse al widget de Apostrophe correspondiente en src/widgets/index.js
.
El ejemplo de abajo agrega los dos componentes anteriores a este archivo:
Consulta la documentación de ApostropheCMS para conocer las convenciones de nomenclatura para widgets estándar, pro y de nivel de proyecto personalizado
El directorio del proyecto debería verse así:
Directorysrc/
Directorywidgets/
- index.js
- ImageWidget.astro
- RichTextWidget.astro
- .env
- astro.config.mjs
- package.json
Agregar tipos de página
Sección titulada Agregar tipos de páginaComo los widgets, cualquier plantilla de tipo de página en tu proyecto de ApostropheCMS necesita tener un componente de plantilla correspondiente en tu proyecto de Astro. También necesitarás un archivo que mapee los tipos de página de Apostrophe a componentes individuales.
Crea un nuevo directorio en src/templates/
para tus componentes de Astro y el archivo de mapeo, index.js
. Los componentes mapeados ubicados en esta carpeta reciben una propiedad page
que contiene los campos del esquema de tu página, y cualquier propiedad personalizada, a través de Astro.props
. Estos valores están disponibles para la edición en la página.
El siguiente ejemplo muestra un componente HomePage.astro
que renderiza una plantilla de página de su tipo de página home-page
de ApostropheCMS, incluyendo un campo de esquema de área llamado main
:
Cada componente .astro
debe mapearse al tipo de página de Apostrophe correspondiente en src/templates/index.js
.
El siguiente ejemplo agrega el componente HomePage.astro
anterior a este archivo:
Consulta la documentación de ApostropheCMS para conocer las convenciones de nomenclatura para tipos de página especiales y tipos de página de piezas.
El directorio del proyecto debería verse así:
Directorysrc/
Directorywidgets/
- index.js
- ImageWidget.astro
- RichTextWidget.astro
Directorytemplates/
- HomePage.astro
- index.js
- .env
- astro.config.mjs
- package.json
Creación del componente […slug.astro] y obtención de datos de Apostrophe
Sección titulada Creación del componente […slug.astro] y obtención de datos de ApostropheDesde que Apostrophe es responsable de conectar URLs con contenido, incluyendo la creación de nuevo contenido y páginas sobre la marcha, solo necesitarás un componente de página de Astro de nivel superior: la ruta [...slug].astro
.
El siguiente ejemplo muestra un componente básico [...slug].astro
:
Consulta la documentación de ApostropheCMS para obtener opciones de plantillas adicionales, incluidos los espacios disponibles en el componente AposTemplate
.
Creación de un blog con Astro y ApostropheCMS
Sección titulada Creación de un blog con Astro y ApostropheCMSCon la integración configurada, ahora puedes crear un blog con Astro y ApostropheCMS. Tu blog utilizará una pieza de Apostrophe, un tipo de contenido independiente que se puede incluir en cualquier página, y un tipo de página de pieza, un tipo de página especializado que se utiliza para mostrar esas piezas individualmente o colectivamente.
Prerrequisitos
Sección titulada Prerrequisitos- Un proyecto de ApostropheCMS con la herramienta de línea de comandos de Apostrophe instalada - Puedes crear un nuevo proyecto o utilizar uno existente. Sin embargo, este tutorial solo mostrará cómo crear un tipo de pieza de blog y un tipo de página de pieza. Deberás integrar cualquier otro código de proyecto existente de forma independiente. Si no tienes la herramienta de línea de comandos instalada, puedes obtener instrucciones de instalación aquí.
- Un proyecto de Astro integrado con ApostropheCMS - Para crear un proyecto desde cero, consulta integración con Astro para obtener instrucciones sobre cómo configurar la integración, o utiliza el proyecto de inicio astro-frontend.
Creación de un tipo de pieza de blog y un tipo de página de pieza
Sección titulada Creación de un tipo de pieza de blog y un tipo de página de piezaPara crear tu tipo de pieza de blog y tu tipo de página de pieza para su visualización, navega a la raíz de tu proyecto de ApostropheCMS en tu terminal. Utiliza la herramienta de línea de comandos de ApostropheCMS para crear el nuevo tipo de pieza y el tipo de página de pieza con el siguiente comando:
Esto creará dos nuevos módulos en tu proyecto, uno para el tipo de pieza de blog y otro para el tipo de página de pieza correspondiente. A continuación, abre el archivo app.js
en la raíz de tu proyecto de ApostropheCMS en tu editor de código y agrega tus nuevos módulos.
El módulo blog-page
también debe agregarse al array de opciones types
del módulo @apostrophecms/page
para que pueda seleccionarse en el modal de creación de página. En tu proyecto de ApostropheCMS, abre el archivo modules/@apostrophecms/page/index.js
y agrega el blog-page
.
Creación del esquema del blog
Sección titulada Creación del esquema del blogEn un proyecto de ApostropheCMS, los editores tienen un conjunto de campos de entrada para agregar contenido. Aquí tienes un ejemplo de una publicación de blog simple que agrega tres campos de entrada, un authorName
, publicationDate
y un área de content
donde los administradores de contenido pueden agregar múltiples instancias de widgets. En este caso, estamos especificando que pueden agregar los widgets de imagen y texto enriquecido que creamos durante la configuración de la integración.
En este punto, todos los componentes provenientes del proyecto de ApostropheCMS están configurados. Inicia el sitio local desde la línea de comandos usando npm run dev
, asegurándote de pasar la variable de entorno APOS_EXTERNAL_FRONT_KEY
configurada con tu cadena seleccionada:
Mostrando las publicaciones del blog
Sección titulada Mostrando las publicaciones del blogPara mostrar una página con todas las publicaciones del blog, crea un archivo de componente BlogIndex.astro
en el directorio src/templates
de tu proyecto de Astro y agrega el siguiente código:
Después de obtener los datos de la página y las piezas de la propiedad aposData
, este componente crea el marcado utilizando los campos del esquema de la pieza de blog que creamos, pero también del piece.title
y piece._url
que se agrega a cada pieza por Apostrophe.
Para mostrar publicaciones individuales del blog, crea un archivo BlogShow.astro
en el directorio src/templates
de tu proyecto de Astro con el siguiente código:
Este componente usa el componente <AposArea>
para mostrar cualquier widget agregado al área content
y el contenido authorName
y publicationDate
ingresado en los campos del mismo nombre.
Finalmente, estos componentes de Astro deben mapearse a los tipos de página correspondientes de ApostropheCMS. Abre el archivo src/templates/index.js
del proyecto de Astro y modifícalo para que contenga el siguiente código:
Creación de publicaciones de blog
Sección titulada Creación de publicaciones de blogAgregar publicaciones de blog a tu sitio se logra utilizando las herramientas de contenido y gestión de ApostropheCMS para crear esas publicaciones y publicando al menos una página de índice para mostrarlas.
Con el servidor de desarrollo de Astro en funcionamiento, navega a la página de inicio de sesión ubicada en http://localhost:4321/login en tu navegador. Utiliza las credenciales que se agregaron durante la creación del proyecto de ApostropheCMS para iniciar sesión como administrador. Tu proyecto de ApostropheCMS debería seguir en funcionamiento.
Una vez que hayas iniciado sesión, tu navegador se redirigirá a la página de inicio de tu proyecto y mostrará una barra de administración en la parte superior para editar contenido y administrar tu proyecto.
Para publicar tu primera publicación de blog, haz clic en el botón Blogs
en la barra de administración para abrir el modal de creación de piezas de blog. Haciendo clic en el botón New Blog
en la esquina superior derecha se abrirá un modal de edición donde podrás agregar contenido. El campo de área content
te permitirá agregar tantos widgets de imagen y texto enriquecido como desees.
Puedes repetir este paso y agregar tantas publicaciones como desees. También seguirás estos pasos cada vez que quieras agregar una nueva publicación.
Para publicar una página para mostrar todas tus publicaciones, haz clic en el botón Pages
en la barra de administración. Desde el modal del árbol de páginas, haz clic en el botón New Page
. En el menú desplegable Type
en la columna derecha, selecciona Blog
. Agrega un título para la página y luego haz clic en Publish and View
. Solo necesitarás hacer esto una vez.
Cualquier nueva publicación de blog que se cree se mostrará automáticamente en esta página. Las publicaciones de blog individuales se pueden mostrar haciendo clic en el enlace creado en la página de índice.
El área content
de las publicaciones individuales se puede editar directamente en la página navegando a la publicación y haciendo clic en edit
en la barra de administración. Otros campos se pueden editar utilizando el modal de edición que se abre al hacer clic el menú Blogs
en la barra de administración.
Despliegue de tu sitio
Sección titulada Despliegue de tu sitioPara desplegar tu sitio web, necesitas alojar tanto tus proyectos de Astro como de ApostropheCMS.
Para Astro, visita nuestras guías de despliegue y sigue las instrucciones para tu proveedor de alojamiento preferido.
Para el proyecto de ApostropheCMS, sigue las instrucciones para tu tipo de alojamiento en nuestra guía de alojamiento. Finalmente, deberás proporcionar una variable de entorno APOS_HOST
al proyecto de Astro para reflejar la URL correcta donde se ha desplegado tu sitio de ApostropheCMS.
Recursos Oficiales
Sección titulada Recursos Oficiales- Integración de ApostropheCMS con Astro - Plugin de ApostropheCMS para Astro, guía de integración y proyectos de inicio para Apostrophe y Astro
- Proyecto de muestra de Astro para usar con ApostropheCMS - Un proyecto simple de Astro con varias páginas y widgets de Apostrophe ya creados.
- Kit de muestra de inicio de ApostropheCMS para usar con Astro - Un proyecto de ApostropheCMS con modificaciones de página básicas para usar con Astro.
Recursos de la Comunidad
Sección titulada Recursos de la Comunidad- Integrando ApostropheCMS con Astro, Parte 1 por Antonello Zaini
- Integrando ApostropheCMS con Astro, Parte 2 por Antonello Zaini
- Mostrar y contar en vivo | Astro & Apostrophe (en inglés)