Áreas de widgets

Áreas de widgets são regiões nomeadas nos seus templates onde administradores podem colocar blocos de conteúdo. Use-as para barras laterais, colunas de rodapé, banners promocionais ou qualquer secção que editores devam controlar sem alterar código.

Consultar áreas de widgets

Use getWidgetArea() para obter uma área de widgets pelo nome:

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

const sidebar = await getWidgetArea("sidebar");
---

{sidebar && sidebar.widgets.length > 0 && (
  <aside class="sidebar">
    {sidebar.widgets.map(widget => (
      <div class="widget">
        {widget.title && <h3>{widget.title}</h3>}
        <!-- Renderizar conteúdo do widget -->
      </div>
    ))}
  </aside>
)}

A função devolve null se a área de widgets não existir.

Estrutura da área de widgets

Uma área de widgets contém metadados e um array de widgets:

interface WidgetArea {
	id: string;
	name: string; // Identificador único ("sidebar", "footer-1")
	label: string; // Nome apresentado ("Barra lateral principal")
	description?: string;
	widgets: Widget[];
}

interface Widget {
	id: string;
	type: "content" | "menu" | "component";
	title?: string;
	// Campos específicos do tipo
	content?: PortableTextBlock[]; // Widgets de conteúdo
	menuName?: string; // Widgets de menu
	componentId?: string; // Widgets de componente
	componentProps?: Record<string, unknown>;
}

O EmDash suporta três tipos de widget:

Widgets de conteúdo

Texto rico armazenado como Portable Text. Renderize com o componente PortableText:

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

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

Mostram um menu de navegação dentro da área de widgets:

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

const menu = widget.menuName ? await getMenu(widget.menuName) : null;
---

{widget.type === "menu" && menu && (
  <nav class="widget-nav">
    <ul>
      {menu.items.map(item => (
        <li><a href={item.url}>{item.label}</a></li>
      ))}
    </ul>
  </nav>
)}

Widgets de componente

Renderizam um componente registado com props configuráveis. O EmDash inclui estes componentes principais:

ID do componente	Descrição	Props
`core:recent-posts`	Lista de artigos recentes	`count`, `showThumbnails`, `showDate`
`core:categories`	Lista de categorias	`showCount`, `hierarchical`
`core:tags`	Nuvem de etiquetas	`showCount`, `limit`
`core:search`	Formulário de pesquisa	`placeholder`
`core:archives`	Arquivos mensais/anuais	`type`, `limit`

Renderizar widgets

Crie um componente de renderização reutilizável:

---
import { PortableText } from "emdash/ui";
import { getMenu } from "emdash";
import type { Widget } from "emdash";

import RecentPosts from "./widgets/RecentPosts.astro";
import Categories from "./widgets/Categories.astro";
import TagCloud from "./widgets/TagCloud.astro";
import SearchForm from "./widgets/SearchForm.astro";
import Archives from "./widgets/Archives.astro";

interface Props {
  widget: Widget;
}

const { widget } = Astro.props;

const componentMap: Record<string, any> = {
  "core:recent-posts": RecentPosts,
  "core:categories": Categories,
  "core:tags": TagCloud,
  "core:search": SearchForm,
  "core:archives": Archives,
};

const menu = widget.type === "menu" && widget.menuName
  ? await getMenu(widget.menuName)
  : null;
---

<div class="widget">
  {widget.title && <h3 class="widget-title">{widget.title}</h3>}

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

  {widget.type === "menu" && menu && (
    <nav class="widget-menu">
      <ul>
        {menu.items.map(item => (
          <li><a href={item.url}>{item.label}</a></li>
        ))}
      </ul>
    </nav>
  )}

  {widget.type === "component" && widget.componentId && componentMap[widget.componentId] && (
    <Fragment>
      {(() => {
        const Component = componentMap[widget.componentId!];
        return <Component {...widget.componentProps} />;
      })()}
    </Fragment>
  )}
</div>

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

interface Props {
  count?: number;
  showThumbnails?: boolean;
  showDate?: boolean;
}

const { count = 5, showThumbnails = false, showDate = true } = Astro.props;

const { entries: posts } = await getEmDashCollection("posts", {
  limit: count,
  orderBy: { publishedAt: "desc" },
});
---

<ul class="recent-posts">
  {posts.map(post => (
    <li>
      {showThumbnails && post.data.featured_image && (
        <img src={post.data.featured_image} alt="" class="thumbnail" />
      )}
      <a href={`/posts/${post.slug}`}>{post.data.title}</a>
      {showDate && post.data.publishedAt && (
        <time datetime={post.data.publishedAt.toISOString()}>
          {post.data.publishedAt.toLocaleDateString()}
        </time>
      )}
    </li>
  ))}
</ul>

---
interface Props {
  placeholder?: string;
}

const { placeholder = "Pesquisar…" } = Astro.props;
---

<form action="/search" method="get" class="search-form">
  <input
    type="search"
    name="q"
    placeholder={placeholder}
    aria-label="Pesquisar"
  />
  <button type="submit">Pesquisar</button>
</form>