Zones de widgets

Une zone de widgets est un emplacement nommé dans un modèle de site. Les éditeurs choisissent ce qui y apparaît, tandis que le modèle contrôle l’endroit où se trouve la zone et la façon dont sa sortie est stylée.

Utilisez une zone de widgets pour du contenu qui doit rester synchronisé partout où la zone apparaît, comme une barre latérale, une colonne de pied de page ou un message promotionnel. Utilisez plutôt une section lorsqu’un éditeur doit insérer puis personnaliser une copie indépendante dans une entrée.

Ajouter une zone de widgets

Créez et remplissez les zones de widgets dans Widgets dans l’administration EmDash.

Les types de widgets disponibles sont :

• Content rend du Portable Text saisi par un éditeur.
• Menu rend un menu sélectionné par son nom.
• Component rend l’un des composants intégrés : articles récents, catégories, étiquettes, recherche ou archives.

Les paramètres du composant dans l’administration contrôlent des détails tels que les limites d’éléments, les dates, les compteurs et le texte indicatif de la recherche.

Les widgets de composants intégrés suivants sont disponibles :

Le modèle de lien de core:recent-posts accepte les mêmes jetons que le routeMap de LiveSearch : :collection, :id (l’ULID du contenu), :slug (le slug seul) et :path (slug ou ID). Sans modèle, les liens conservent leur forme actuelle, y compris tout préfixe de langue i18n d’Astro.

Placer la zone dans un modèle

Importez WidgetArea depuis emdash/ui. Le composant récupère la zone nommée, conserve l’ordre configuré et ne rend rien lorsque la zone est absente ou vide.

La mise en page suivante place une zone de barre latérale à côté du contenu de la page :

---
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 ajoute widget-area et la class fournie à son conteneur. Chaque élément utilise les classes widget, widget__title et widget__content. Les widgets de contenu, de menu et de composant intégré ajoutent des classes plus spécifiques en dessous.

Les styles des composants Astro sont limités à leur portée par défaut. Utilisez un bloc de styles global pour styler le balisage rendu à l’intérieur de 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>

Menus et taxonomies dans les widgets

Les widgets de menu, de catégories et d’étiquettes interrogent les données dans la langue de la requête courante. Les références de menu se résolvent également vers le contenu ou le terme traduit lorsqu’il existe.

Le moteur de rendu de widgets intégré utilise l’URL relative à la racine renvoyée par l’assistant de menu ou de taxonomie. Il n’ajoute pas le préfixe de langue d’Astro. Sur un site multilingue, rendez la navigation et les listes de taxonomies avec le modèle de rendu de menu ou le modèle de liste de termes lorsque ces liens ont besoin de préfixes de langue. Les widgets de contenu, de recherche, d’articles récents et d’archives peuvent toujours utiliser le composant standard WidgetArea.

Rendre une zone soi-même

Appelez getWidgetArea() lorsque le site a besoin d’un balisage que le moteur de rendu intégré ne fournit pas. L’exemple suivant rend une zone contenant des widgets de contenu et de menu, et ajoute le préfixe de langue d’Astro aux liens du menu.

Commencez par récupérer la zone et passer chaque widget configuré à un moteur de rendu :

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

Traitez ensuite explicitement les widgets de contenu et de 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>
)}

Ce moteur de rendu ciblé ne produit aucune sortie pour les widgets de composants. Conservez les widgets de composants dans le WidgetArea standard, ou ajoutez des cas explicites par ID de composant pour les composants du site que vous prenez en charge.

La référence de l’API d’exécution documente getWidgetArea() et getWidgetAreas(). Pour des modifications par programmation, authentifiez-vous avec un jeton Bearer et ajoutez X-EmDash-Request: 1 à chaque requête qui modifie l’état. Consultez les endpoints des zones de widgets pour les corps de requête et les réponses.