Tassonomie

Una tassonomia è una classificazione con nome applicata a una o più collection. EmDash parte con la tassonomia gerarchica category e la tassonomia piatta tag per i post. Un sito può anche definire tassonomie come genre, topic o difficulty.

I termini appartengono a una tassonomia. Una categoria come «Guides» può avere categorie figlie, mentre i tag e le altre tassonomie piatte hanno un livello.

Gestire i termini

Apri una tassonomia da Taxonomies nell’amministrazione di EmDash.

Gli editor assegnano i termini dai pannelli delle tassonomie in una voce di contenuto. La definizione della tassonomia controlla in quali collection viene mostrato ogni pannello.

Eliminare un termine rimuove le sue assegnazioni dal contenuto. Non elimina le voci di contenuto.

Aggiungere un termine a più post

Gli editor possono selezionare dei post in un elenco di una collection e fare clic su Add seguito dal nome singolare della tassonomia (ad esempio Add tag), oppure aprire la pagina di una tassonomia e fare clic su Add to posts per incollare gli URL pubblici dei post (uno per riga, fino a 50). Quando alla collection si applica più di una tassonomia, l’elenco mostra Add term e la finestra di dialogo chiede quale tassonomia usare. Scegli un termine esistente o creane uno nella finestra di dialogo, quindi fai clic su Review posts. Controlla ogni titolo e lingua corrispondente, poi fai clic sul pulsante che indica quanti post verranno aggiornati. I link che non corrispondono esattamente a un post pubblicato su questo sito vengono segnalati anziché indovinati. Possono essere abbinate solo le voci delle collection che usano la tassonomia scelta.

L’aggiunta del termine ha effetto immediato, anche quando un post ha altre modifiche di bozza non pubblicate; non pubblica quelle modifiche. I termini esistenti restano al loro posto e i post che hanno già il termine vengono saltati. L’elenco dei risultati mostra quali post sono stati aggiornati, saltati o non è stato possibile aggiornare; usa Retry failures per gli errori di scrittura. L’abbinamento degli URL usa l’origin pubblico configurato del sito e i pattern URL delle collection, inclusi i percorsi di data e lingua.

Aggiungere una tassonomia personalizzata

Crea una tassonomia quando una collection esistente ha bisogno di una classificazione separata.

I template interrogano il nome stabile. Cambiare un’etichetta visualizzata non richiede modifiche al template.

Le tassonomie personalizzate usano gli stessi helper di query e di filtro di categorie e tag. L’esempio seguente legge i termini genre e filtra i libri in base a uno dei loro slug:

import { getEmDashCollection, getTaxonomyTerms } from "emdash";

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

Eliminare una tassonomia

Apri la tassonomia nell’amministrazione, quindi scegli Delete taxonomy dal menu delle azioni nell’intestazione della pagina e conferma. L’azione richiede il permesso taxonomies:manage, che hanno gli editor e gli amministratori.

Eliminare una tassonomia elimina i suoi termini in ogni lingua e rimuove quei termini dal contenuto che vi era classificato. Le voci di contenuto in sé vengono conservate.

Interrogare un elenco di termini

Usa getTaxonomyTerms() per renderizzare un indice di tassonomia, un elenco di navigazione o un insieme di filtri. Le tassonomie gerarchiche restituiscono un albero attraverso l’array children di ciascun termine.

I conteggi dei termini sono inclusi per impostazione predefinita e richiedono un’aggregazione sulle collection assegnate alla tassonomia. Salta quel lavoro quando il componente non mostra i conteggi.

Il componente seguente renderizza i link delle categorie senza conteggi:

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

Quando un componente mostra l’utilizzo, ometti includeCounts: false e renderizza term.count. Il conteggio include le voci visibili pubblicamente nella locale usata per la query.

Creare un archivio di tassonomia

Decodifica il parametro di una route dinamica prima di cercare un termine. Interroga termine e contenuto con la stessa locale e fai passare i percorsi generati dall’helper degli URL di locale di Astro.

La route seguente elenca i post pubblicati in una categoria:

---
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 usa il nome della tassonomia come chiave e lo slug di un termine come valore. Gli identificatori di ordinamento delle query usano nomi di campo del database come published_at; i dati della voce espongono il valore corrispondente come publishedAt.

Usa in postHref() la vera route pubblica della collection. Se la collection usa un urlPattern personalizzato, costruisci i link a partire da quel pattern invece di dare per scontato /posts/{slug}.

Mostrare i termini di una voce

getEmDashEntry() e getEmDashCollection() idratano i termini assegnati in entry.data.terms. Leggi quel valore invece di eseguire una query getEntryTerms() per ogni voce di un elenco.

Il componente seguente renderizza le categorie e i tag già caricati con 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>
)}

Usa getEntryTerms() quando hai solo il nome di una collection e l’ID di una voce. Usa getTermsForEntries() per recuperare in blocco i termini di più voci quando non sono stati idratati dalla query di contenuto.

Tradurre tassonomie e termini

Le definizioni delle tassonomie e i termini hanno una riga per locale. EmDash registra quali righe sono traduzioni della stessa tassonomia o dello stesso termine. Le assegnazioni di contenuto usano questa identità condivisa, quindi un’assegnazione fatta in una locale si risolve nel termine tradotto in un’altra locale quando ne esiste uno.

Una definizione di tassonomia divide i propri campi tra la tassonomia e ciascuna locale:

Una definizione creata per un nome che esiste già in un’altra locale si unisce a quella tassonomia, con o senza translationOf, e ne assume hierarchical e collections. Crearla con valori diversi fallisce; cambiali con un aggiornamento. Una locale senza definizione propria elenca comunque i termini della tassonomia e mostra l’etichetta della prima locale della sua catena di fallback che ne ha una, altrimenti l’etichetta della locale predefinita, altrimenti l’etichetta della locale con il codice locale più basso.

Usa il selettore di locale in una pagina di tassonomia per gestire i termini in ogni locale configurata. Apri la finestra di modifica di un termine e usa il suo pannello Translations per aggiungere o aprire un’altra locale. Un termine tradotto può usare uno slug e un’etichetta diversi.

Il genitore e la posizione di un termine sono condivisi da ogni locale. Una traduzione creata senza genitore assume il genitore e la posizione del suo termine. Creare una traduzione sotto un genitore diverso, o cambiare il genitore da una qualsiasi locale, sposta il termine in ogni locale.

Gli helper di query usano una locale esplicita quando viene fornita. Altrimenti usano la locale della richiesta corrente, poi il valore predefinito configurato. Le ricerche di un singolo termine seguono la catena di fallback configurata quando manca la traduzione richiesta.

Consulta Internazionalizzazione (i18n) per il routing delle locale e la configurazione del fallback, e Lavorare con i contenuti per la modifica delle voci. Il Riferimento API JavaScript documenta gli helper di query delle tassonomie. Per le modifiche programmatiche, autenticati con un token Bearer e aggiungi X-EmDash-Request: 1 a ogni richiesta che modifica lo stato. Consulta gli endpoint delle tassonomie per i corpi delle richieste e le risposte.