Astro per sviluppatori WordPress | EmDash CMS Everything

Astro fornisce le pagine, i layout, i componenti e il rendering lato server per un sito EmDash. Questa guida copre i concetti di Astro utilizzati dagli attuali template EmDash. Si presuppone che tu abbia già familiarità con i temi WordPress e i template PHP.

Per le funzionalità del framework che non sono specifiche di EmDash, usa la documentazione Astro.

Struttura del progetto

Un sito Astro assegna a ogni tipo di file una directory esplicita. Gli attuali template EmDash utilizzano questa struttura:

WordPress	Astro	Scopo
`index.php`, `single.php`, `page.php`	`src/pages/`	Route URL
`template-parts/`	`src/components/`	Markup riutilizzabile
`header.php` e `footer.php`	`src/layouts/`	Strutture di pagina condivise
`style.css`	`src/styles/`	Stili del sito
Configurazione plugin e database	`astro.config.mjs`	Integrazioni e adattatore server
Dati di configurazione del tema	`seed/seed.json`	Collezioni, menu e contenuti di esempio

Il template del blog utilizza directory di route che corrispondono ai suoi URL pubblici:

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

Componenti Astro

Un componente .astro combina TypeScript lato server con un template HTML. Il codice tra i delimitatori --- viene eseguito sul server. Il markup sotto il secondo delimitatore diventa l’HTML di risposta.

Il seguente componente dichiara le props nel suo frontmatter e le renderizza nel suo 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 effettua l’escape dei valori renderizzati con {value}. Le importazioni, le query al database e altre operazioni server appartengono al frontmatter.

Espressioni nei template

I template Astro usano le parentesi graffe dove un template PHP passerebbe a <?php ?>. I pattern più comuni nei template EmDash sono valori, condizioni e mapping di array:

Obiettivo	Sintassi Astro
Stampare un valore	`{post.data.title}`
Renderizzare quando un valore esiste	`{post.data.excerpt && <p>{post.data.excerpt}</p>}`
Scegliere tra due risultati	`{posts.length === 0 ? <p>Nessun articolo ancora.</p> : <PostList />}`
Renderizzare una lista	`{posts.map((post) => <PostCard title={post.data.title} excerpt={post.data.excerpt} href={"/posts/" + post.id} />)}`

L’espressione può usare variabili preparate nel frontmatter, valori da Astro.props o dati restituiti da una query EmDash. Astro effettua l’escape dei valori stringa per impostazione predefinita; usa un renderer come <PortableText /> per testo ricco strutturato invece di iniettare HTML.

Props e slot

Le props sono paragonabili ai $args passati a get_template_part(). Rendono ogni input esplicito e possono essere verificati da TypeScript.

Gli slot permettono a un genitore di passare markup a un componente. Uno slot predefinito è utile per il contenuto della pagina, mentre gli slot con nome forniscono punti di inserimento aggiuntivi:

---
interface Props {
  title: string;
}

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

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

La seguente pagina riempie entrambi gli slot:

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

<Card title="Ultimo articolo">
  <p>Il contenuto principale della scheda.</p>
  <a slot="footer" href="/posts/latest">Leggi l'articolo</a>
</Card>

Gli slot sono locali alla chiamata del componente. Non si comportano come le azioni di WordPress, che possono ricevere callback registrati altrove.

Layout

Un layout possiede la struttura di documento condivisa che un tema WordPress spesso divide tra header.php e footer.php. Le pagine importano il layout e passano il loro contenuto attraverso il suo slot.

Il seguente layout fornisce una struttura di documento:

---
interface Props {
  title: string;
}

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

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

La seguente pagina fornisce il titolo e il contenuto principale del layout:

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

<Base title="Home">
  <h1>Ultimi articoli</h1>
</Base>

Routing basato su file

I file in src/pages/ definiscono le route. I nomi di file tra parentesi quadre creano segmenti dinamici.

File	URL
`src/pages/index.astro`	`/`
`src/pages/posts/index.astro`	`/posts`
`src/pages/posts/[slug].astro`	`/posts/hello-world`
`src/pages/pages/[slug].astro`	`/pages/about`

All’interno di src/pages/posts/[slug].astro, Astro.params.slug contiene il valore dall’URL. Leggi Routing Astro per parametri rest, reindirizzamenti e altre funzionalità di routing.

Rendering lato server

Gli attuali template EmDash usano output: "server" in astro.config.mjs. Una pagina può quindi interrogare il database ad ogni richiesta, cosicché il contenuto pubblicato non dipende da una nuova compilazione statica.

Non aggiungere getStaticPaths() a una route del tema EmDash a meno che il sito non tratti deliberatamente EmDash come una fonte di dati al momento della compilazione. I temi forniti sono renderizzati lato server.

Leggi Rendering on-demand Astro per il comportamento a livello di framework.

Interrogare i contenuti EmDash

EmDash avvolge le collezioni di contenuti live di Astro con getEmDashCollection() e getEmDashEntry(). I risultati delle collezioni contengono un array entries. I risultati di una singola voce contengono entry, che è null quando nessuna voce pubblicata corrisponde.

Il seguente archivio usa lo stesso ordinamento e identificatori del template blog attuale:

---
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("Impossibile caricare gli articoli", { status: 500 });
}
---

<Base title="Articoli">
  {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 è l’identificatore di route esposto da Astro e normalmente è lo slug della voce. post.data.id è l’identificatore del database. Usa data.id quando un’API si aspetta l’ID del contenuto memorizzato, come le funzioni di supporto per la tassonomia o i commenti.

La seguente route dinamica cerca un articolo tramite lo slug nell’URL e renderizza il suo campo 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.redirect("/404");

const { entry: post, error } = await getEmDashEntry("posts", slug);
if (error) return new Response("Impossibile caricare l'articolo", { status: 500 });
if (!post) return Astro.redirect("/404");
---

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

Continuare con Astro

I template EmDash usano anche stili dei componenti e piccoli script del browser, ma queste sono funzionalità Astro ordinarie piuttosto che concetti EmDash. Leggi Stili e CSS per stili con scope e globali, e Script e gestione degli eventi quando un componente ha bisogno di comportamento lato browser.