Backend do site (manipuladores dinâmicos)
Além dos seus arquivos estáticos, um site enviado pode ter um backend de verdade — pequenos manipuladores em JavaScript vinculados a endereços individuais. Cada manipulador é associado a um caminho e a um método HTTP; quando um visitante abre esse endereço, o Qubix executa o manipulador e retorna o que ele construir — uma página, uma resposta JSON, um redirecionamento, um código de status.
Use-o quando uma página precisar fazer algo no servidor em vez de apenas mostrar conteúdo estático: aceitar um lead por uma requisição POST, responder a um caminho específico com HTML gerado, ou enviar um redirecionamento dependendo da requisição. Para whitepages e landings estáticas comuns você não precisa disso — deixe a aba Backend vazia e o site é servido como arquivos puros.
Abra a aba Backend
Um cartão de site tem três abas no topo: Arquivos, Backend e Pré-visualização. A aba ativa é salva na barra de endereço, então você pode copiar um link direto para uma aba específica.
- Abra a seção «Sites» e clique no site que você precisa.
- Mude para a aba Backend.
Se o site ainda não tiver manipuladores, a lista mostra a dica de que «+ novo» cria um a partir de um modelo.
A aba Backend só é necessária quando a página precisa processar algo no servidor. Uma página puramente estática funciona sem nenhum manipulador.
Crie um manipulador
- Na aba Backend, clique em «+ novo» no canto superior esquerdo, acima da lista de manipuladores. Um novo manipulador é criado a partir de um modelo pronto e abre no editor.
🎬 GIF: clicando em «+ novo» e o manipulador-modelo abrindo no editor
- No formulário de cabeçalho acima do editor, defina o caminho — o endereço no qual o manipulador responde. O campo aceita um modelo com placeholders (por exemplo,
/users/:id)::name— captura um segmento do caminho (por exemplo,:idem/users/:idcorresponde a/users/42);*— captura o restante do caminho ao longo de vários segmentos;**— corresponde ao restante do caminho sem capturá-lo.
- Escolha o método —
GET,POST,PUT,DELETE,PATCH,HEAD,OPTIONSou ANY (responde a qualquer método). - Mantenha a caixa de seleção Lig. marcada para que o manipulador funcione no site ativo. Desmarque-a para manter um manipulador salvo, porém inativo.
- No editor central, escreva o código do manipulador (veja O código do manipulador abaixo).
- Clique em Salvar (ou Cmd+S, no Windows — Ctrl+S).
Na lista à esquerda, cada manipulador é exibido como seu método e caminho (um manipulador sem método definido é exibido como ANY); um desativado é marcado conforme.
Se mais de um manipulador puder responder ao mesmo endereço, o Qubix escolhe o mais específico — um manipulador com um caminho exato vence um com placeholder ou curinga. Assim você pode manter um manipulador preciso ao lado de um catch-all amplo sem que entrem em conflito.
O código do manipulador
Um manipulador é uma função JavaScript que recebe um objeto de requisição — chame-o de r — que expõe a requisição (método, caminho, argumentos de query e de formulário, cabeçalhos, os segmentos de caminho capturados) e a resposta (definir cabeçalhos, retornar um status com um corpo, ou um redirecionamento). O modelo do qual o editor parte já mostra o formato típico.
O editor é um editor de código completo, com realce de sintaxe e autocompletar: comece a digitar r. e o Qubix sugere os campos de requisição e resposta disponíveis com suas descrições, para que você não precise mantê-los na cabeça.
Dentro de um manipulador você também conta com o conjunto de ferramentas compartilhado do Qubix: consultas somente leitura ao banco de dados, requisições a serviços externos e estado que persiste entre chamadas. Eles funcionam do mesmo modo que em Scripts — consulte aquele artigo para os detalhes. Requisições de saída só são permitidas para endereços que o administrador colocou na allowlist. Quais tabelas e colunas uma consulta pode acessar está em Tabelas para consultas sql.
Referência do objeto r
Tudo o que o manipulador lê da requisição e utiliza para construir a resposta.
Lendo a requisição:
| Campo | O que é |
|---|---|
r.method | O método HTTP da requisição (GET, POST, …) |
r.uri | O endereço em que o manipulador respondeu (por exemplo, /promo/123) |
r.rawUri | O endereço externo completo, incluindo o prefixo de serviço |
r.args | Os parâmetros de endereço e de formulário (chave → valor) |
r.params | Valores capturados do modelo de caminho (por exemplo, id de /users/:id) |
r.requestBuffer | O corpo da requisição como string |
r.headersIn | Os cabeçalhos da requisição |
r.remoteAddress | O IP do visitante |
r.variables | O contexto do clique: geo, click_id, sub1…sub5, lang |
r.session | A sessão do visitante: get(key), set(key, value), delete(key) |
Construindo a resposta:
| Campo / método | Ação |
|---|---|
r.headersOut | Os cabeçalhos da resposta (você pode defini-los e excluí-los) |
r.return(status, body?, location?) | Envia a resposta; location é o endereço de redirecionamento |
r.log(...), r.warn(...), r.error(...) | Grava no log de execução (visível no executor de testes) |
Auxiliares de criptografia
Um manipulador também dispõe de auxiliares de criptografia:
| Método | O que faz |
|---|---|
crypto.uuid() | Um identificador aleatório |
crypto.hmac(algo, key, data) | HMAC de data com key, codificado em hexadecimal; algo é 'sha256', 'sha1' ou 'md5' |
Útil, por exemplo, para assinar dados antes de enviá-los a um serviço externo via fetch.
Teste um manipulador
Cada manipulador tem um executor de testes integrado à direita do editor — envie uma requisição de teste e veja exatamente o que o manipulador responde, sem mexer no site ativo.
- Escolha o método e informe o caminho a testar (por exemplo,
/users/42). - (Opcional) Preencha os dados de entrada da requisição:
- Consulta (JSON) — parâmetros de query como um objeto JSON;
- Corpo (raw) — o corpo bruto da requisição;
- geo e click_id — valores passados ao manipulador como variáveis da requisição.
- Clique em Executar.
O resultado aparece abaixo:
- o status da resposta (colorido em verde / azul / vermelho) e quanto tempo a execução levou;
- parâmetros — os valores capturados do modelo de caminho;
- Redirecionamento — o destino do redirecionamento, se o manipulador definiu um;
- os cabeçalhos e o corpo da resposta;
- o console — tudo o que o manipulador registrou durante a execução.
Se a requisição acessa ou altera o estado armazenado do manipulador, o painel também marca a sessão como tocada.
Consulta (JSON) deve ser um JSON válido. Se não for, o teste não será executado e o campo é destacado — corrija o JSON e clique em Executar novamente.
Edite os arquivos do site
A outra metade do cartão é a aba Arquivos — os arquivos estáticos do site (HTML, CSS, JS, imagens, fontes) em uma árvore à esquerda e um editor de código à direita. Arquivos de texto abrem com realce de sintaxe; salve com Salvar ou Cmd+S (no Windows — Ctrl+S). Imagens, vídeo, áudio e outros arquivos recebem uma pré-visualização ou um download. Você pode arrastar arquivos entre pastas e soltar novos a partir do seu computador.
Um detalhamento completo da aba Arquivos está em Sites e Enviando um site.
Notas sobre campos e comportamento
caminho — o modelo de endereço no qual o manipulador responde. Suporta :name (um segmento), * (o restante, capturado) e ** (o restante, não capturado). Os segmentos capturados ficam disponíveis ao manipulador e são exibidos como parâmetros no executor de testes.
método — qual método HTTP aciona o manipulador. ANY responde a todos os métodos.
Lig. — se o manipulador é executado no site ativo. Um manipulador desativado permanece salvo, mas é ignorado.
«+ novo» — cria um manipulador a partir do modelo integrado, pronto para editar.