Tassonomie

Le tassonomie sono sistemi di classificazione per organizzare i contenuti. EmDash include categorie e tag integrati e supporta tassonomie personalizzate per esigenze di classificazione specializzate.

Tassonomie integrate

EmDash fornisce due tassonomie predefinite:

Entrambe sono disponibili per la collezione dei post per impostazione predefinita.

Gestire i termini

Creare un termine

POST /_emdash/api/taxonomies/category/terms
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{
  "slug": "tutorials",
  "label": "Tutorial",
  "parentId": "term_abc",
  "description": "Guide pratiche e tutorial"
}

Modificare un termine

1. Vai alla pagina dei termini della tassonomia

2. Clicca su Modifica accanto al termine

3. Aggiorna il nome, lo slug, il genitore o la descrizione

4. Clicca su Salva

Eliminare un termine

1. Vai alla pagina dei termini della tassonomia

2. Clicca su Elimina accanto al termine

3. Conferma l’eliminazione

Interrogare le tassonomie

EmDash fornisce funzioni per interrogare i termini di tassonomia e filtrare i contenuti per termine.

Ottenere tutti i termini

Recupera tutti i termini di una tassonomia:

import { getTaxonomyTerms } from "emdash";

// Ottenere tutte le categorie (restituisce struttura ad albero)
const categories = await getTaxonomyTerms("category");

// Ottenere tutti i tag (restituisce lista piatta)
const tags = await getTaxonomyTerms("tag");

Per le tassonomie gerarchiche, i termini includono un array children:

interface TaxonomyTerm {
	id: string;
	name: string; // Nome della tassonomia ("category")
	slug: string; // Slug del termine ("news")
	label: string; // Etichetta di visualizzazione ("News")
	parentId?: string;
	description?: string;
	children: TaxonomyTerm[];
	count?: number; // Numero di voci con questo termine
}

Calcolare count aggrega ogni assegnazione contenuto-termine nelle collezioni della tassonomia, che è la parte più costosa della chiamata. Se hai bisogno solo di etichette e slug, saltalo — count viene quindi omesso dai termini restituiti:

const tags = await getTaxonomyTerms("tag", { includeCounts: false });

Ottenere un singolo termine

Il seguente esempio recupera un termine per tassonomia e slug:

import { getTerm } from "emdash";

const category = await getTerm("category", "news");
// Restituisce TaxonomyTerm o null

Ottenere i termini di una voce

Il seguente esempio recupera le categorie e i tag assegnati a una singola voce:

import { getEntryTerms } from "emdash";

// Ottenere tutte le categorie di un post
const categories = await getEntryTerms("posts", "post-123", "category");

// Ottenere tutti i tag di un post
const tags = await getEntryTerms("posts", "post-123", "tag");

Filtrare i contenuti per termine

Usa getEmDashCollection con il filtro where:

import { getEmDashCollection } from "emdash";

// Post nella categoria "news"
const { entries: newsPosts } = await getEmDashCollection("posts", {
	status: "published",
	where: { category: "news" },
});

// Post con il tag "javascript"
const { entries: jsPosts } = await getEmDashCollection("posts", {
	status: "published",
	where: { tag: "javascript" },
});

O usa la funzione di comodità:

import { getEntriesByTerm } from "emdash";

const newsPosts = await getEntriesByTerm("posts", "category", "news");

Creare pagine di tassonomia

Archivio categorie

Crea una pagina che elenca i post di una categoria:

---
import { getTaxonomyTerms, getTerm, getEmDashCollection } from "emdash";
import Base from "../../layouts/Base.astro";

export async function getStaticPaths() {
  const categories = await getTaxonomyTerms("category");

  function flatten(terms) {
    return terms.flatMap((term) => [term, ...flatten(term.children)]);
  }

  return flatten(categories).map((cat) => ({
    params: { slug: cat.slug },
    props: { category: cat },
  }));
}

const { category } = Astro.props;

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

<Base title={category.label}>
  <h1>{category.label}</h1>
  {category.description && <p>{category.description}</p>}
  <p>{category.count} post</p>

  <ul>
    {posts.map((post) => (
      <li>
        <a href={`/blog/${post.data.slug}`}>{post.data.title}</a>
      </li>
    ))}
  </ul>
</Base>

Archivio tag

Crea una pagina che elenca i post con un tag:

---
import { getTaxonomyTerms, getEmDashCollection } from "emdash";
import Base from "../../layouts/Base.astro";

export async function getStaticPaths() {
  const tags = await getTaxonomyTerms("tag");

  return tags.map((tag) => ({
    params: { slug: tag.slug },
    props: { tag },
  }));
}

const { tag } = Astro.props;

const { entries: posts } = await getEmDashCollection("posts", {
  status: "published",
  where: { tag: tag.slug },
});
---

<Base title={`Post con tag "${tag.label}"`}>
  <h1>#{tag.label}</h1>

  <ul>
    {posts.map((post) => (
      <li>
        <a href={`/blog/${post.data.slug}`}>{post.data.title}</a>
      </li>
    ))}
  </ul>
</Base>

Widget lista categorie

Mostra una lista di categorie con conteggio dei post:

---
import { getTaxonomyTerms } from "emdash";

const categories = await getTaxonomyTerms("category");
---

<nav class="category-list">
  <h3>Categorie</h3>
  <ul>
    {categories.map((cat) => (
      <li>
        <a href={`/category/${cat.slug}`}>
          {cat.label} ({cat.count})
        </a>
        {cat.children.length > 0 && (
          <ul>
            {cat.children.map((child) => (
              <li>
                <a href={`/category/${child.slug}`}>
                  {child.label} ({child.count})
                </a>
              </li>
            ))}
          </ul>
        )}
      </li>
    ))}
  </ul>
</nav>

Cloud di tag

Mostra i tag con dimensione basata sull’utilizzo:

---
import { getTaxonomyTerms } from "emdash";

const tags = await getTaxonomyTerms("tag");

const counts = tags.map((t) => t.count ?? 0);
const maxCount = Math.max(...counts, 1);
const minSize = 0.8;
const maxSize = 2;

function getSize(count: number) {
  const ratio = count / maxCount;
  return minSize + ratio * (maxSize - minSize);
}
---

<div class="tag-cloud">
  {tags.map((tag) => (
    <a
      href={`/tag/${tag.slug}`}
      style={`font-size: ${getSize(tag.count ?? 0)}rem`}
    >
      {tag.label}
    </a>
  ))}
</div>

Mostrare i termini sul contenuto

Mostra categorie e tag su un post:

---
import { getEntryTerms } from "emdash";

interface Props {
  collection: string;
  entryId: string;
}

const { collection, entryId } = Astro.props;

const categories = await getEntryTerms(collection, entryId, "category");
const tags = await getEntryTerms(collection, entryId, "tag");
---

<div class="post-terms">
  {categories.length > 0 && (
    <div class="categories">
      <span>Pubblicato in:</span>
      {categories.map((cat, i) => (
        <>
          {i > 0 && ", "}
          <a href={`/category/${cat.slug}`}>{cat.label}</a>
        </>
      ))}
    </div>
  )}

  {tags.length > 0 && (
    <div class="tags">
      {tags.map((tag) => (
        <a href={`/tag/${tag.slug}`} class="tag">
          #{tag.label}
        </a>
      ))}
    </div>
  )}
</div>

Tassonomie personalizzate

Crea tassonomie oltre a categorie e tag per esigenze specializzate.

Creare una tassonomia personalizzata

Usa l’API admin per creare una tassonomia:

POST /_emdash/api/taxonomies
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{
  "name": "genre",
  "label": "Generi",
  "labelSingular": "Genere",
  "hierarchical": true,
  "collections": ["books", "movies"]
}

Usare tassonomie personalizzate

Interroga e mostra tassonomie personalizzate allo stesso modo di quelle integrate:

import { getTaxonomyTerms, getEmDashCollection } from "emdash";

// Ottenere tutti i generi
const genres = await getTaxonomyTerms("genre");

// Ottenere libri di un genere
const { entries: sciFiBooks } = await getEmDashCollection("books", {
	where: { genre: "science-fiction" },
});

Assegnare alle collezioni

Le tassonomie specificano a quali collezioni si applicano:

{
  "name": "difficulty",
  "label": "Livelli di difficoltà",
  "hierarchical": false,
  "collections": ["recipes", "tutorials"]
}

Riferimento API delle tassonomie

Endpoint REST

Assegnare termini al contenuto

La seguente richiesta assegna termini di categoria a un post:

POST /_emdash/api/content/posts/post-123/terms/category
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{
  "termIds": ["term_news", "term_featured"]
}

Prossimi passi

• Creare un blog - Usare categorie e tag in un blog
• Interrogare i contenuti - Filtrare per termini di tassonomia
• Lavorare con i contenuti - Assegnare termini nell’editor