stacy
v2.0.0
Stacy est un générateur de sites Web qui combine le contenu de Contentful CMS avec des modèles de guidon pour créer les pages du site Web.
Stacy fait correspondre les types de contenu d'entrée de Contentful avec les modèles de guidon dans votre projet de site Web dans une relation un-à-un : il existe un modèle pour chaque type d'entrée défini dans votre modèle de contenu . Il existe deux types d'entrées du point de vue de Stacy : les entrées de page et les entrées de module . Une entrée de page combinée à son modèle produit une seule page de site Web à une URL unique. Les entrées de module peuvent être incluses dans des pages et d'autres modules à l'aide des champs de référence de Contentful pour créer des éléments de contenu réutilisables ou simplement pour fournir une structure de contenu et de modèles en le divisant en éléments plus petits.
Ce qui différencie Stacy de nombreux générateurs de sites Web statiques existants, c'est qu'il prend en charge la publication automatique du site Web dans un compartiment S3 dans Amazon Cloud, à partir duquel il peut être servi sur Internet. Stacy déploie une infrastructure spéciale dans Amazon Cloud qui peut être connectée à Contentful via sa fonctionnalité Webhooks. Lorsque le contenu est mis à jour dans votre espace Contentful, l'infrastructure de votre site Web déployée par Stacy dans Amazon Cloud est avertie et régénère et republie automatiquement uniquement les pages de votre site Web affectées par la mise à jour. Aucune régénération et redéploiement manuels du site Web n’est requis.
Lorsque vous utilisez Stacy, votre site Web est un projet NPM généralement enregistré dans un référentiel git pour le contrôle de version. Le projet comprend vos modèles guidons et votre contenu statique (tel que les feuilles de style CSS, les images utilisées dans la conception du site Web, les polices, etc.), tandis que le contenu du site Web réside dans l'espace Contentful. À partir du projet de site Web, les développeurs du site Web utilisent l'outil de ligne de commande Stacy pour développer, publier et republier le site. Une fois le site Web publié dans Amazon Cloud, les auteurs de contenu travaillent uniquement avec Contentful UI.
Voir Création d'un site Web avec Stacy pour un didacticiel/procédure détaillée.
Tout d'abord, vous avez besoin d'un espace Contentful pour le contenu de votre site Web. Une fois que vous avez cela, vous pouvez créer un nouveau projet pour votre site Web.
Assurez-vous que Node.js version 10.16.3 ou plus récente est installée avec npm. Si vous envisagez de publier le site Web dans Amazon Cloud, vous devrez également installer AWS CLI.
Commencez par installer Stacy globalement :
npm install -g stacy
Dans votre espace Contentful, accédez à Paramètres de l'espace → Clés API et ajoutez une clé API dans Jetons de diffusion/aperçu de contenu . Notez les valeurs des jetons d’accès Space ID et Content Delivery API que vous utiliserez pour connecter votre environnement Stacy à votre espace Contentful.
Maintenant, vous pouvez générer un projet initial pour votre site Web :
stacy new --cf-space <your space ID> --cf-access-token <your access token> mywebsite
Cela créera un nouveau répertoire de projet nommé « monsiteweb » dans le répertoire actuel. La valeur "mywebsite" est connue sous le nom d'ID du site . Utilisez une valeur différente qui identifie votre site Web. La valeur doit être adaptée aux URL (lettres minuscules, chiffres et tirets).
Dans le répertoire de votre projet, placez le contenu statique sous /static (il est copié tel quel sur votre site Web) et placez vos modèles d'entrée sous /templates . Le nom du fichier modèle (sans l'extension) doit correspondre exactement au type de contenu d'entrée correspondant dans votre modèle Contentful Content . Sous /templates , les fichiers modèles peuvent être organisés en sous-dossiers. Cependant, les noms de fichiers doivent être uniques dans tous les sous-dossiers, car ils sont utilisés pour faire correspondre de manière unique les modèles aux types de contenu d'entrée (les sous-dossiers dans /templates ne jouent aucun rôle).
Remarque : Normalement, un modèle, combiné au contenu d'une entrée, produit du HTML. Si vous devez produire un autre type de contenu, vous pouvez ajouter une extension au nom du modèle. Par exemple, page.hbs produit du HTML. Pour produire du texte brut, utilisez page.txt.hbs . Cela signifie également que page.hbs et page.html.hbs sont identiques.
Vous pouvez désormais exécuter votre site Web localement à des fins de développement :
stacy serve
Vous pouvez voir votre site Web à http://localhost:8080/ . Après avoir modifié un modèle, du contenu statique ou du contenu dans Contentful, rechargez simplement la page.
Pour arrêter le serveur Web local de Stacy, utilisez Ctrl+C .
Exécutez stacy --help pour voir les autres commandes disponibles.
Le contenu du répertoire de votre projet, vous pouvez l'archiver dans un référentiel git tel que GitHub ou Bitbucket.
Dans vos modèles, tous les champs de saisie sont disponibles par ID de champ tel que défini dans votre modèle de contenu . Vous pouvez les référencer directement dans votre modèle. Par exemple:
Cela affichera la valeur du champ caption de l'entrée. Notez que c'est Field ID qui est utilisé ici et non le champ Name .
Stacy ajoute quelques aides spéciales que vous pouvez utiliser dans vos modèles :
module <reference field> - Inclut l'entrée de module référencée par le champ Type de référence. Par exemple, étant donné que vous avez un champ avec paragraphs d'ID et qu'il s'agit d'une liste de références :
asset <asset field> - Inclut l'actif référencé, une telle image. Par exemple:
Actuellement, seules les ressources image sont prises en charge, pour lesquelles une balise HTML <img> est rendue.
assetSrc <asset field> - Obtenez l'URL de l'actif. Par exemple:
assetTitle <asset field> - Obtenez le titre de l'actif. Par exemple:
markdown <long text field> - Rendu le champ de texte long Markdown. Par exemple:
Notez les triples accolades nécessaires ici car l'assistant génère du HTML qui n'a pas besoin d'être échappé.
richText <rich text field> - Afficher le champ de texte enrichi. Par exemple:
Comme pour markdown , notez les triples accolades.
json <field> - Sortie d'une représentation JSON Contentful interne du champ. Par exemple:
Cette aide peut être utile pour diagnostiquer des problèmes.
Comme mentionné ci-dessus, il existe une relation un-à-un entre les types de contenu que vous définissez dans le modèle de contenu et les modèles de votre espace Contentful.
Remarque : À proprement parler, vous pouvez avoir plusieurs modèles pour un type de contenu donné afin de permettre la génération de différents types de fichiers pour la même entrée de contenu. Par exemple, pour module ID de type de contenu, vous pouvez avoir des modèles module.html.hbs et module.xml.hbs . Le premier modèle produira un fichier HTML pour l'entrée et le second produira un fichier XML.
Lorsque vous définissez un type de contenu, notez l' identifiant Api (également appelé ID de type de contenu ). Le fichier modèle pour le type de contenu devra avoir le même nom (plus l'extension).
Il existe une exigence concernant les types de contenu pour les entrées de page (par opposition aux entrées de module) : un type de contenu de page doit définir un champ slug obligatoire. La valeur dans le champ déterminera le nom du fichier généré lorsque l'entrée de contenu sera combinée avec le modèle correspondant. Par exemple, si la valeur du slug pour une entrée de page est « index », la page générée sera « /index.html ». Si le slug est "more/terms", la page sera "/more/terms.html". Et ainsi de suite.
Par défaut, l'ID du champ slug doit être slug . L'ID peut être remplacé dans le fichier stacy.json du projet. En plus de rendre le champ slug obligatoire dans la définition du type de contenu, il est également recommandé de lui associer un validateur de modèle de correspondance personnalisé pour garantir le format spécifique de la valeur du champ. L'expression régulière du validateur peut être ^w[w-]*(/w[w-]*)*$ .
Lorsque vous êtes prêt à déployer votre site Web dans AWS, vous devez d'abord configurer l'infrastructure Stacy sous votre compte AWS. Vous devez effectuer plusieurs étapes avant de pouvoir le faire :
Créez le compartiment S3 cible. C'est ici que votre site Web sera publié et d'où il sera servi (probablement via CloudFront). Vous pouvez également utiliser un compartiment que vous possédez déjà (Stacy prend également en charge la publication dans un sous-dossier du compartiment cible).
Si vous ne l'avez pas encore, créez un compartiment S3 que Stacy utilisera pour télécharger le package de fonctions Lambda de l'éditeur. La fonction Lambda de l'éditeur est l'élément qui répond aux événements de publication et de dépublication Contentful et met à jour les pages et les actifs pertinents dans le compartiment S3 cible.
Créez le package d'éditeur :
stacy build-publisher
Cela créera le package de fonctions Publisher Lambda dans votre projet sous /build/stacy-mywebsite-publisher.zip . Téléchargez ce fichier dans votre compartiment S3 de fonctions Lambda.
stacy new de Stacy a généré un modèle CloudFormation pour l'environnement AWS et l'a enregistré dans votre projet sous /misc/cfn-template.json . Vous pouvez le consulter et le personnaliser si nécessaire. Sinon, allez-y et créez une pile Stacy pour votre site Web sous votre compte AWS.
Une fois la pile CloudFormation créée, vous devez ajuster la politique du compartiment S3 cible pour permettre à l'éditeur Stacy d'y publier le contenu du site Web généré. La stratégie du compartiment peut inclure quelque chose comme ce qui suit :
{
"Version" : " 2012-10-17 " ,
"Statement" : [
{
"Effect" : " Allow " ,
"Principal" : {
"AWS" : " <Stacy publisher role ARN> "
},
"Action" : [
" s3:PutObject " ,
" s3:DeleteObject "
],
"Resource" : " arn:aws:s3:::<bucket name>/* "
}
]
} Dans la stratégie ci-dessus, remplacez l'ARN du rôle d'éditeur Stacy par la valeur que vous pouvez trouver dans le paramètre de sortie PublisherRoleArn de votre pile CloudFormation, et le nom du bucket par le nom du bucket du site Web cible (le bucket auquel la stratégie est appliquée).
Vous devez maintenant préparer votre environnement de développement pour la publication. Ouvrez et modifiez le fichier .env dans votre projet de site Web. Dans celui-ci, définissez toutes les variables AWS_* sur les valeurs correctes. Notez que vous pouvez trouver la valeur de la variable AWS_PUBLISH_EVENT_SOURCE_MAPPING dans le paramètre de sortie PublishEventSourceMappingId de la pile CloudFormation.
Une fois votre fichier .env correctement configuré, vous pouvez publier votre site Web en utilisant :
stacy publish
Une dernière étape de configuration consiste à configurer un webhook dans votre espace Contentful pour appeler Stacy Publisher lors des événements de publication et de dépublication . Dans votre compte AWS, dans le service API Gateway, recherchez l'API créée pour vous par Stacy. Il n'y a qu'une seule méthode POST /publish dans l'étape prod de l'API. Notez son URL d'appel .
Accédez également à la section Clés API et notez la valeur de la clé API créée pour Stacy.
Dans votre espace Contentful, accédez à Paramètres de l'espace → Webhooks et ajoutez un webhook. Mettez l'URL d'invocation de l'API Gatwey dans le champ URL (laissez la méthode POST ). Choisissez ensuite l’option Sélectionner des événements déclencheurs spécifiques dans la section Déclencheurs . Cochez les cases Publier et Annuler la publication dans les lignes Entrée et Actif (4 cases cochées en tout).
Dans la section En-têtes , cliquez sur Ajouter un en-tête secret . Mettez "X-API-Key" dans le champ Clé et dans le champ Valeur , mettez la clé API de la passerelle API.
Une fois que vous avez enregistré ce webhook, la publication et la suppression des entrées et des actifs dans Contentful déclencheront l'éditeur dans la configuration AWS et vous êtes prêt !
