Campos e validação

Campos são opcionais. Um formulário sem campos aceita quaisquer dados que o seu formulário enviar. Depois que você publica os campos, o Ikiform valida cada envio contra eles no servidor, rejeita dados ruins com mensagens claras e armazena valores limpos e tipados.

Definindo campos

Abra um formulário no painel e vá em Fields. Adicione campos no editor visual ou edite a definição JSON diretamente. O id de cada campo é o name do input que o seu formulário precisa enviar.

{
  "version": 1,
  "title": "Contact",
  "fields": [
    { "id": "name", "type": "text", "label": "Name", "required": true, "validation": { "max_length": 120 } },
    { "id": "email", "type": "email", "label": "Email", "required": true },
    {
      "id": "topic",
      "type": "select",
      "label": "Topic",
      "options": [
        { "value": "sales", "label": "Sales" },
        { "value": "support", "label": "Support" }
      ]
    },
    { "id": "message", "type": "textarea", "label": "Message", "validation": { "min_length": 10 } }
  ],
  "settings": { "submit_label": "Send", "success_message": "Thanks, we'll reply within a day." }
}

A definição

Chaves desconhecidas são recusadas, no nível superior e em cada campo, então um erro de digitação como requried aparece como erro quando você salva.

Chaves de todo campo

Playground

{
  "ok": true,
  "id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3"
}

Tipos de campo

text

Os patterns rodam com a flag u e precisam corresponder ao valor inteiro. Quando você salva, o Ikiform recusa patterns que poderiam causar backtracking catastrófico: backreferences, grupos repetidos que contêm repetições ou alternativas ((a+)+, (a|b)*) e repetições aninhadas demais.

textarea

email

Endereços com mais de 254 caracteres são recusados. A parte do domínio é armazenada em minúsculas; a parte antes do @ é mantida como foi enviada.

number

select, radio e multi_select

Só valores da lista são aceitos. select e radio aceitam um valor; envie multi_select como nomes repetidos, name[] ou um array JSON.

checkbox

Sem chaves extras. Um checkbox ausente é false. required: true significa que ele precisa estar marcado, o que serve para caixas de consentimento. Valores diferentes de on, true, 1, yes, off, false, 0, no ou vazio são recusados.

date

url

Só URLs http: e https: com um nome de host com ponto e sem usuário ou senha são aceitas. O valor armazenado é a URL normalizada.

phone

Sem e164, um telefone precisa ter de 6 a 15 dígitos e é armazenado como foi enviado. Com ele, +1 (415) 555-0123 é armazenado como +14155550123.

rating

Conversão de tipos

Formulários HTML enviam tudo como texto. O Ikiform converte cada valor para o tipo que o campo declara antes de armazenar. Com name como texto, email, guests como número, newsletter como checkbox, site como URL e phone como telefone:

name=++Ada+Lovelace++&email=Ada@Example.COM&guests=3&newsletter=on&site=example.com&phone=%2B1%20415%20555%200123

{
  "name": "Ada Lovelace",
  "email": "Ada@example.com",
  "guests": 3,
  "newsletter": true,
  "site": "https://example.com/",
  "phone": "+14155550123"
}

• Os valores passam por trim. Uma string vazia conta como ausente.
• Um campo que espera um valor recusa um array com mais de um item.
• Números aceitam notação decimal simples e exponencial com até 64 caracteres, como 3, -2.5 ou 1e3.

Erros de validação

Um envio que falha na validação é rejeitado com 422 validation_failed e nada é armazenado. error.fields associa cada id de campo às suas mensagens. Envios pelo navegador veem as mesmas mensagens em uma página de erro hospedada, identificadas pelos rótulos dos seus campos.

{
  "ok": false,
  "error": {
    "code": "validation_failed",
    "message": "Some fields are invalid.",
    "fields": {
      "email": ["Enter a valid email address"],
      "website": ["Unknown field \"website\""]
    }
  },
  "request_id": "req_01k7v2c9t3e8m5q4x6z0a1b2c3"
}

Campos desconhecidos

Com campos definidos, qualquer campo que não está na definição é rejeitado como Unknown field "name". Campos reservados que começam com _, o honeypot e cf-turnstile-response não contam. Sem definição, quaisquer nomes de campo são aceitos.

Mensagens

Validando no navegador

O validate do SDK espelha as regras e mensagens do servidor para os 12 tipos de campo, então você pode mostrar erros antes de enviar. O servidor continua sendo a fonte da verdade. Veja validate.