Backend del sitio (handlers dinámicos)
Además de sus archivos estáticos, un sitio web subido puede tener un backend real: pequeños handlers en JavaScript asociados a direcciones concretas. Cada handler se vincula a una ruta y a un método HTTP; cuando un visitante abre esa dirección, Qubix ejecuta el handler y devuelve lo que este construye: una página, una respuesta JSON, una redirección o un código de estado.
Úselo cuando una página deba hacer algo en el servidor en lugar de solo mostrar contenido estático: aceptar un lead mediante una petición POST, responder a una ruta concreta con HTML generado o enviar una redirección según la petición. Para whitepages y landings estáticas corrientes no necesita esto: deje la pestaña Backend vacía y el sitio web se sirve como archivos planos.
Abrir la pestaña Backend
La tarjeta de un sitio web tiene tres pestañas en la parte superior: Archivos, Backend y Vista previa. La pestaña activa se guarda en la barra de direcciones, de modo que puede copiar un enlace directamente a una pestaña concreta.
- Abra la sección «Sitios web» y haga clic en el sitio web que necesite.
- Cambie a la pestaña Backend.
Si el sitio web aún no tiene handlers, la lista muestra la indicación de que «+ nuevo» crea uno a partir de una plantilla.
La pestaña Backend solo es necesaria cuando la página debe procesar algo en el servidor. Una página puramente estática funciona sin ningún handler.
Crear un handler
- En la pestaña Backend, haga clic en «+ nuevo» en la parte superior izquierda, encima de la lista de handlers. Se crea un nuevo handler a partir de una plantilla lista para usar y se abre en el editor.
🎬 GIF: clic en «+ nuevo» y apertura del handler de plantilla en el editor
- En el formulario de cabecera situado encima del editor, establezca la ruta — la dirección en la que responde el handler. El campo acepta una plantilla con marcadores de posición (por ejemplo,
/users/:id)::name— captura un segmento de ruta (por ejemplo,:iden/users/:idcoincide con/users/42);*— captura el resto de la ruta a lo largo de varios segmentos;**— coincide con el resto de la ruta sin capturarlo.
- Elija el método —
GET,POST,PUT,DELETE,PATCH,HEAD,OPTIONSo ANY (responde a cualquier método). - Mantenga activada la casilla enabled para que el handler funcione en el sitio activo. Desactívela para mantener un handler guardado pero inactivo.
- En el editor central, escriba el código del handler (consulte El código del handler más abajo).
- Haga clic en Guardar (o Cmd+S, en Windows — Ctrl+S).
En la lista de la izquierda, cada handler se muestra con su método y su ruta (un handler sin método establecido se muestra como ANY); uno desactivado se marca como tal.
Si más de un handler pudiera responder a la misma dirección, Qubix elige el más específico — un handler con una ruta exacta gana a uno con un marcador de posición o un comodín. Así puede mantener un handler preciso junto a un catch-all amplio sin que entren en conflicto.
El código del handler
Un handler es una función JavaScript que recibe un objeto de petición —llámelo r— que expone la petición (método, ruta, argumentos de query y de formulario, cabeceras, los segmentos de ruta capturados) y la respuesta (establecer cabeceras, devolver un estado con un cuerpo o una redirección). La plantilla con la que arranca el editor ya muestra la forma típica.
El editor es un editor de código completo con resaltado de sintaxis y autocompletado: empiece a escribir r. y Qubix sugiere los campos disponibles de la petición y la respuesta con sus descripciones, para que no tenga que memorizarlos.
Dentro de un handler también dispone del conjunto de herramientas compartido de Qubix: consultas de solo lectura a la base de datos, peticiones a servicios externos y estado que persiste entre llamadas. Funcionan igual que en Scripts — consulte ese artículo para los detalles. Las peticiones salientes solo se permiten a direcciones que el administrador haya añadido a la lista de permitidos. Qué tablas y columnas puede alcanzar una consulta está en Tablas para consultas sql.
Referencia del objeto r
Todo lo que el handler lee de la petición y utiliza para construir la respuesta.
Lectura de la petición:
| Campo | Qué es |
|---|---|
r.method | El método HTTP de la petición (GET, POST, …) |
r.uri | La dirección en la que respondió el handler (por ejemplo, /promo/123) |
r.rawUri | La dirección externa completa, incluido el prefijo de servicio |
r.args | Los parámetros de dirección y de formulario (clave → valor) |
r.params | Los valores capturados de la plantilla de ruta (por ejemplo, id de /users/:id) |
r.requestBuffer | El cuerpo de la petición como cadena de texto |
r.headersIn | Las cabeceras de la petición |
r.remoteAddress | La IP del visitante |
r.variables | El contexto del clic: geo, click_id, sub1…sub5, lang |
r.session | La sesión del visitante: get(key), set(key, value), delete(key) |
Construcción de la respuesta:
| Campo / método | Acción |
|---|---|
r.headersOut | Las cabeceras de la respuesta (se pueden establecer y eliminar) |
r.return(status, body?, location?) | Enviar la respuesta; location es la dirección de redirección |
r.log(...), r.warn(...), r.error(...) | Escribir en el log de ejecución (visible en el ejecutor de pruebas) |
Funciones criptográficas
Un handler también dispone de funciones criptográficas:
| Método | Qué hace |
|---|---|
crypto.uuid() | Un identificador aleatorio |
crypto.hmac(algo, key, data) | HMAC de data con key, codificado en hexadecimal; algo es 'sha256', 'sha1' o 'md5' |
Resulta útil, por ejemplo, para firmar datos antes de enviarlos a un servicio externo mediante fetch.
Probar un handler
Cada handler tiene un ejecutor de pruebas integrado a la derecha del editor: envíe una petición de prueba y vea exactamente qué responde el handler, sin tocar el sitio activo.
- Elija el método e introduzca la ruta que va a probar (por ejemplo,
/users/42). - (Opcional) Rellene las entradas de la petición:
- Consulta (JSON) — parámetros de query como un objeto JSON;
- Cuerpo (raw) — el cuerpo de la petición en bruto;
- geo y click_id — valores que se pasan al handler como variables de la petición.
- Haga clic en Ejecutar.
El resultado aparece debajo:
- el estado de la respuesta (coloreado en verde / azul / rojo) y cuánto tardó la ejecución;
- parámetros — los valores capturados de la plantilla de ruta;
- Redirección — el destino de la redirección, si el handler estableció uno;
- las encabezados y el cuerpo de la respuesta;
- la consola — todo lo que el handler registró durante la ejecución.
Si la petición alcanza o cambia el estado almacenado del handler, el panel también marca la sesión como afectada.
Consulta (JSON) debe ser JSON válido. Si no lo es, la prueba no se ejecuta y el campo se resalta — corrija el JSON y haga clic en Ejecutar de nuevo.
Editar los archivos del sitio
La otra mitad de la tarjeta es la pestaña Archivos — los archivos estáticos del sitio web (HTML, CSS, JS, imágenes, fuentes) en un árbol a la izquierda y un editor de código a la derecha. Los archivos de texto se abren con resaltado de sintaxis; guarde con Guardar o Cmd+S (en Windows — Ctrl+S). Las imágenes, el vídeo, el audio y otros archivos obtienen una vista previa o una descarga. Puede arrastrar archivos entre carpetas y soltar nuevos desde su ordenador.
Encontrará un desglose completo de la pestaña Archivos en Sitios web y Subir un sitio web.
Notas sobre campos y comportamiento
ruta — la plantilla de dirección en la que responde el handler. Admite :name (un segmento), * (el resto, capturado) y ** (el resto, no capturado). Los segmentos capturados están disponibles para el handler y se muestran como params en el ejecutor de pruebas.
method — qué método HTTP activa el handler. ANY responde a todos los métodos.
enabled — si el handler se ejecuta en el sitio activo. Un handler desactivado permanece guardado pero se omite.
«+ nuevo» — crea un handler a partir de la plantilla integrada, listo para editar.