Builder.io & Astro

Builder.io est un CMS visuel qui prend en charge l'édition de contenu par glisser-déposer pour la construction de sites Web.

Cette recette vous montrera comment connecter votre espace Builder à Astro avec zéro JavaScript côté client.

Prérequis

Pour commencer, vous devez disposer des éléments suivants :

Un compte et un espace Builder - Si vous n'avez pas encore de compte, inscrivez-vous gratuitement et créez un nouvel espace. Si vous avez déjà un espace avec Builder, n'hésitez pas à l'utiliser, mais vous devrez modifier le code pour qu'il corresponde au nom du modèle (blogpost) et aux champs de données personnalisées.
Une clé API Builder - Cette clé publique sera utilisée pour récupérer votre contenu depuis Builder. Lire le guide de Builder sur la façon de trouver votre clé.

Configuration des informations d'identification

Pour ajouter votre clé API Builder et votre nom de modèle Builder à Astro, créez un fichier .env à la racine de votre projet (s'il n'existe pas déjà) et ajoutez les variables suivantes :

BUILDER_API_PUBLIC_KEY=VOTRE_CLE_API
BUILDER_BLOGPOST_MODEL='blogpost'

Maintenant, vous devriez pouvoir utiliser cette clé API dans votre projet.

:::noteAu moment de la rédaction, cette clé est publique, vous n'avez donc pas à vous soucier de la cacher ou de la chiffrer.:::

Si vous voulez avoir IntelliSense pour vos variables d'environnement, vous pouvez créer un fichier env.d.ts dans le répertoire src/ et configurer ImportMetaEnv comme ceci :

interface ImportMetaEnv {
  readonly BUILDER_API_PUBLIC_KEY: string;
}

Votre projet doit maintenant inclure ces fichiers :

Répertoiresrc/
- env.d.ts
.env
astro.config.mjs
package.json

Apprenez-en plus sur les variables d'environnement et les fichiers .env dans Astro.

Créer un blog avec Astro et Builder

Création d'un modèle pour un article de blog

Les instructions ci-dessous créent un blog Astro en utilisant un modèle Builder (Type : "Section") appelé blogpost qui contient deux champs texte obligatoires : title et slug.

:::tip[Pour les types visuels]Vous pouvez trouver des vidéos montrant cette procédure dans l'un des tutoriels officiels de Builder.:::

Dans l'application Builder, créez le modèle qui représentera un article de blog : allez dans l'onglet Models et cliquez sur le bouton + Create Model pour créer un modèle avec les champs et valeurs suivants :

Type: Section
Name: « blogpost »
Description: « Ce modèle est destiné à un article de blog »

Dans votre nouveau modèle, utilisez le bouton + New Custom Field pour créer deux nouveaux champs :

Champ texte
- Name: « title »
- Required: Yes
- Default value « J'ai oublié de donner un titre à ce champ »
(laisser les autres paramètres par défaut)
Champ texte
- Name: « slug »
- Required: Yes
- Default value « certaines-limaces-prennent-leur-temps »
(laisser les autres paramètres par défaut)

Cliquez ensuite sur le bouton Save en haut à droite.

:::caution[Slugs]Il y a quelques pièges avec le champ slug :

Assurez-vous que votre mot-clé n'est pas un simple nombre. Cela semble interrompre la requête de récupération à l'API de Builder.
Assurez vous que vos slugs sont uniques, car le routage de votre site dépendra de cela.:::

Mise en place de la prévisualisation

Pour utiliser l'éditeur visuel de Builder, créez la page src/pages/builder-preview.astro qui générera le composant spécial <builder-component> :

Répertoiresrc/
- Répertoirepages/
  - builder-preview.astro
- env.d.ts
.env
astro.config.mjs
package.json

Ajoutez ensuite le contenu suivant :

---
const builderAPIpublicKey = import.meta.env.BUILDER_API_PUBLIC_KEY;
const builderModel = import.meta.env.BUILDER_BLOGPOST_MODEL;
---

<html lang="fr">
  <head>
    <title>Aperçu pour builder.io</title>
  </head>
  <body>
    <header>Ceci est votre header</header>

    <builder-component model={builderModel} api-key={builderAPIpublicKey}
    ></builder-component>
    <script async src="https://cdn.builder.io/js/webcomponents"></script>

    <footer>Ceci est votre footer</footer>
  </body>
</html>

Dans l'exemple ci-dessus, <builder-component> indique à Builder où insérer le contenu de son CMS.

Définir la nouvelle route comme URL de prévisualisation

Copiez l'URL complète de votre aperçu, y compris le protocole, dans votre presse-papiers (par exemple https://{votre_hôte}/builder-preview).
Allez dans l'onglet Models de votre espace Builder, sélectionnez le modèle que vous avez créé et collez l'URL de l'étape 1 dans le champ Preview URL. Assurez-vous que l'URL est complète et inclut le protocole, par exemple https://.
Cliquez sur le bouton Save en haut à droite.

:::tipLorsque vous déployez votre site, modifiez l'URL de prévisualisation pour qu'elle corresponde à l'URL de production, par exemple https://myAwesomeAstroBlog.com/builder-preview.:::

Test de la configuration de l'URL de prévisualisation

Assurez-vous que votre site est actif (c'est-à-dire que votre serveur de développement fonctionne) et que la route /builder-preview fonctionne.
Dans votre espace Builder, sous l'onglet Content, cliquez sur New pour créer une nouvelle entrée de contenu pour votre modèle blogpost.
Dans l'éditeur Builder qui vient de s'ouvrir, vous devriez pouvoir voir la page builder-preview.astro avec un gros Add Block au milieu.

:::tip[Dépannage]

Les choses peuvent parfois mal tourner lors de la mise en place de la prévisualisation. Si quelque chose ne va pas, vous pouvez essayer l'une des choses suivantes :

Assurez-vous que le site est en ligne - par exemple, votre serveur de développement est en cours d'exécution.
Assurez-vous que les URL correspondent exactement - celle de votre projet Astro et celle définie dans l'application Builder.
Assurez-vous qu'il s'agit de l'URL complète, y compris le protocole, par exemple https://.
Si vous travaillez dans un environnement virtuel comme StackBlitz, vous devrez peut-être copier et coller l'URL à nouveau lorsque vous redémarrez votre espace de travail, car cela génère généralement une nouvelle URL pour votre projet.

Pour plus d'informations, consultez le guide de dépannage de Builder.:::

Création d'un article de blog

Dans l'éditeur visuel de Builder, créez une nouvelle entrée de contenu avec les valeurs suivantes :
- title: 'Premier article, woohoo !
- slug: 'premier-article-woohoo'
Complétez votre article à l'aide du bouton Add Block et ajoutez un champ de texte avec le contenu de l'article.
Dans le champ de texte situé au-dessus de l'éditeur, donnez un nom à votre article. C'est ainsi qu'il sera listé dans l'application Builder.
Lorsque vous êtes prêt, cliquez sur le bouton Publish dans le coin supérieur droit.
Créez autant d'articles que vous le souhaitez en vous assurant que toutes les entrées de contenu contiennent un titre et un slug ainsi que le contenu de l'article.

Affichage d'une liste d'articles de blog

Ajoutez le contenu suivant à src/pages/index.astro afin de récupérer et d'afficher une liste de tous les titres d'articles, chacun renvoyant à sa propre page :

---

const builderAPIpublicKey = import.meta.env.BUILDER_API_PUBLIC_KEY;
const builderModel = import.meta.env.BUILDER_BLOGPOST_MODEL;

const { results: posts } = await fetch(
  `https://cdn.builder.io/api/v3/content/${builderModel}?${new URLSearchParams({
    apiKey: builderAPIpublicKey,
    fields: ["data.slug", "data.title"].join(","),
    cachebust: "true",
  }).toString()}`
)
  .then((res) => res.json())
  .catch();
---

<html lang="fr">
  <head>
    <title>Index du Blog</title>
  </head>
  <body>
    <ul>
      {
        posts.flatMap(({ data: { slug, title } }) => (
          <li>
            <a href={`/posts/${slug}`}>{title}</a>
          </li>
        ))
      }
    </ul>
  </body>
</html>

La récupération via l'API de contenu renvoie un tableau d'objets contenant les données de chaque article. Le paramètre de requête fields indique à Builder quelles données sont incluses (voir le code surligné). Les paramètres slug et title doivent correspondre aux noms des champs de données personnalisés que vous avez ajoutés à votre modèle Builder.

Le tableau posts retourné par la recherche affiche une liste de titres d'articles de blog sur la page d'accueil. Les routes des pages individuelles seront créées dans l'étape suivante.

:::tip[Intégrations de frameworks]Si vous utilisez un framework JavaScript (par exemple Svelte, Vue ou React) dans votre projet Astro, vous pouvez utiliser l'une des intégrations de Builder au lieu de faire des appels de récupération bruts via l'API REST.:::

Allez sur votre route d'index et vous devriez pouvoir voir une liste de liens, chacun avec le titre d'un article de blog !

Affichage d'un seul article de blog

Créez la page src/pages/posts/[slug].astro qui générera dynamiquement une page pour chaque article.

Répertoiresrc/
- Répertoirepages/
  - index.astro
  - Répertoireposts/
    [slug].astro
- env.d.ts
.env
astro.config.mjs
package.json

Ce fichier doit contenir :

Une fonction getStaticPaths() pour récupérer les informations slug de Builder et créer une route statique pour chaque article de blog.
Un fetch() vers l'API de Builder utilisant l'identifiant slug pour retourner le contenu de l'article et les métadonnées (par exemple un title).
Un <Fragment /> dans le modèle pour générer le contenu de l'article en HTML.

Chacun de ces éléments est mis en évidence dans l'extrait de code suivant.

---
export async function getStaticPaths() {
  const builderModel = import.meta.env.BUILDER_BLOGPOST_MODEL;
  const builderAPIpublicKey = import.meta.env.BUILDER_API_PUBLIC_KEY;
  const { results: posts } = await fetch(
    `https://cdn.builder.io/api/v3/content/${builderModel}?${new URLSearchParams(
      {
        apiKey: builderAPIpublicKey,
        fields: ["data.slug", "data.title"].join(","),
        cachebust: "true",
      }
    ).toString()}`
  )
    .then((res) => res.json())
    .catch
    // ...détecter quelques erreurs...);
    ();
  return posts.map(({ data: { slug, title } }) => ({
    params: { slug },
    props: { title },
  }))
}
const { slug } = Astro.params;
const { title } = Astro.props;
const builderModel = import.meta.env.BUILDER_BLOGPOST_MODEL;
const builderAPIpublicKey = import.meta.env.BUILDER_API_PUBLIC_KEY;
// L'API de Builder requiert ce champ, mais pour ce cas d'utilisation, l'URL ne semble pas avoir d'importance - l'API renvoie le même HTML.
const encodedUrl = encodeURIComponent("moot");
const { html: postHTML } = await fetch(
  `https://cdn.builder.io/api/v1/qwik/${builderModel}?${new URLSearchParams({
    apiKey: builderAPIpublicKey,
    url: encodedUrl,
    "query.data.slug": slug,
    cachebust: "true",
  }).toString()}`
)
  .then((res) => res.json())
  .catch();
---
<html lang="fr">
  <head>
    <title>{title}</title>
  </head>
  <body>
    <header>Ceci est votre header</header>
    <article>
      <Fragment set:html={postHTML} />
    </article>
    <footer>Voici votre pied de page</footer>
  </body>
</html>

:::noteLes variables builderModel et builderAPIpublicKey doivent être créées deux fois, puisque getStaticPaths() s'exécute dans sa propre portée isolée.:::

Désormais, lorsque vous cliquez sur un lien de votre route d'indexation, vous êtes redirigé vers la page de l'article de blog concerné.

Publier votre site

Pour déployer votre site web, visitez nos guides de déploiement et suivez les instructions de votre hébergeur préféré.

Recompiler suite à des changements sur Builder

Si votre projet utilise le mode statique par défaut d'Astro, vous devrez configurer un webhook pour déclencher une nouvelle compilation lorsque votre contenu change. Si vous utilisez Netlify ou Vercel comme fournisseur d'hébergement, vous pouvez utiliser sa fonctionnalité webhook pour déclencher une nouvelle compilation chaque fois que vous cliquez sur Publish dans l'éditeur Builder.

Netlify

Allez dans le tableau de bord de votre site, puis Site Settings et cliquez sur Build & deploy.
Sous l'onglet Continuous Deployment, trouvez la section Build hooks et cliquez sur Add build hook.
Donnez un nom à votre webhook et sélectionnez la branche sur laquelle vous souhaitez déclencher la compilation. Cliquez sur Save et copiez l'URL générée.

Vercel

Allez sur le tableau de bord de votre projet et cliquez sur Settings.
Sous l'onglet Git, trouvez la section Deploy Hooks.
Donnez un nom à votre webhook et indiquez la branche sur laquelle vous souhaitez déclencher la compilation. Cliquez sur Add et copiez l'URL générée.

Ajouter un webhook à Builder

:::tip[Ressource officielle]Consultez le guide de Builder sur l'ajout de webhooks pour plus d'informations.:::

Dans votre tableau de bord Builder, allez dans votre modèle blogpost. Sous Show More Options, sélectionnez Edit Webhooks en bas.
Ajoutez un nouveau webhook en cliquant sur Webhook. Collez l'URL générée par votre hébergeur dans le champ Url.
Cliquez sur Show Advanced sous le champ URL et basculez l'option pour sélectionner Disable Payload. Lorsque la charge utile est désactivée, Builder envoie une requête POST plus simple à votre hébergeur, ce qui peut s'avérer utile au fur et à mesure de la croissance de votre site. Cliquez sur Done pour enregistrer cette sélection.

Avec ce webhook en place, chaque fois que vous cliquez sur le bouton Publish dans l'éditeur de Builder, votre hébergeur reconstruit votre site - et Astro récupère les données nouvellement publiées pour vous. Il ne vous reste plus qu'à vous détendre et à publier votre contenu !

Ressources officielles

Consultez le projet de démarrage officiel de Builder.io, qui utilise Astro et SolidJS.
Le guide officiel de démarrage rapide de Builder couvre à la fois l'utilisation de l'API REST et la récupération de données par le biais d'une intégration avec un framework JavaScript comme Qwik, React ou Vue.
L'explorateur d'API de Builder peut vous aider à résoudre les problèmes liés à vos appels d'API.