Componentes

Los componentes le permiten a un club del plan Pro escribir en código sus propias secciones del sitio web: una cuenta regresiva para el inicio de tu temporada, una tabla de posiciones con tus colores, cualquier cosa que las secciones incluidas no hagan. Escribes un componente en TypeScript y React, ClubHelix lo revisa y lo compila y, una vez que lo publicas y lo instalas, se agrega a cualquier página como una sección incluida.

Un componente interactivo, la opción por defecto, se ejecuta en un marco aislado en un dominio aparte. No puede ver tu administración, los datos de tus socios ni el inicio de sesión de nadie, y solo lee la información pública que tú le permitas. Un componente estático se convierte en HTML simple por adelantado y se muestra como parte de la página, sin ningún script ejecutándose en el navegador del visitante.

Quién puede usar esto

• Los administradores de tu organización pueden crear, editar, compilar, publicar, instalar, desactivar y archivar componentes.
• Un moderador al que se le otorgó el permiso Crear y editar componentes puede abrir la página y mirar, pero no puede cambiar nada.
• Los componentes son parte del plan Pro, y primero tienes que activarlos en Funciones.

Qué hay en la página

Gestión del sitio web → Componentes lista tus componentes: la última versión de cada uno, en qué punto está su compilación (en palabras, como "Compilación correcta, aún sin publicar") y si está instalado en tu sitio. Crea un componente nuevo con el formulario de la parte superior.

Abre un componente para ver:

• Código fuente: tus archivos, con index.tsx primero. Tiene que exportar el componente como exportación por defecto.
• Manifiesto (component.json): el nombre del componente, su versión, los datos que puede leer, dónde puede ir en una página y su altura máxima.
• Ajustes de ejemplo: ajustes de muestra con los que la compilación renderiza tu componente. La vista previa usa el primero.
• Compilación: cada paso de la última compilación y todos los mensajes que produjo, con el archivo y la línea.
• Vista previa: cuando una compilación salió bien, el componente ejecutándose en el mismo tipo de marco que usa tu sitio web.
• Versiones: cada versión y su estado. Elige una para abrirla.
• En tu sitio: instalar, desactivar, desinstalar o archivar.

Paso a paso

Elegir entre estático e interactivo

Define renderMode en el manifiesto:

• Interactivo ("interactive", la opción por defecto) se ejecuta en el navegador del visitante, en su propio marco. Elígelo para cualquier cosa en la que la gente haga clic o que cambie por sí sola: pestañas, calculadoras, cuentas regresivas, carruseles.
• Estático ("static") se renderiza una vez como HTML simple con los datos públicos de tu organización y se muestra como parte de la página. Los buscadores y los lectores de pantalla lo leen como el resto de la página. Nada de su código se ejecuta en el navegador del visitante, así que nada en él es interactivo: los clics, los temporizadores y las actualizaciones en vivo no hacen nada, y los efectos (useEffect) nunca se ejecutan, así que siempre muestra su primer renderizado.

Un componente estático se renderiza después de que guardas una página que lo usa, y otra vez cuando cambia la información que muestra: noticias, eventos y sus sedes, patrocinadores, equipos, programas, partidos y resultados, o el nombre y el logotipo de tu organización. Un renderizado nuevo suele aparecer en tu sitio en unos diez minutos, y un mismo componente se renderiza como mucho una vez cada cinco minutos. Mientras se prepara un renderizado nuevo, los visitantes siguen viendo el anterior, así que el componente nunca queda en blanco, y si un renderizado nuevo falla, se mantiene el último que funcionó. Hasta que el primer renderizado esté listo, los visitantes no ven nada en su lugar y tus administradores ven "Preparando este componente".

Un componente estático puede tener sus propios estilos con un archivo component.css. Esos estilos se aplican solo dentro del componente, nunca al resto de tu página. Los componentes incluidos Heading y Text toman su color y su tamaño de tu tema, así que una regla como h2 { color: … } no los va a cambiar. En su lugar, aplica estilos a tus propios elementos o nombres de clase, o agrega !important a la regla.

Escribir y compilar un componente

1. Escribe un nombre en el formulario de la parte superior de la página y haz clic en Crear componente. Empieza como un ejemplo que funciona y que puedes cambiar.
2. Edita index.tsx. Declara los ajustes que completa la gente con un esquema de zod exportado como propsSchema.
3. Cambia el manifiesto si lo necesitas; por ejemplo, agrega "events:read" a data para leer tus eventos.
4. Haz clic en Guardar borrador y luego en Compilar. Una compilación suele empezar en menos de un minuto y la página se actualiza sola.
5. Si la compilación falla, lee los mensajes de Compilación, corrige el archivo y la línea que indican, guarda y vuelve a compilar.

Pedirle al asistente que redacte uno

Abre el Asistente Helix en esta página y describe lo que quieres, por ejemplo: "Crea una cuenta regresiva para el inicio de nuestra temporada el 7 de marzo". Te muestra los archivos y lo que va a leer el componente. Cuando haces clic en Aplicar, guarda un borrador y empieza una compilación, y el asistente te muestra cómo va. Si la compilación falla, haz clic en Corregir los errores de compilación: el asistente recibe los mensajes de la propia compilación y te devuelve un borrador corregido. Cada ronda usa una de tus consultas diarias, y tienes hasta cinco rondas por componente en un chat. El asistente nunca publica ni instala un componente. Tú revisas la vista previa y haces esos pasos.

Publicarlo e instalarlo

1. Cuando la compilación salió bien, revisa la Vista previa y luego haz clic en Publicar. Una versión publicada no se puede cambiar; los cambios posteriores van en una versión nueva (Empezar una nueva versión).
2. En En tu sitio, lee lo que el componente va a poder ver y luego haz clic en Instalar.
3. En el editor de páginas, agrega una sección Componente personalizado, elige tu componente y completa sus ajustes.
4. Guarda la página. Un componente estático aparece en ella a los pocos minutos de guardarla.

Pasar tu sitio a una versión nueva

1. Haz clic en Empezar una nueva versión, haz tus cambios y luego compílala y publícala.
2. En En tu sitio, haz clic en Cambiar el sitio a la versión nueva. Todas las páginas que muestran el componente pasan a ella al mismo tiempo, así que no hay nada que cambiar en las páginas.
3. Si la versión nueva cambió sus ajustes, revisa cada página que la usa. Una sección cuyos ajustes la versión nueva no acepta deja de mostrarse hasta que los corrijas en el editor de páginas.

Quitarlo de tu sitio

• Desactivar deja de mostrarlo en todas partes de inmediato. Volver a activar lo recupera.
• Desinstalar quita la instalación. Archivar oculta el componente y lo desactiva.

Referencia de campos

Qué puede importar un componente. react, zod y @clubhelix/component-sdk (títulos, texto, botones, imágenes, una cuenta regresiva y más, con los estilos de tu tema), además de sus propios archivos. No se pueden instalar otros paquetes.

Qué no puede conservar un componente estático. Cuando se incorpora a tu página, se quitan los formularios, los campos de entrada, los marcos, los SVG, los manejadores de eventos y srcset, y también las propiedades personalizadas de CSS en un atributo style. En component.css, :host no se puede posicionar ni mover. Las imágenes tienen que venir de tu propia biblioteca de medios.

Qué rechaza la compilación. Solicitudes de red, leer cookies o la página que lo rodea, eval, HTML sin procesar, scripts y marcos, código que parece ocultado a propósito y cualquier cosa de más de 64 KB comprimida. Cada rechazo indica el archivo y la línea.

Consejos y preguntas frecuentes

• ¿Por qué no puedo editar una versión publicada? Para que el código de tu sitio sea siempre exactamente el que se revisó. Empieza una versión nueva, compílala, publícala y luego cambia el sitio a ella.
• ¿Los buscadores van a leer mi componente? Uno estático, sí: es parte del HTML de la página. Uno interactivo se ejecuta en un marco, así que no de forma confiable. Pon todo lo que la gente busca en un componente estático o en una sección común.
• ¿Por qué no cambió mi componente estático? Se actualiza después de que guardas la página y después de que cambia la información que muestra, normalmente en unos diez minutos. Algunos cambios ocurren sin que nadie edite nada, y esos no lo actualizan: un evento que ya empezó, un patrocinador que pasó su fecha de finalización o un partido que ya tiene resultado se quedan como estaban hasta la próxima edición o hasta que se guarde la página. Si pasó más tiempo que eso, vuelve a guardar la página.
• ¿Por qué los datos están vacíos en la vista previa? La vista previa todavía no carga los datos de tu sitio. Muestra el componente solo con tus ajustes de ejemplo.
• ¿Otros clubes pueden usar mi componente? Todavía no. Los componentes pertenecen a tu organización.
• ¿El Asistente Helix puede crear uno por mí? Puede redactar uno, compilarlo y corregir lo que indique la compilación, y explicarte qué significa un mensaje de compilación. Publicar e instalar siempre dependen de tu clic.
• ¿Qué pasa si dejamos el plan Pro? Tus componentes dejan de mostrarse a los visitantes de inmediato. Se conservan y vuelven cuando mejoras tu plan. Igual puedes desactivarlos o desinstalarlos.
• Para los colores y las fuentes que toman los componentes, consulta Tema.