Astro pour les développeurs WordPress

Astro fournit les pages, les mises en page, les composants et le rendu serveur d’un site EmDash. Ce guide couvre les concepts d’Astro utilisés par les modèles EmDash actuels. Il suppose que vous comprenez déjà les thèmes WordPress et les templates PHP.

Pour les fonctionnalités du framework qui ne sont pas propres à EmDash, consultez la documentation d’Astro.

Structure du projet

Un site Astro attribue un répertoire explicite à chaque type de fichier. Les modèles EmDash actuels utilisent cette structure :

Le modèle de blog utilise des répertoires de routes qui correspondent à ses URL publiques :

src/
├── components/
│   └── PostCard.astro
├── layouts/
│   └── Base.astro
├── pages/
│   ├── index.astro
│   ├── pages/
│   │   └── [slug].astro
│   └── posts/
│       ├── index.astro
│       └── [slug].astro
└── live.config.ts

Composants Astro

Un composant .astro combine du TypeScript côté serveur et un template HTML. Le code situé entre les délimiteurs --- s’exécute sur le serveur. Le balisage situé sous le second délimiteur devient le HTML de la réponse.

Le composant suivant déclare des props dans son frontmatter et les affiche dans son template :

---
interface Props {
  title: string;
  excerpt?: string;
  href: string;
}

const { title, excerpt, href } = Astro.props;
---

<article>
  <h2><a href={href}>{title}</a></h2>
  {excerpt && <p>{excerpt}</p>}
</article>

Astro échappe les valeurs rendues avec {value}. Les imports, les requêtes de base de données et les autres traitements côté serveur relèvent du frontmatter.

Expressions de template

Les templates Astro utilisent des accolades là où un template PHP passerait en <?php ?>. Les schémas les plus courants dans les templates EmDash sont les valeurs, les conditions et le mappage de tableaux :

L’expression peut utiliser des variables préparées dans le frontmatter, des valeurs de Astro.props ou des données renvoyées par une requête EmDash. Astro échappe les valeurs de type chaîne par défaut ; utilisez un moteur de rendu tel que <PortableText /> pour le texte enrichi structuré plutôt que d’injecter du HTML.

Props et slots

Les props sont comparables aux $args passés à get_template_part(). Elles rendent chaque entrée explicite et peuvent être vérifiées par TypeScript.

Les slots permettent à un parent de passer du balisage à un composant. Un slot par défaut est utile pour le contenu de la page, tandis que les slots nommés offrent des points d’insertion supplémentaires :

---
interface Props {
  title: string;
}

const { title } = Astro.props;
---

<article>
  <h2>{title}</h2>
  <slot />
  <footer><slot name="footer" /></footer>
</article>

La page suivante remplit les deux slots :

---
import Card from "../components/Card.astro";
---

<Card title="Latest post">
  <p>The main card content.</p>
  <a slot="footer" href="/posts/latest">Read the post</a>
</Card>

Les slots sont locaux à l’appel du composant. Ils ne se comportent pas comme les actions WordPress, qui peuvent recevoir des callbacks enregistrés ailleurs.

Layouts

Un layout détient la structure de document partagée qu’un thème WordPress répartit souvent entre header.php et footer.php. Les pages importent le layout et lui transmettent leur contenu via son slot.

Le layout suivant fournit une structure de document :

---
interface Props {
  title: string;
}

const { title } = Astro.props;
---

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <title>{title}</title>
  </head>
  <body>
    <header><a href="/">My site</a></header>
    <main><slot /></main>
  </body>
</html>

La page suivante fournit le titre et le contenu principal du layout :

---
import Base from "../layouts/Base.astro";
---

<Base title="Home">
  <h1>Latest posts</h1>
</Base>

Routage basé sur les fichiers

Les fichiers de src/pages/ définissent les routes. Les noms de fichiers entre crochets créent des segments dynamiques.

Dans src/pages/posts/[slug].astro, Astro.params.slug contient la valeur issue de l’URL. Consultez Le routage dans Astro pour les paramètres rest, les redirections et les autres fonctionnalités de routage.

Rendu serveur

Les modèles EmDash actuels utilisent output: "server" dans astro.config.mjs. Une page peut donc interroger la base de données à chaque requête, de sorte que le contenu publié ne dépend pas d’un nouveau build statique.

N’ajoutez pas getStaticPaths() à la route d’un thème EmDash, sauf si le site traite délibérément EmDash comme une source de données au moment du build. Les thèmes fournis sont rendus côté serveur.

Consultez Le rendu à la demande dans Astro pour le comportement au niveau du framework.

Interroger le contenu EmDash

EmDash enveloppe les collections de contenu en direct d’Astro avec getEmDashCollection() et getEmDashEntry(). Les résultats d’une collection contiennent un tableau entries. Les résultats d’une seule entrée contiennent entry, qui vaut null lorsqu’aucune entrée publiée ne correspond.

L’archive suivante utilise le même tri et les mêmes identifiants que le modèle de blog actuel :

---
import { getEmDashCollection } from "emdash";
import Base from "../../layouts/Base.astro";

const { entries: posts, error } = await getEmDashCollection("posts", {
  orderBy: { published_at: "desc" },
});

if (error) {
  return new Response("Could not load posts", { status: 500 });
}
---

<Base title="Posts">
  {posts.map((post) => (
    <article>
      <h2><a href={`/posts/${post.id}`}>{post.data.title}</a></h2>
      {post.data.excerpt && <p>{post.data.excerpt}</p>}
    </article>
  ))}
</Base>

post.id est l’identifiant de route exposé par Astro et correspond normalement au slug de l’entrée. post.data.id est l’identifiant en base de données. Utilisez data.id lorsqu’une API attend l’ID de contenu stocké, comme pour les helpers de taxonomies ou de commentaires.

La route dynamique suivante recherche un article d’après le slug de l’URL et affiche son champ Portable Text :

---
import { decodeSlug, getEmDashEntry } from "emdash";
import { PortableText } from "emdash/ui";
import Base from "../../layouts/Base.astro";

const slug = decodeSlug(Astro.params.slug);
if (!slug) return Astro.rewrite("/404");

const { entry: post, error } = await getEmDashEntry("posts", slug);
if (error) return new Response("Could not load the post", { status: 500 });
if (!post) return Astro.rewrite("/404");
---

<Base title={post.data.title}>
  <article>
    <h1>{post.data.title}</h1>
    <PortableText value={post.data.content} />
  </article>
</Base>

Continuer avec Astro

Les modèles EmDash utilisent également des styles de composant et de petits scripts navigateur, mais ce sont des fonctionnalités Astro ordinaires et non des concepts d’EmDash. Consultez Styles et CSS pour les styles à portée limitée et globaux, ainsi que Scripts et gestion des événements lorsqu’un composant a besoin d’un comportement côté navigateur.