Componentes

Os componentes permitem que um clube no plano Pro escreva as próprias seções do site em código: uma contagem regressiva para a abertura da temporada, uma tabela de classificação nas suas cores, qualquer coisa que as seções prontas não fazem. Você escreve um componente em TypeScript e React, o ClubHelix o verifica e compila e, depois que você o publica e instala, ele entra em qualquer página como uma seção pronta.

Um componente interativo, o padrão, roda em um quadro isolado, em um domínio separado. Ele não consegue ver o seu painel, os dados dos seus sócios nem o acesso de ninguém, e lê só as informações públicas que você permitir. Um componente estático é transformado em HTML simples com antecedência e mostrado como parte da página, sem nenhum script rodando no navegador do visitante.

Quem pode usar

• Os administradores da sua organização podem criar, editar, compilar, publicar, instalar, desativar e arquivar componentes.
• Um moderador que recebeu a permissão Criar e editar componentes pode abrir a página e olhar, mas não consegue alterar nada.
• Os componentes fazem parte do plano Pro, e você precisa ativá-los antes em Recursos.

O que há na página

Gestão do site → Componentes lista os seus componentes: a versão mais recente de cada um, em que ponto está a compilação (em palavras, como "Compilação aprovada, ainda não publicada") e se ele está instalado no seu site. Crie um novo componente pelo formulário no topo.

Abra um componente para ver:

• Código-fonte: os seus arquivos, com index.tsx primeiro. Ele precisa exportar o componente como padrão (default export).
• Manifesto (component.json): o nome do componente, a versão, os dados que ele pode ler, onde ele pode ficar em uma página e a altura máxima.
• Configurações de exemplo: configurações de amostra com que a compilação renderiza o seu componente. A prévia usa a primeira.
• Compilação: cada etapa da última compilação e todas as mensagens que ela gerou, com o arquivo e a linha.
• Prévia: depois que uma compilação é aprovada, o componente rodando no mesmo tipo de quadro que o seu site usa.
• Versões: todas as versões e a situação de cada uma. Escolha uma para abri-la.
• No seu site: instalar, desativar, desinstalar ou arquivar.

Passo a passo

Escolher entre estático e interativo

Defina renderMode no manifesto:

• Interativo ("interactive", o padrão) roda no navegador do visitante, em um quadro próprio. Escolha-o para qualquer coisa em que as pessoas clicam ou que muda sozinha: abas, calculadoras, contagens regressivas, carrosséis.
• Estático ("static") é renderizado uma vez em HTML simples com os dados públicos da sua organização e mostrado como parte da página. Mecanismos de busca e leitores de tela o leem como o resto da página. Nenhum código dele roda no navegador do visitante, então nada nele é interativo: cliques, temporizadores e atualizações ao vivo não fazem nada, e os efeitos (useEffect) nunca rodam, então ele sempre mostra a primeira renderização.

Um componente estático é renderizado depois que você salva uma página que o usa e de novo quando as informações que ele mostra mudam: notícias, eventos e seus locais, patrocinadores, equipes, programas, jogos e resultados, ou o nome e o logo da sua organização. Uma nova renderização costuma aparecer no seu site em cerca de dez minutos, e o mesmo componente é renderizado no máximo uma vez a cada cinco minutos. Enquanto uma nova renderização está sendo feita, os visitantes continuam vendo a última, então o componente nunca fica em branco, e, se uma nova renderização falhar, a última boa continua no ar. Até a primeira renderização ficar pronta, os visitantes não veem nada no lugar dele, e os seus administradores veem "Preparando este componente".

Um componente estático pode ter estilo próprio com um arquivo component.css. Esses estilos se aplicam só dentro do componente, nunca ao resto da página. Os componentes prontos Heading e Text definem a própria cor e o próprio tamanho a partir do seu tema, então uma regra como h2 { color: … } não vai mudá-los. Estilize os seus próprios elementos ou nomes de classe, ou adicione !important à regra.

Escrever e compilar um componente

1. Digite um nome no formulário no topo da página e clique em Criar componente. Ele começa como um exemplo que funciona e que você pode alterar.
2. Edite index.tsx. Declare as configurações que as pessoas preenchem com um schema zod exportado como propsSchema.
3. Altere o manifesto se precisar: por exemplo, adicione "events:read" a data para ler os seus eventos.
4. Clique em Salvar rascunho e depois em Compilar. Uma compilação costuma começar em até um minuto, e a página se atualiza sozinha.
5. Se a compilação falhar, leia as mensagens em Compilação, corrija o arquivo e a linha que elas apontam, salve e compile de novo.

Pedir um rascunho ao assistente

Abra o Assistente Helix nesta página e descreva o que você quer, como "Crie uma contagem regressiva para a abertura da nossa temporada em 7 de março". Ele mostra os arquivos e o que o componente vai ler. Quando você clica em Aplicar, ele salva um rascunho e inicia uma compilação, e o assistente mostra como a compilação está indo. Se a compilação falhar, clique em Corrigir os erros de compilação, e o assistente recebe as mensagens da própria compilação e devolve um rascunho corrigido. Cada rodada usa um dos seus pedidos diários, e você tem até cinco rodadas por componente em uma conversa. O assistente nunca publica nem instala um componente. Você confere a prévia e faz isso por conta própria.

Publicar e instalar

1. Quando a compilação for aprovada, confira a Prévia e clique em Publicar. Uma versão publicada não pode ser alterada; as mudanças seguintes vão para uma nova versão (Iniciar uma nova versão).
2. Em No seu site, leia o que o componente vai poder ver e clique em Instalar.
3. No editor de páginas, adicione uma seção Componente personalizado, escolha o seu componente e preencha as configurações dele.
4. Salve a página. Um componente estático aparece nela alguns minutos depois de salvar.

Passar o seu site para uma nova versão

1. Clique em Iniciar uma nova versão, faça as alterações e depois compile e publique.
2. Em No seu site, clique em Mudar o site para a nova versão. Todas as páginas que mostram o componente passam para ela de uma vez, então não há nada para mudar nas páginas.
3. Se a nova versão mudou as configurações, confira cada página que a usa. Uma seção cujas configurações a nova versão não aceita deixa de aparecer até você corrigi-las no editor de páginas.

Tirar o componente do site

• Desativar faz ele parar de aparecer em todos os lugares na hora. Reativar o traz de volta.
• Desinstalar remove a instalação. Arquivar oculta o componente e o desativa.

Referência de campos

O que um componente pode importar. react, zod e @clubhelix/component-sdk (títulos, textos, botões, imagens, uma contagem regressiva e mais, com o estilo do seu tema), além dos próprios arquivos. Não é possível instalar outros pacotes.

O que um componente estático não consegue manter. Quando ele é colocado na sua página, formulários, campos, quadros, SVG, manipuladores de eventos e srcset são removidos, assim como propriedades CSS personalizadas em um atributo style. Em component.css, :host não pode ser posicionado nem movido. As imagens precisam vir da sua própria biblioteca de mídia.

O que a compilação recusa. Requisições de rede, leitura de cookies ou da página ao redor, eval, HTML bruto, scripts e quadros, código que parece deliberadamente ocultado e qualquer coisa com mais de 64 KB compactada. Cada recusa aponta o arquivo e a linha.

Dicas e perguntas frequentes

• Por que não consigo editar uma versão publicada? Para que o código no seu site seja sempre exatamente o que foi verificado. Inicie uma nova versão, compile, publique e então mude o site para ela.
• Os mecanismos de busca vão ler o meu componente? Um estático, sim: ele faz parte do HTML da página. Um interativo roda em um quadro, então não de forma confiável. Deixe tudo o que as pessoas pesquisam em um componente estático ou em uma seção comum.
• Por que o meu componente estático não mudou? Ele se atualiza depois que você salva a página e depois que as informações que ele mostra mudam, normalmente em cerca de dez minutos. Algumas mudanças acontecem sem que ninguém edite nada, e essas não o atualizam: um evento que já começou, um patrocinador depois da data de término ou um jogo que virou resultado continuam como estavam até a próxima edição ou o próximo salvamento da página. Se já passou mais tempo que isso, salve a página de novo.
• Por que os dados aparecem vazios na prévia? A prévia ainda não carrega os dados do seu site. Ela mostra o componente só com as suas configurações de exemplo.
• Outros clubes podem usar o meu componente? Ainda não. Os componentes pertencem à sua organização.
• O Assistente Helix pode criar um para mim? Ele pode escrever um rascunho, compilá-lo, corrigir o que a compilação apontar e explicar o que uma mensagem de compilação significa. Publicar e instalar são sempre um clique seu.
• O que acontece se sairmos do Pro? Os seus componentes param de aparecer para os visitantes na hora. Eles são guardados e voltam quando você fizer upgrade. Você ainda pode desativá-los ou desinstalá-los.
• Para as cores e fontes que os componentes usam, veja Tema.