Taxonomien

Eine Taxonomie ist eine benannte Klassifikation, die auf eine oder mehrere Collections angewendet wird. EmDash startet mit der hierarchischen Taxonomie category und der flachen Taxonomie tag für Posts. Eine Site kann auch Taxonomien wie genre, topic oder difficulty definieren.

Terms gehören zu einer Taxonomie. Eine Kategorie wie „Guides“ kann Kindkategorien haben, während Tags und andere flache Taxonomien eine Ebene haben.

Terms verwalten

Öffnen Sie eine Taxonomie über Taxonomies im EmDash-Admin.

Redakteure weisen Terms über die Taxonomie-Panels in einem Inhaltseintrag zu. Die Taxonomie-Definition steuert, bei welchen Collections jedes Panel angezeigt wird.

Das Löschen eines Terms entfernt seine Zuweisungen aus Inhalten. Die Inhaltseinträge selbst werden nicht gelöscht.

Einen Term zu mehreren Posts hinzufügen

Redakteure können in einer Collection-Liste Posts auswählen und auf Add gefolgt vom Singularnamen der Taxonomie klicken (zum Beispiel Add tag) oder die Seite einer Taxonomie öffnen und auf Add to posts klicken, um öffentliche Post-URLs einzufügen (eine pro Zeile, bis zu 50). Wenn für die Collection mehr als eine Taxonomie gilt, zeigt die Liste Add term, und der Dialog fragt, welche Taxonomie verwendet werden soll. Wählen Sie im Dialog einen vorhandenen Term aus oder erstellen Sie einen, und klicken Sie dann auf Review posts. Prüfen Sie jeden zugeordneten Titel und jede Sprache und klicken Sie dann auf die Schaltfläche, die anzeigt, wie viele Posts aktualisiert werden. Links, die nicht exakt zu einem veröffentlichten Post dieser Site passen, werden markiert, statt geraten zu werden. Nur Einträge in Collections, die die gewählte Taxonomie verwenden, können zugeordnet werden.

Das Hinzufügen des Terms wirkt sofort, auch wenn ein Post weitere unveröffentlichte Entwurfsänderungen hat; diese Änderungen werden dadurch nicht veröffentlicht. Vorhandene Terms bleiben bestehen, und Posts, die den Term bereits haben, werden übersprungen. Die Ergebnisliste zeigt, welche Posts aktualisiert, übersprungen wurden oder nicht aktualisiert werden konnten; verwenden Sie bei Schreibfehlern Retry failures. Die URL-Zuordnung verwendet den konfigurierten öffentlichen Origin der Site und die URL-Muster der Collections, einschließlich Datums- und Sprachpfaden.

Eine benutzerdefinierte Taxonomie hinzufügen

Erstellen Sie eine Taxonomie, wenn eine vorhandene Collection eine separate Klassifikation benötigt.

Templates fragen den stabilen Namen ab. Das Ändern eines Anzeige-Labels erfordert keine Änderung am Template.

Benutzerdefinierte Taxonomien verwenden dieselben Abfrage- und Filter-Helfer wie Kategorien und Tags. Das folgende Beispiel liest die genre-Terms und filtert Bücher nach einem ihrer Slugs:

import { getEmDashCollection, getTaxonomyTerms } from "emdash";

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

Eine Taxonomie löschen

Öffnen Sie die Taxonomie im Admin, wählen Sie dann im Aktionsmenü der Seitenkopfzeile Delete taxonomy und bestätigen Sie. Die Aktion erfordert die Berechtigung taxonomies:manage, die Redakteure und Administratoren besitzen.

Das Löschen einer Taxonomie löscht ihre Terms in jeder Sprache und entfernt diese Terms aus den Inhalten, die ihnen zugeordnet waren. Die Inhaltseinträge selbst bleiben erhalten.

Eine Term-Liste abfragen

Verwenden Sie getTaxonomyTerms(), um einen Taxonomie-Index, eine Navigationsliste oder eine Gruppe von Filtern zu rendern. Hierarchische Taxonomien geben über das children-Array jedes Terms einen Baum zurück.

Term-Zählungen sind standardmäßig enthalten und erfordern eine Aggregation über die der Taxonomie zugewiesenen Collections. Sparen Sie sich diesen Aufwand, wenn die Komponente keine Zählungen anzeigt.

Die folgende Komponente rendert Kategorie-Links ohne Zählungen:

---
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>

Wenn eine Komponente die Nutzung anzeigt, lassen Sie includeCounts: false weg und rendern Sie term.count. Die Zählung umfasst öffentlich sichtbare Einträge in der für die Abfrage verwendeten Locale.

Ein Taxonomie-Archiv bauen

Dekodieren Sie einen dynamischen Routenparameter, bevor Sie einen Term nachschlagen. Fragen Sie Term und Inhalt mit derselben Locale ab und leiten Sie erzeugte Pfade durch Astros Locale-URL-Helfer.

Die folgende Route listet veröffentlichte Posts in einer Kategorie auf:

---
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 verwendet den Taxonomie-Namen als Schlüssel und einen Term-Slug als Wert. Sortierbezeichner in Abfragen verwenden Datenbank-Feldnamen wie published_at; die Eintragsdaten stellen den entsprechenden Wert als publishedAt bereit.

Verwenden Sie in postHref() die tatsächliche öffentliche Route der Collection. Wenn die Collection ein benutzerdefiniertes urlPattern verwendet, bauen Sie die Links aus diesem Muster, statt /posts/{slug} anzunehmen.

Die Terms eines Eintrags anzeigen

getEmDashEntry() und getEmDashCollection() hydrieren zugewiesene Terms in entry.data.terms. Lesen Sie diesen Wert, statt für jeden Eintrag einer Liste eine eigene getEntryTerms()-Abfrage auszuführen.

Die folgende Komponente rendert Kategorien und Tags, die bereits mit einem Post geladen wurden:

---
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>
)}

Verwenden Sie getEntryTerms(), wenn Sie nur einen Collection-Namen und eine Eintrags-ID haben. Verwenden Sie getTermsForEntries(), um die Terms mehrerer Einträge gebündelt abzurufen, wenn sie von der Inhaltsabfrage nicht hydriert wurden.

Taxonomien und Terms übersetzen

Taxonomie-Definitionen und Terms haben pro Locale eine Zeile. EmDash hält fest, welche Zeilen Übersetzungen derselben Taxonomie oder desselben Terms sind. Inhaltszuweisungen verwenden diese gemeinsame Identität, sodass eine in einer Locale vorgenommene Zuweisung in einer anderen Locale zum übersetzten Term aufgelöst wird, sofern einer existiert.

Eine Taxonomie-Definition teilt ihre Felder zwischen der Taxonomie und jeder Locale auf:

Eine Definition, die für einen Namen erstellt wird, der in einer anderen Locale bereits existiert, schließt sich dieser Taxonomie an – mit oder ohne translationOf – und übernimmt deren hierarchical und collections. Ein Erstellen mit abweichenden Werten schlägt fehl; ändern Sie sie mit einem Update. Eine Locale ohne eigene Definition listet weiterhin die Terms der Taxonomie auf und zeigt das Label der ersten Locale in ihrer Fallback-Kette, die eine hat, sonst das Label der Standard-Locale, sonst das Label der Locale mit dem niedrigsten Locale-Code.

Verwenden Sie den Locale-Umschalter auf einer Taxonomie-Seite, um Terms in jeder konfigurierten Locale zu verwalten. Öffnen Sie den Bearbeitungsdialog eines Terms und verwenden Sie dessen Panel Translations, um eine weitere Locale hinzuzufügen oder zu öffnen. Ein übersetzter Term kann einen anderen Slug und ein anderes Label verwenden.

Übergeordneter Term und Position eines Terms werden von allen Locales gemeinsam genutzt. Eine Übersetzung, die ohne übergeordneten Term erstellt wird, übernimmt den übergeordneten Term und die Position ihres Terms. Das Erstellen einer Übersetzung unter einem anderen übergeordneten Term oder das Ändern des übergeordneten Terms über eine beliebige Locale verschiebt den Term in jeder Locale.

Die Abfrage-Helfer verwenden eine explizit angegebene Locale. Andernfalls verwenden sie die Locale der aktuellen Anfrage, dann den konfigurierten Standard. Abfragen einzelner Terms folgen der konfigurierten Fallback-Kette, wenn die angeforderte Übersetzung fehlt.

Siehe Internationalisierung (i18n) für Locale-Routing und Fallback-Konfiguration und Mit Inhalten arbeiten für das Bearbeiten von Einträgen. Die JavaScript-API-Referenz dokumentiert die Taxonomie-Abfrage-Helfer. Für programmatische Änderungen authentifizieren Sie sich mit einem Bearer-Token und fügen jeder zustandsändernden Anfrage X-EmDash-Request: 1 hinzu. Siehe die Taxonomie-Endpunkte für Anfrage-Bodys und Antworten.