Criando um bloco de lista de referência dinâmica para os serviços de entrega do Adobe Edge

Neste post, vamos explorar como usar o poder dos Serviços de Entrega de Borda e da Criação de Documentos para construir uma lista dinâmica de itens a partir de uma planilha localizada no DA.

Existe uma grande diferença entre despejar uma lista de links em uma página e selecionar algo que seja realmente útil. Este projeto começou com a ideia de "precisamos apenas de uma lista de URLs e descrições", mas rapidamente se transformou na solução de diversos problemas reais: manter o conteúdo organizado, evitar o inchaço do DOM e fazer com que a filtragem pareça rápida sem exageros.

O resultado é o bloco Lista de Referências ; uma grade de cartões filtrável e orientada por dados para o Adobe Edge Delivery Services (EDS) que extrai conteúdo de um feed JSON baseado em planilha, oferece suporte à filtragem por categoria e tag e carrega os resultados progressivamente com animações refinadas. Criamos isso especificamente para direcionar vocês para esta página de referência da Edge Delivery Services , que todos vocês já devem ter adicionado aos favoritos!

Deixando a planilha controlar tudo

O bloco é inteiramente orientado por dados. Ele busca um arquivo JSON gerado por uma planilha EDS em /en/reference-links.json. Optamos por usar um formato com várias folhas; uma folha para itens de referência e outra para categorias:

{
  "data": {
    "data": [
      {
        "url": "https://developer.adobe.com/",
        "image-url": "https://example.com/thumb.png",
        "title": "Adobe Developer Documentation",
        "description": "Official docs for building on Adobe platforms.",
        "tag": "Documentation|Official",
        "category": "Development"
      }
    ]
  },
  "categories": {
    "data": [{ "Category": "Development", "Description": "Dev tools and references" }]
  }
}

As etiquetas utilizam barras verticais dentro da célula (Etiqueta1 | Etiqueta2), o que mantém a autoria simples e previsível.

Ao criar esse bloco, você certamente desejará realizar alguns testes antes de publicá-lo. Se você tiver apenas a lista preenchida dentro do DA, provavelmente encontrará alguns problemas de compartilhamento de recursos de origem cruzada (CORS) ao testar localmente. Para corrigir isso, basta criar seu próprio arquivo JSON com algumas entradas de teste que atendam aos mesmos requisitos da planilha DA e habilitar o uso de JSON local.

const USE_LOCAL_JSON = false;
const LOCAL_JSON_PATH = '/tools/json/reference-list.json';
const LIVE_JSON_URL = '/en/reference-links.json';

Construindo cartas que não quebram

Cada item de referência se torna um cartão com esta estrutura DOM:

.reference-card
  └── a.reference-link
        ├── div.reference-image-wrapper   (optional)
        │     └── img.reference-image
        └── div.reference-content
              ├── h3.reference-title
              ├── p.reference-description  (optional)
              └── div.reference-tags
                    └── span.reference-tag (one per tag)

Ao construir um bloco, um dos aspectos mais importantes a considerar é a facilidade com que um autor poderá utilizá-lo. Para isso, tivemos que garantir que a lista pudesse lidar com diferentes quantidades de informações e ainda funcionar da mesma maneira. Algumas têm descrição, etiquetas ou nenhuma das duas. A regra era renderizar apenas o que existia, mas não deixar que o layout dependesse da presença de qualquer elemento específico. Algumas decisões específicas:

• A imagem é opcional; o campo `image-url` (com uma imagem como alternativa) só é exibido se não estiver vazio.

• As imagens usam loading="lazy" para que as miniaturas fora da tela não bloqueiem a renderização inicial.

• Todos os links usam rel="noopener noreferrer" para evitar o "napping" em URLs externas.

  • Normalmente, os navegadores modernos fazem isso automaticamente, mas é melhor prevenir do que remediar!

Filtrar a lista sem reconstruir o mundo

Ao considerar como filtrar, as coisas podem por vezes ficar complicadas, especialmente quando se trata de renderizar novamente a cada interação. Para evitar isso, garantimos que os atributos de cada cartão fossem definidos desde o início, transformando-o em algo mais parecido com uma ativação/desativação de visibilidade.

card.setAttribute('data-category', ref.category);
card.setAttribute('data-tags', JSON.stringify(cardTags));

Adicionamos também uma função, updateReferenceDisplay, para reavaliar a visibilidade a cada interação:

const categoryMatch = selectedCategory === 'all' || cardCategory === selectedCategory;
const tagMatch = cardTags.length === 0 || cardTags.some((tag) => activeTags.has(tag));

A correspondência de tags usa a lógica OR; qualquer tag selecionada qualifica um cartão. As tags ativas ficam em um conjunto, então adicionar/remover e verificações de associação são todas O(1). Um caso excepcional e sutil: itens sem etiqueta. Permitir que sempre passassem pelo filtro de etiquetas significava que nunca desapareciam inesperadamente.

CSS fazendo mais do que o esperado

Embora este não seja necessariamente um blog sobre estilo, seria negligente da minha parte não mencionar algumas das decisões que tomamos nesse quesito. Principalmente no que diz respeito ao efeito de "holofote" quando o cursor está sobre uma carta.

.reference-grid:has(.reference-card:hover) .reference-card:not(:hover) {
  transform: scale(0.9);
  opacity: 0.6;
}

A animação de entrada gradual segue a mesma abordagem, portanto não há sobrecarga de coordenação entre JS e estilos:

.reference-card { opacity: 0; }

.reference-card.fade-in {
  opacity: 1;
  animation: fade-in-up 0.5s ease-out forwards;
}

@keyframes fade-in-up {
  from { transform: translateY(20px); }
  to   { transform: translateY(0); }
}

Considerações finais

Este projeto é um excelente exemplo de como uma arquitetura bem planejada transforma um padrão comum em algo verdadeiramente escalável. Ao transferir a responsabilidade para os dados estruturados e manter o frontend focado na renderização eficiente e no gerenciamento de estado, o bloco Lista de Referências evita as armadilhas comuns de DOMs inchados e renderizações dispendiosas.

O verdadeiro valor não está apenas na filtragem ou na apresentação, mas no próprio sistema. Os autores obtêm uma maneira previsível e descomplicada de gerenciar o conteúdo, enquanto a implementação permanece eficiente e fácil de expandir. É um padrão que se mantém à medida que o conteúdo cresce, e não algo que precise ser revisto a cada vez que isso acontece.

Veja a página de referência em ação!

Sobre o autor

Gostou do que ouviu? Tem dúvidas sobre o que é certo para você? Adoraríamos conversar! Entre em contato conosco.