Tipos utilitários

Leitura sugerida

• Conceitos: Section
• Codificando uma nova Section

Você já sabe que é fácil criar uma Section configurável na deco.cx. Neste post vamos detalhar todas as formas possíveis de declarar os types das props e como isso afeta o formulário que renderizamos no Admin da deco.cx.

Personalizando Sections

As Sections, como componentes Preact, aceitam props como seus primeiro argumento e usam esses valores em seus markups para exibir textos, imagens ou configurar algum comportamento.

Normalmente, essas props são passadas a partir de outro componente, mas quando você usa deco.cx essas props são configuradas no Admin, o que facilita usuários de negócios alterarem o conteúdo em seus Sites.

Para declarar como essas props serão configuradas você usa o Typescript type, especificando quais props e seus respectivos tipos como string, number, Array<T>, etc.

Exemplo:

• Configuração de Section em um site deco.cx.

interface Props {
  título: string;
}

export default function LatestPosts({ title }: Props) {
  return (
    <div>
      <h1 class="font-bold">{title}</h1>
      <p>Esta é uma Section de exemplo</p>
    </div>
  );
}

• Como fica o editor no Admin:

Tipos suportados

O editor aceita um subconjunto de tipos Typescript para configuração da Section. Esta é a lista de tipos suportados atualmente:

Tipos nativos

string

export interface Props {
  title: string;
}

number

export interface Props {
  lineNumber: número;
}

object

export interface Props {
  address: {
    street: string;
    postalCode: string;
  };
}

array

export default {
   menuItems: Array<{ label: string; value: string }>;
}

string options

export interface Props {
  variant: "primary" | "secondary" | "tertiary";
}

Tipos Especiais

Imagem

Este tipo renderiza um widget de upload de imagem no editor, possibilitando os usuários fazer upload de imagens.

O tipo é um wrapper para string, então a Section receberá a URL da imagem hospedada nos servidores da deco.cx.

Você pode ler mais sobre como trabalhar com Imagens na deco.cx aqui

Opcional: A deco.cx fornece um componente que otimiza o carregamento da imagens e pode ser usado em conjunto com esta propriedade.

Exemplo:

import type { ImageWidget as Image } from "apps/admin/widgets.ts";

export interface props {
  bannerImg: Image;
}

Vídeo

Semelhante à Imagem, as propriedades com este tipo serão editadas através de um widget com a possibilidade de upload de vídeos.

Exemplo de uso aqui.

import type { VideoWidget as Video } from "apps/admin/widgets.ts";

export interface props {
  myVideo: Video;
}

Enriquecendo o editor

Ao usar tipos nativos, o editor usará o nome do prop como a label padrão do formulário. Mas é possível personalizar isso usando tags JSDoc.

• Exemplo: Código da Section:

export interface props {
  /** @title Numero de produtos */
  /** @description Total de produtos para mostrar na vitrine */
  count: number;
}

• Editor:

As tags disponíveis são os campos compatíveis com JSON Schema, ou seja, @title, @description, @format entre outros. Por exemplo, para aceitar apenas e-mails:

export interface props {
  /** @format email */
  color: string;
}

Outros tipos de formatos válidos são: uri, color.

Carregando dados de APIs externas

Um caso de uso comum para obter dados dentro de Sections é usar fontes como APIs ou bancos de dados. Este é um cenário muito comum no ecommerce, onde geralmente queremos obter dados do produto através da API de um ecommerce provider (como Shopify, Magento, VTEX...).

Para entender como fazer isso com Sections e Loaders, leia Buscando dados de APIs.