ApostropheCMS & Astro
ApostropheCMS est un système de gestion de contenu qui prend en charge l’édition de pages dans Astro.
Intégration avec Astro
Titre de la section Intégration avec AstroDans cette section, vous utiliserez l’intégration Apostrophe pour connecter ApostropheCMS à Astro.
Prérequis
Titre de la section PrérequisPour commencer, vous devez disposer des éléments suivants :
-
Un projet Astro affiché à la demande avec l’adaptateur Node.js installé et
output : 'server'
configuré - Si vous n’avez pas encore de projet Astro, notre guide d’installation vous permettra d’être opérationnel en un rien de temps. -
Un projet ApostropheCMS avec une variable d’environnement configurée appelée
APOS_EXTERNAL_FRONT_KEY
- Cette variable d’environnement peut être configurée avec n’importe quelle chaîne de caractères aléatoire. Si vous n’avez pas encore de projet ApostropheCMS, le guide d’installation vous permettra de l’installer rapidement. Nous recommandons fortement l’utilisation de l’outil CLI d’Apostrophe pour faciliter cette opération.
Mise en place de la communication entre les projets
Titre de la section Mise en place de la communication entre les projetsVotre projet Astro doit avoir une variable d’environnement APOS_EXTERNAL_FRONT_KEY
définie à la même valeur que celle de votre projet ApostropheCMS pour permettre la communication entre les deux. Cette clé partagée permet de vérifier les requêtes entre le frontend (Astro) et le backend (ApostropheCMS).
Créez un fichier .env
à la racine de votre projet Astro avec la variable suivante :
Votre répertoire racine doit maintenant contenir ce nouveau fichier :
Répertoiresrc/
- …
- .env
- astro.config.mjs
- package.json
Installation des dépendances
Titre de la section Installation des dépendancesPour connecter Astro à votre projet ApostropheCMS, installez l’intégration officielle d’Apostrophe dans votre projet Astro en utilisant la commande ci-dessous pour votre gestionnaire de paquets préféré.
Configuration d’Astro
Titre de la section Configuration d’AstroConfigurez l’intégration apostrophe-astro
et vite
dans votre fichier astro.config.mjs
.
L’exemple suivant fournit l’URL de base de votre instance d’Apostrophe et les chemins vers les dossiers de votre projet pour établir une correspondance entre les types widgets et les templates de page d’ApostropheCMS et votre projet Astro. Il configure également l’affichage côté serveur de Vite.
Pour les options de configuration complètes et les explications, voir la documentation apostrophe-astro
.
Connecter les widgets d’ApostropheCMS aux composants Astro
Titre de la section Connecter les widgets d’ApostropheCMS aux composants AstroLes widgets d’ApostropheCMS sont des blocs de contenu structuré qui peuvent être ajoutés à la page, tels que des colonnes de mise en page, des images et des blocs de texte. Vous devrez créer un composant Astro pour chaque widget dans votre projet Apostrophe, ainsi qu’un fichier pour faire correspondre ces composants au widget Apostrophe correspondant.
Créez un nouveau dossier dans src/widgets/
pour vos composants Astro et le fichier de correspondance, index.js
.
Les composants mappés situés dans ce dossier reçoivent une propriété widget
contenant les champs du schéma de votre widget, et tous les props personnalisés, à travers Astro.props
. Ces valeurs sont alors disponibles pour l’édition sur la page.
L’exemple suivant montre un composant RichTextWidget.astro
accédant au contenu de son widget ApostropheCMS correspondant pour permettre une édition en contexte :
Certains widgets standard d’Apostrophe, tels que les images et les vidéos, nécessitent des placeholders car ils ne contiennent pas de contenu éditable par défaut. L’exemple suivant crée un composant standard ImageWidget.astro
qui définit la valeur src
conditionnellement à la valeur de l’image aposPlaceholder
passée par le widget, à une image de repli du projet Astro, ou à l’image sélectionnée par le gestionnaire de contenu en utilisant l’aide attachment
d’Apostrophe :
Pour plus d’exemples, voir les exemples de widgets de projets de démarrage astro-frontend
.
Chaque composant .astro
doit être associé au widget Apostrophe correspondant dans src/widgets/index.js
.
L’exemple ci-dessous ajoute les deux composants précédents à ce fichier :
Voir la documentation d’ApostropheCMS pour les conventions de nommage des widgets standard, pro et personnalisés au niveau du projet.
Le répertoire du projet devrait maintenant ressembler à ceci :
Répertoiresrc/
- …
Répertoirewidgets/
- …
- index.js
- ImageWidget.astro
- RichTextWidget.astro
- .env
- astro.config.mjs
- package.json
Ajouter des types de pages
Titre de la section Ajouter des types de pagesComme pour les widgets, tout modèle de type de page dans votre projet ApostropheCMS doit avoir un composant de modèle correspondant dans votre projet Astro. Vous aurez également besoin d’un fichier qui associe les types de pages Apostrophe aux composants individuels.
Créez un nouveau dossier dans src/templates/
pour vos composants Astro et le fichier de correspondance, index.js
. Les composants mappés situés dans ce dossier reçoivent une propriété page
contenant les champs du schéma de votre page, et tous les props personnalisés, à travers Astro.props
. Ces composants peuvent également accéder à un composant AposArea
pour afficher les zones d’apostrophe.
L’exemple suivant montre un composant HomePage.astro
affichant un modèle de page à partir de son type de page correspondant home-page
ApostropheCMS, incluant un champ de schéma de zone nommé main
:
Chaque composant .astro
doit être associé au type de page Apostrophe correspondant dans src/templates/index.js
.
L’exemple ci-dessous ajoute le composant HomePage.astro
précédent à ce fichier :
See the ApostropheCMS documentation for template naming conventions, including special pages and piece page types.
The project directory should now look like this:
Répertoiresrc/
- …
Répertoirewidgets/
- …
- index.js
- ImageWidget.astro
- RichTextWidget.astro
Répertoiretemplates/
- …
- HomePage.astro
- index.js
- .env
- astro.config.mjs
- package.json
Création du composant […slug.astro] et récupération des données d’Apostrophe
Titre de la section Création du composant […slug.astro] et récupération des données d’ApostrophePuisque Apostrophe est responsable de la connexion des URLs au contenu, y compris la création de nouveaux contenus et pages à la volée, vous n’aurez besoin que d’un composant de page Astro de premier niveau : la route [...slug].astro
.
L’exemple suivant montre un composant [...slug].astro
minimal :
Voir la documentation d’ApostropheCMS pour des options de modélisation supplémentaires, y compris les emplacements disponibles dans le composant AposTemplate
.
Créer un blog avec Astro et ApostropheCMS
Titre de la section Créer un blog avec Astro et ApostropheCMSAvec l’intégration mise en place, vous pouvez maintenant créer un blog avec Astro et ApostropheCMS. Votre blog utilisera une pièce d’Apostrophe, un type de contenu autonome qui peut être inclus dans n’importe quelle page, et un type de page de pièce, un type de page spécialisé qui est utilisé pour afficher ces pièces individuellement ou collectivement.
Prérequis
Titre de la section Prérequis- Un projet ApostropheCMS avec l’outil CLI d’Apostrophe installée - Vous pouvez créer un nouveau projet ou utiliser un projet existant. Cependant, ce tutoriel ne montrera que la création d’un article de blog et d’un type de page d’article. Vous devrez intégrer le code de tout autre projet existant de manière indépendante. Si vous n’avez pas installé l’outil CLI, vous pouvez obtenir les instructions d’installation ici.
- Un projet Astro intégré à ApostropheCMS - Pour créer un projet à partir de zéro, voir integrating with Astro pour les instructions sur la façon de configurer l’intégration, ou utiliser le projet de démarrage astro-frontend.
Création d’un article de blog et d’un type de page d’article
Titre de la section Création d’un article de blog et d’un type de page d’articlePour créer votre pièce de blog et votre type de page de pièce pour leur affichage, naviguez vers la racine de votre projet ApostropheCMS dans votre terminal. Utilisez l’outil CLI d’ApostropheCMS pour créer le nouveau morceau et le nouveau type de page du morceau à l’aide de la commande suivante :
Cela créera deux nouveaux modules dans votre projet, un pour le type de pièce du blog et un pour le type de page de la pièce correspondante. Ensuite, ouvrez le fichier app.js
à la racine de votre projet ApostropheCMS dans votre éditeur de code et ajoutez vos nouveaux modules.
Le module blog-page
doit également être ajouté au tableau d’options types
du module @apostrophecms/page
afin qu’il puisse être sélectionné dans la modale de création de page. Dans votre projet ApostropheCMS, ouvrez le fichier modules/@apostrophecms/page/index.js
et ajoutez le module blog-page
.
Création du schéma du blog
Titre de la section Création du schéma du blogDans un projet ApostropheCMS, les éditeurs disposent d’un ensemble de champs de saisie pour ajouter du contenu. Voici un exemple de billet de blog simple qui ajoute trois champs de saisie, un authorName
, un publicationDate
et une zone de content
où les gestionnaires de contenu peuvent ajouter plusieurs instances de widgets. Dans ce cas, nous spécifions qu’ils peuvent ajouter les widgets image et texte riche que nous avons créés pendant la configuration de l’intégration.
À ce stade, tous les composants provenant du projet ApostropheCMS sont installés. Démarrez le site local à partir de la ligne de commande en utilisant npm run dev
, en vous assurant de passer la variable d’environnement APOS_EXTERNAL_FRONT_KEY
à votre chaîne de caractères sélectionnée :
Affichage des articles de blog
Titre de la section Affichage des articles de blogPour afficher une page avec tous les articles du blog, créez un fichier composant BlogIndex.astro
dans le répertoire src/templates
de votre projet Astro et ajoutez le code suivant :
Après avoir récupéré les données de la page et des articles dans le props aposData
, ce composant crée des balises en utilisant les deux champs du schéma de l’article de blog que nous avons créé, mais aussi les piece.title
et piece._url
qui sont ajoutés à chaque article par Apostrophe.
Pour afficher des articles de blog individuels, créez un fichier BlogShow.astro
dans le dossier src/templates
du projet Astro avec le code suivant :
Ce composant utilise le composant <AposArea>
pour afficher tous les widgets ajoutés à la zone content
et le contenu authorName
et publicationDate
saisi dans les champs du même nom.
Enfin, ces composants Astro doivent être mappés aux types de pages ApostropheCMS correspondants. Ouvrez le fichier src/templates/index.js
du projet Astro et modifiez-le pour qu’il contienne le code suivant :
Créer des articles de blog
Titre de la section Créer des articles de blogPour ajouter des articles de blog à votre site, vous devez utiliser les outils de gestion et de contenu d’ApostropheCMS pour créer ces articles et publier au moins une page d’index pour les afficher.
Lorsque le serveur Astro dev est en cours d’exécution, accédez à la page de connexion située à l’adresse http://localhost:4321/login dans l’aperçu de votre navigateur. Utilisez les identifiants qui ont été ajoutés lors de la création du projet ApostropheCMS pour vous connecter en tant qu’administrateur. Votre projet ApostropheCMS doit toujours être en cours d’exécution.
Une fois connecté, votre navigateur sera redirigé vers la page d’accueil de votre projet et affichera une barre d’administration en haut pour éditer le contenu et gérer votre projet.
Pour ajouter votre premier article de blog, cliquez sur le bouton Blogs
dans la barre d’administration pour ouvrir la fenêtre de création d’un article de blog. En cliquant sur le bouton New Blog
en haut à droite, vous ouvrirez une fenêtre d’édition dans laquelle vous pourrez ajouter du contenu. Le champ content
vous permettra d’ajouter autant d’images et de textes enrichis que vous le souhaitez.
Vous pouvez répéter cette étape et ajouter autant de messages que vous le souhaitez. Vous suivrez également ces étapes chaque fois que vous voudrez ajouter un nouveau message.
Pour publier une page pour afficher tous vos messages, cliquez sur le bouton Pages
dans la barre d’administration. Dans la fenêtre de l’arbre des pages, cliquez sur le bouton “Nouvelle page”. Dans le menu déroulant Type
dans la colonne de droite, sélectionnez Blog
. Ajoutez un titre à la page et cliquez sur Publish and View
. Vous n’aurez à le faire qu’une seule fois.
Tout nouvel article de blog créé sera automatiquement affiché sur cette page. Les articles de blog individuels peuvent être affichés en cliquant sur le lien créé sur la page d’index.
Le content
des articles individuels peut être modifié directement sur la page en naviguant jusqu’à l’article et en cliquant sur edit
dans la barre d’administration. D’autres champs peuvent être édités en utilisant la modale d’édition ouverte en cliquant sur l’élément de menu Blogs
dans la barre d’administration.
Déployer votre site
Titre de la section Déployer votre sitePour déployer votre site, vous devez héberger vos projets Astro et ApostropheCMS.
Pour Astro, visitez nos guides de déploiement et suivez les instructions de votre fournisseur d’hébergement préféré.
Pour le projet ApostropheCMS, suivez les instructions pour votre type d’hébergement dans notre guide d’hébergement. Enfin, vous devrez fournir une variable d’environnement APOS_HOST
au projet Astro pour refléter l’URL correcte où votre site ApostropheCMS a été déployé.
Ressources officielles
Titre de la section Ressources officielles- Astro integration for ApostropheCMS - Plugin Astro d’ApostropheCMS, guide d’intégration et projets de démarrage pour Apostrophe et Astro.
- Exemple de projet Astro à utiliser avec ApostropheCMS - Un projet Astro simple avec plusieurs pages et des widgets Apostrophe déjà créés.
- Exemple de kit de démarrage ApostropheCMS à utiliser avec Astro - Un projet ApostropheCMS avec des modifications de pages de base pour une utilisation avec Astro.
Ressources communautaires
Titre de la section Ressources communautaires- Intégrer ApostropheCMS avec Astro, Pt. 1 par Antonello Zaini
- Intégration d’ApostropheCMS avec Astro, Partie 2 par Antonello Zaini
- Show & Tell Live | Astro & Apostrophe