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

Gli editor assegnano i termini dai pannelli di tassonomia in una voce di contenuto. La definizione della tassonomia controlla quali collection mostrano ciascun pannello.

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

Aggiungere un tag a più post

Gli editor possono selezionare post in un elenco di collection e fare clic su Add tag, oppure aprire Tags e fare clic su Add to posts per incollare URL pubblici di post (uno per riga, fino a 50). Scegli un tag esistente o creane uno nella finestra di dialogo, poi fai clic su Review posts. Controlla ogni titolo e lingua corrispondenti, poi fai clic sul pulsante che indica quanti post verranno taggati. I collegamenti che non corrispondono esattamente a un post pubblicato su questo sito vengono segnalati invece di essere indovinati.

L’aggiunta del tag ha effetto immediato, anche quando un post ha altre modifiche di bozza non pubblicate; non pubblica quelle modifiche. I tag esistenti restano, e i post che hanno già il tag vengono saltati. L’elenco dei risultati mostra quali post sono stati taggati, saltati o non hanno potuto essere taggati; usa Retry failures per gli errori di scrittura. La corrispondenza URL usa l’origine pubblica configurata del sito e i pattern URL delle collection, inclusi percorsi di data e lingua.

Aggiungere una tassonomia personalizzata

Crea una tassonomia quando una collection esistente necessita di una classificazione separata.

I template interrogano il nome stabile. Cambiare un’etichetta di visualizzazione non richiede una modifica del template.

Le tassonomie personalizzate usano gli stessi helper di query e filtro di categorie e tag. L’esempio seguente legge i termini genre e filtra i libri per 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, poi scegli Delete taxonomy dal menu azioni nell’intestazione della pagina e conferma. L’azione richiede il permesso taxonomies:manage, che editor e amministratori detengono.

Eliminare una tassonomia elimina i suoi termini in ogni lingua e rimuove quei termini dal contenuto archiviato sotto di essi. Le voci di contenuto stesse 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 tramite l’array children di ogni termine.

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

Il seguente componente renderizza collegamenti di categoria 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’uso, 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 un parametro di route dinamica prima di cercare un termine. Interroga il termine e il contenuto con la stessa locale, e passa i percorsi generati attraverso l’helper URL di locale di Astro.

La seguente route 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.redirect("/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 uno slug di termine come valore. Gli identificatori di ordinamento della query usano nomi di campo del database come published_at; i dati della voce espongono il valore corrispondente come publishedAt.

Usa la route pubblica reale della collection in postHref(). Se la collection usa un urlPattern personalizzato, costruisci i collegamenti da quel pattern invece di assumere /posts/{slug}.

Mostrare i termini di una voce

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

Il seguente componente renderizza categorie e 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 un nome di collection e un ID voce. Usa getTermsForEntries() per raggruppare i termini di più voci quando non sono stati idratati dalla query di contenuto.

Tradurre tassonomie e termini

Le definizioni di tassonomia 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 quell’identità condivisa, così un’assegnazione fatta in una locale si risolve al termine tradotto in un’altra locale quando ne esiste uno.

Una definizione di tassonomia suddivide i suoi campi tra la tassonomia e ogni locale:

Una definizione creata per un nome che esiste già in un’altra locale si unisce a quella tassonomia, con o senza translationOf, e prende i suoi hierarchical e collections. Crearla con valori diversi fallisce; cambiali con un aggiornamento. Una locale senza una propria definizione elenca comunque i termini della tassonomia e mostra l’etichetta della prima locale nella 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 prende il genitore e la posizione del suo termine. Creare una traduzione sotto un genitore diverso, o cambiare il genitore tramite qualsiasi locale, sposta il termine in ogni locale.

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

Vedi Internationalization per il routing delle locale e la configurazione del fallback e Working with Content per la modifica delle voci. Il riferimento API runtime documenta gli helper di query delle tassonomie. Per modifiche programmatiche, autenticati con un token Bearer e aggiungi X-EmDash-Request: 1 a ogni richiesta che cambia lo stato. Vedi gli endpoint di tassonomia per i corpi delle richieste e le risposte.