Taxonomies

Une taxonomie est une classification nommée appliquée à une ou plusieurs collections. EmDash démarre avec la taxonomie hiérarchique category et la taxonomie plate tag pour les posts. Un site peut aussi définir des taxonomies telles que genre, topic ou difficulty.

Les termes appartiennent à une taxonomie. Une catégorie telle que « Guides » peut avoir des catégories enfants, tandis que les tags et les autres taxonomies plates ont un niveau.

Gérer les termes

Ouvrez une taxonomie depuis Taxonomies dans l’administration d’EmDash.

Les éditeurs attribuent des termes depuis les panneaux de taxonomie d’une entrée de contenu. La définition de la taxonomie détermine dans quelles collections chaque panneau s’affiche.

Supprimer un terme retire ses attributions du contenu. Cela ne supprime pas les entrées de contenu.

Ajouter un terme à plusieurs posts

Les éditeurs peuvent sélectionner des posts dans une liste de collection et cliquer sur Add suivi du nom singulier de la taxonomie (par exemple, Add tag), ou ouvrir la page d’une taxonomie et cliquer sur Add to posts pour coller des URL publiques de posts (une par ligne, jusqu’à 50). Lorsque plusieurs taxonomies s’appliquent à la collection, la liste affiche Add term et la boîte de dialogue demande quelle taxonomie utiliser. Choisissez un terme existant ou créez-en un dans la boîte de dialogue, puis cliquez sur Review posts. Vérifiez chaque titre et chaque langue associés, puis cliquez sur le bouton indiquant combien de posts seront mis à jour. Les liens qui ne correspondent pas exactement à un post publié sur ce site sont signalés plutôt que devinés. Seules les entrées des collections qui utilisent la taxonomie choisie peuvent être associées.

L’ajout du terme prend effet immédiatement, même lorsqu’un post comporte d’autres modifications de brouillon non publiées ; il ne publie pas ces modifications. Les termes existants restent en place, et les posts qui ont déjà le terme sont ignorés. La liste des résultats indique quels posts ont été mis à jour, ignorés ou n’ont pas pu être mis à jour ; utilisez Retry failures pour les échecs d’écriture. La correspondance des URL utilise l’origine publique configurée du site et les modèles d’URL des collections, y compris les chemins de date et de langue.

Ajouter une taxonomie personnalisée

Créez une taxonomie lorsqu’une collection existante a besoin d’une classification distincte.

Les templates interrogent le nom stable. Modifier un libellé affiché n’exige aucun changement de template.

Les taxonomies personnalisées utilisent les mêmes helpers de requête et de filtre que les catégories et les tags. L’exemple suivant lit les termes genre et filtre des livres selon l’un de leurs slugs :

import { getEmDashCollection, getTaxonomyTerms } from "emdash";

const genres = await getTaxonomyTerms("genre", { includeCounts: false });
const { entries: scienceFictionBooks } = await getEmDashCollection("books", {
  where: { genre: "science-fiction" },
});

Supprimer une taxonomie

Ouvrez la taxonomie dans l’administration, puis choisissez Delete taxonomy dans le menu d’actions de l’en-tête de page et confirmez. L’action requiert la permission taxonomies:manage, que détiennent les éditeurs et les administrateurs.

Supprimer une taxonomie supprime ses termes dans toutes les langues et retire ces termes du contenu qui y était classé. Les entrées de contenu elles-mêmes sont conservées.

Interroger une liste de termes

Utilisez getTaxonomyTerms() pour afficher un index de taxonomie, une liste de navigation ou un ensemble de filtres. Les taxonomies hiérarchiques renvoient un arbre via le tableau children de chaque terme.

Les compteurs de termes sont inclus par défaut et nécessitent une agrégation sur les collections attribuées à la taxonomie. Évitez ce travail lorsque le composant n’affiche pas de compteurs.

Le composant suivant affiche des liens de catégories sans compteurs :

---
import { getTaxonomyTerms } from "emdash";
import { getRelativeLocaleUrl } from "astro:i18n";

const locale = Astro.currentLocale;
const categories = await getTaxonomyTerms("category", {
  locale,
  includeCounts: false,
});

function categoryHref(slug: string) {
  const path = `/category/${slug}`;
  return locale ? getRelativeLocaleUrl(locale, path) : path;
}
---

<nav aria-label="Categories">
  <ul>
    {categories.map((category) => (
      <li>
        <a href={categoryHref(category.slug)}>{category.label}</a>
        {category.children.length > 0 && (
          <ul>
            {category.children.map((child) => (
              <li><a href={categoryHref(child.slug)}>{child.label}</a></li>
            ))}
          </ul>
        )}
      </li>
    ))}
  </ul>
</nav>

Lorsqu’un composant affiche l’utilisation, omettez includeCounts: false et affichez term.count. Le compteur inclut les entrées visibles publiquement dans la locale utilisée pour la requête.

Construire une archive de taxonomie

Décodez le paramètre d’une route dynamique avant de rechercher un terme. Interrogez le terme et le contenu avec la même locale, et faites passer les chemins générés par le helper d’URL de locale d’Astro.

La route suivante liste les posts publiés d’une catégorie :

---
import { decodeSlug, getEmDashCollection, getTerm } from "emdash";
import { getRelativeLocaleUrl } from "astro:i18n";
import Base from "../../layouts/Base.astro";

const locale = Astro.currentLocale;
const slug = decodeSlug(Astro.params.slug);
const category = slug
  ? await getTerm("category", slug, { locale, includeCounts: false })
  : null;

if (!category) {
  return Astro.rewrite("/404");
}

const { entries: posts } = await getEmDashCollection("posts", {
  status: "published",
  locale,
  where: { category: category.slug },
  orderBy: { published_at: "desc" },
});

function postHref(postSlug: string) {
  const path = `/posts/${postSlug}`;
  return locale ? getRelativeLocaleUrl(locale, path) : path;
}
---

<Base title={`${category.label} posts`}>
  <h1>{category.label}</h1>
  {category.description && <p>{category.description}</p>}

  {posts.length > 0 ? (
    <ul>
      {posts.map((post) => (
        post.data.slug && (
          <li>
            <a href={postHref(post.data.slug)}>{post.data.title}</a>
          </li>
        )
      ))}
    </ul>
  ) : (
    <p>No posts in this category.</p>
  )}
</Base>

where utilise le nom de la taxonomie comme clé et le slug d’un terme comme valeur. Les identifiants de tri des requêtes utilisent des noms de champs de base de données tels que published_at ; les données de l’entrée exposent la valeur correspondante sous le nom publishedAt.

Utilisez la véritable route publique de la collection dans postHref(). Si la collection utilise un urlPattern personnalisé, construisez les liens à partir de ce modèle plutôt que de supposer /posts/{slug}.

Afficher les termes d’une entrée

getEmDashEntry() et getEmDashCollection() hydratent les termes attribués dans entry.data.terms. Lisez cette valeur plutôt que d’exécuter une requête getEntryTerms() pour chaque entrée d’une liste.

Le composant suivant affiche les catégories et les tags déjà chargés avec un post :

---
import type { ContentEntry, InferCollectionData } from "emdash";
import { getRelativeLocaleUrl } from "astro:i18n";

interface Props {
  post: ContentEntry<InferCollectionData<"posts">>;
}

const { post } = Astro.props;
const locale = Astro.currentLocale;
const categories = post.data.terms?.category ?? [];
const tags = post.data.terms?.tag ?? [];

function termHref(taxonomy: string, slug: string) {
  const path = `/${taxonomy}/${slug}`;
  return locale ? getRelativeLocaleUrl(locale, path) : path;
}
---

{categories.length > 0 && (
  <ul aria-label="Categories">
    {categories.map((category) => (
      <li>
        <a href={termHref("category", category.slug)}>{category.label}</a>
      </li>
    ))}
  </ul>
)}

{tags.length > 0 && (
  <ul aria-label="Tags">
    {tags.map((tag) => (
      <li>
        <a href={termHref("tag", tag.slug)}>{tag.label}</a>
      </li>
    ))}
  </ul>
)}

Utilisez getEntryTerms() lorsque vous n’avez qu’un nom de collection et un ID d’entrée. Utilisez getTermsForEntries() pour récupérer par lots les termes de plusieurs entrées lorsqu’ils n’ont pas été hydratés par la requête de contenu.

Traduire les taxonomies et les termes

Les définitions de taxonomie et les termes ont une ligne par locale. EmDash enregistre quelles lignes sont des traductions de la même taxonomie ou du même terme. Les attributions de contenu utilisent cette identité partagée : une attribution faite dans une locale se résout donc vers le terme traduit dans une autre locale lorsqu’il existe.

Une définition de taxonomie répartit ses champs entre la taxonomie et chaque locale :

Une définition créée pour un nom qui existe déjà dans une autre locale rejoint cette taxonomie, avec ou sans translationOf, et reprend ses hierarchical et collections. La créer avec des valeurs différentes échoue ; modifiez-les avec une mise à jour. Une locale sans définition propre liste toujours les termes de la taxonomie et affiche le libellé de la première locale de sa chaîne de repli qui en a un, sinon le libellé de la locale par défaut, sinon le libellé de la locale dont le code de locale est le plus bas.

Utilisez le sélecteur de locale d’une page de taxonomie pour gérer les termes dans chaque locale configurée. Ouvrez la boîte de dialogue de modification d’un terme et utilisez son panneau Translations pour ajouter ou ouvrir une autre locale. Un terme traduit peut utiliser un slug et un libellé différents.

Le parent et la position d’un terme sont partagés par toutes les locales. Une traduction créée sans parent reprend le parent et la position de son terme. Créer une traduction sous un autre parent, ou changer le parent via n’importe quelle locale, déplace le terme dans toutes les locales.

Les helpers de requête utilisent une locale explicite lorsqu’elle est fournie. Sinon, ils utilisent la locale de la requête en cours, puis la valeur par défaut configurée. Les recherches d’un seul terme suivent la chaîne de repli configurée lorsque la traduction demandée est absente.

Consultez Internationalisation (i18n) pour le routage par locale et la configuration du repli, et Travailler avec le contenu pour la modification des entrées. La Référence de l’API JavaScript documente les helpers de requête de taxonomie. Pour les modifications programmatiques, authentifiez-vous avec un jeton Bearer et ajoutez X-EmDash-Request: 1 à chaque requête qui modifie l’état. Consultez les endpoints de taxonomie pour les corps de requête et les réponses.