Aree widget

Un’area widget è una posizione con nome in un template del sito. Gli editor scelgono cosa appare al suo interno, mentre il template controlla dove si trova l’area e come viene stilizzato il suo output.

Usa un’area widget per i contenuti che devono restare sincronizzati ovunque appaia l’area, come una barra laterale, una colonna del footer o un messaggio promozionale. Usa invece una sezione quando un editor deve inserire e poi personalizzare una copia indipendente all’interno di una voce.

Aggiungere un’area widget

Crea e popola le aree widget in Widgets nell’amministrazione di EmDash.

I tipi di widget disponibili sono:

• Content renderizza Portable Text inserito da un editor.
• Menu renderizza un menu selezionato per nome.
• Component renderizza uno dei componenti integrati: post recenti, categorie, tag, ricerca o archivi.

Le impostazioni del componente nell’amministrazione controllano dettagli come i limiti di elementi, le date, i conteggi e il testo segnaposto della ricerca.

Sono disponibili i seguenti widget di componenti integrati:

Il template di link di core:recent-posts accetta gli stessi token del routeMap di LiveSearch: :collection, :id (l’ULID del contenuto), :slug (lo slug semplice) e :path (slug o ID). Senza template, i link mantengono la forma attuale, incluso qualsiasi prefisso di lingua di i18n di Astro.

Posizionare l’area in un template

Importa WidgetArea da emdash/ui. Il componente recupera l’area indicata per nome, mantiene l’ordine configurato e non renderizza nulla quando l’area manca o è vuota.

Il layout seguente posiziona un’area barra laterale accanto al contenuto della pagina:

---
import { WidgetArea } from "emdash/ui";
---

<div class="page-with-sidebar">
  <main>
    <slot />
  </main>

  <aside aria-label="Sidebar">
    <WidgetArea name="sidebar" class="sidebar-widgets" />
  </aside>
</div>

WidgetArea aggiunge widget-area e la class fornita al proprio wrapper. Ogni elemento usa le classi widget, widget__title e widget__content. I widget di contenuto, di menu e di componenti integrati aggiungono classi più specifiche al di sotto di queste.

Gli stili dei componenti Astro hanno per impostazione predefinita uno scope limitato. Usa un blocco di stili globale quando stilizzi il markup renderizzato all’interno di WidgetArea:

<style is:global>
  .page-with-sidebar {
    display: grid;
    grid-template-columns: minmax(0, 1fr) 18rem;
    gap: 2rem;
  }

  .sidebar-widgets {
    display: grid;
    gap: 1.5rem;
  }

  .sidebar-widgets .widget__title {
    margin-block-end: 0.75rem;
  }

  @media (max-width: 48rem) {
    .page-with-sidebar {
      grid-template-columns: 1fr;
    }
  }
</style>

Menu e tassonomie nei widget

I widget di menu, categorie e tag interrogano i dati nella lingua della richiesta corrente. I riferimenti dei menu vengono inoltre risolti nel contenuto o nel termine tradotto, quando esiste.

Il renderer di widget integrato usa l’URL relativo alla radice restituito dall’helper del menu o della tassonomia. Non aggiunge il prefisso di lingua di Astro. Su un sito multilingue, renderizza la navigazione e gli elenchi di tassonomie con il pattern di rendering dei menu o il pattern per l’elenco dei termini quando quei link richiedono prefissi di lingua. I widget di contenuto, ricerca, post recenti e archivi possono comunque usare il componente standard WidgetArea.

Renderizzare un’area in autonomia

Chiama getWidgetArea() quando il sito richiede un markup che il renderer integrato non fornisce. L’esempio seguente renderizza un’area contenente widget di contenuto e di menu, e aggiunge il prefisso di lingua di Astro ai link del menu.

Per prima cosa, recupera l’area e passa ogni widget configurato a un renderer:

---
import { getWidgetArea } from "emdash";
import LocalizedWidget from "./LocalizedWidget.astro";

interface Props {
  name: string;
}

const area = await getWidgetArea(Astro.props.name);
---

{area && area.widgets.length > 0 && (
  <div class="widget-area" data-widget-area={area.name}>
    {area.widgets.map((widget) => (
      <LocalizedWidget widget={widget} />
    ))}
  </div>
)}

Poi gestisci esplicitamente i widget di contenuto e di menu:

---
import { getMenu } from "emdash";
import type { Widget } from "emdash";
import { PortableText } from "emdash/ui";
import { getRelativeLocaleUrl } from "astro:i18n";

interface Props {
  widget: Widget;
}

const { widget } = Astro.props;
const locale = Astro.currentLocale;
const menu = widget.type === "menu" && widget.menuName
  ? await getMenu(widget.menuName, { locale })
  : null;

function menuHref(url: string) {
  return locale && url.startsWith("/")
    ? getRelativeLocaleUrl(locale, url)
    : url;
}
---

{widget.type !== "component" && (
  <section class="widget" data-widget-id={widget.id}>
    {widget.title && <h3>{widget.title}</h3>}

    {widget.type === "content" && widget.content && (
      <PortableText value={widget.content} />
    )}

    {widget.type === "menu" && menu && (
      <nav aria-label={widget.title}>
        <ul>
          {menu.items.map((item) => (
            <li>
              <a
                href={menuHref(item.url)}
                target={item.target}
                rel={item.target === "_blank" ? "noopener noreferrer" : undefined}
              >
                {item.label}
              </a>
            </li>
          ))}
        </ul>
      </nav>
    )}
  </section>
)}

Questo renderer mirato non produce alcun output per i widget di componenti. Mantieni i widget di componenti nel WidgetArea standard, oppure aggiungi casi espliciti per ID di componente per i componenti del sito che supporti.

Il riferimento dell’API di runtime documenta getWidgetArea() e getWidgetAreas(). 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 aree widget per i corpi delle richieste e le risposte.