Áreas de widgets

Uma área de widgets é uma posição nomeada em um template do site. Os editores escolhem o que aparece ali, enquanto o template controla onde a área fica e como a saída dela é estilizada.

Use uma área de widgets para conteúdo que deve permanecer sincronizado em todos os lugares onde a área aparece, como uma barra lateral, uma coluna do rodapé ou uma mensagem promocional. Use uma seção quando um editor precisar inserir e depois personalizar uma cópia independente dentro de uma entrada.

Adicionar uma área de widgets

Crie e preencha as áreas de widgets em Widgets no administrador do EmDash.

Os tipos de widget disponíveis são:

• Content renderiza Portable Text inserido por um editor.
• Menu renderiza um menu selecionado pelo nome.
• Component renderiza um dos componentes integrados: posts recentes, categorias, tags, busca ou arquivos.

As configurações do componente no administrador controlam detalhes como limites de itens, datas, contagens e o texto de placeholder da busca.

Os seguintes widgets de componentes integrados estão disponíveis:

O template de link de core:recent-posts aceita os mesmos tokens que o routeMap do LiveSearch: :collection, :id (o ULID do conteúdo), :slug (o slug simples) e :path (slug ou ID). Sem um template, os links mantêm o formato atual, incluindo qualquer prefixo de idioma do i18n do Astro.

Colocar a área em um template

Importe WidgetArea de emdash/ui. O componente busca a área nomeada, preserva a ordem configurada e não renderiza nada quando a área não existe ou está vazia.

O layout a seguir coloca uma área de barra lateral ao lado do conteúdo da página:

---
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 adiciona widget-area e a class fornecida ao seu wrapper. Cada item usa as classes widget, widget__title e widget__content. Os widgets de conteúdo, de menu e de componentes integrados adicionam classes mais específicas abaixo delas.

Os estilos de componentes Astro têm escopo por padrão. Use um bloco de estilo global ao estilizar a marcação renderizada dentro 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 e taxonomias em widgets

Os widgets de menu, categoria e tag consultam dados no idioma da requisição atual. As referências de menu também são resolvidas para o conteúdo ou termo traduzido quando ele existe.

O renderizador de widgets integrado usa a URL relativa à raiz retornada pelo helper de menu ou de taxonomia. Ele não adiciona o prefixo de idioma do Astro. Em um site multilíngue, renderize a navegação e as listas de taxonomias com o padrão de renderização de menu ou o padrão de lista de termos quando esses links precisarem de prefixos de idioma. Os widgets de conteúdo, busca, posts recentes e arquivos ainda podem usar o componente padrão WidgetArea.

Renderizar uma área por conta própria

Chame getWidgetArea() quando o site precisar de uma marcação que o renderizador integrado não oferece. O exemplo a seguir renderiza uma área contendo widgets de conteúdo e de menu e adiciona o prefixo de idioma do Astro aos links do menu.

Primeiro, busque a área e passe cada widget configurado para um renderizador:

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

Em seguida, trate explicitamente os widgets de conteúdo e 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>
)}

Esse renderizador específico não produz saída para widgets de componentes. Mantenha os widgets de componentes no WidgetArea padrão ou adicione casos explícitos por ID de componente para os componentes do site que você oferece suporte.

A referência da API de runtime documenta getWidgetArea() e getWidgetAreas(). Para alterações programáticas, autentique-se com um token Bearer e adicione X-EmDash-Request: 1 a toda requisição que altere o estado. Consulte os endpoints de áreas de widgets para ver os corpos das requisições e as respostas.