Tags de texto: noções básicas e sintaxe

Entenda a estrutura exata que as tags de texto exigem para que seus campos sejam reconhecidos corretamente e funcionem conforme o esperado.

As tags de texto permitem criar campos de formulário digitando espaços reservados estruturados diretamente no seu documento. São rápidas e poderosas, mas só funcionam quando a sintaxe está exata.

Esta página explica a estrutura necessária de uma tag de texto, o que cada parte faz e as regras que devem ser seguidas para que as tags sejam reconhecidas corretamente.

Delimitador de tag obrigatório (chaves)

Toda tag de texto deve estar delimitada por chaves duplas:

{field-name_es_:signer-role:field-type:directive1:directive2}}

As chaves são obrigatórias e têm duas finalidades:

• Indicam ao Acrobat Sign onde a tag de texto começa e termina.
• Definem a largura e altura iniciais do campo gerado.
  • O tamanho (fonte) da primeira chave determina a altura do campo. 
    • Um tamanho da fonte maior na primeira chave cria campos mais altos.
    • O restante da etiqueta pode ter um tamanho de fonte diferente, mas deve ser de 2 pt ou maior.
  • O espaço entre as chaves (incluindo as próprias chaves) determina a largura geral do campo. 
    • Espaçamento maior entre chaves cria campos mais largos
    • Espaços em branco são importantes.

Se as chaves estiverem faltando ou estiverem malformadas, o texto será tratado como texto simples, nenhum campo será criado e você verá o texto da tag impresso no seu formulário após o upload.

Para obter uma orientação mais ampla sobre tags de texto e quando usá-las, consulte Visão geral das tags de texto.

A estrutura necessária de uma tag de texto

Dentro das chaves, todas as tags de texto devem seguir esta estrutura:

field-name_es_:signer-role:field-type:directive1:directive2

Esta estrutura é rigorosa. Reordenar elementos ou omitir partes obrigatórias pode resultar em falha silenciosa ou comportamento não intencional.

Elementos obrigatórios (em ordem)

Nome do campo

O nome do campo identifica o campo do formulário no Acrobat Sign.

• Deve ser único dentro do documento.
• Não deve conter espaços.
• É usado para relatórios e extração de dados.

Identificador _es_

O identificador _es_ informa ao Acrobat Sign que o texto representa uma tag de texto.

• _es_ é obrigatório.
• Sem isso, a tag é tratada como texto simples.

Função do signatário

A função do signatário define a qual destinatário o campo pertence.

• Sempre inclua uma função de signatário.
• A função do signatário deve incluir um número para indicar para qual destinatário o campo se destina. 

Funções de signatário compatíveis

As tags de texto atribuem campos aos destinatários usando funções posicionais do signatário.

O formato de função de signatário compatível é:

:signerN

Onde N é um número que começa em 1 e corresponde à posição do destinatário na ordem de assinatura.

Exemplos:

• :signer1 — primeiro destinatário
• :signer2 — segundo destinatário
• :signer3 — terceiro destinatário

Não há limite máximo imposto pelas próprias tags de texto. Uma função de signatário deve corresponder a um destinatário real no contrato para que o campo seja atribuído.

As tags de texto não suportam funções nomeadas ou semânticas. Apenas funções de signatário posicionais são reconhecidas.

A exceção à regra é a função :prefill:

• :prefill — Campos atribuídos ao remetente do contrato e que devem ser preenchidos após o envio do contrato, mas antes da notificação do primeiro signatário.
  • Nenhum número é usado porque essa posição acontece antes do ciclo de assinatura real.

Tipo de campo

O tipo de campo determina o tipo de campo de formulário criado.

Exemplos comuns incluem:

• :text
• :signature
• :date
• :checkbox

Apenas tipos de campo compatíveis são reconhecidos. Tipos de campo não compatíveis são ignorados.

Para obter a lista completa e o comportamento específico do campo, consulte Tipos de campo compatíveis com tags de texto.

Diretivas (opcional)

As diretivas modificam o comportamento do campo.

Alguns exemplos incluem:

• :required
• :tooltip()
• :readOnly
• :calc()
• :format()

As diretivas devem aparecer após o tipo de campo e devem seguir a sintaxe correta.

Para interações complexas de diretivas, consulte Comportamentos avançados de tags de texto.

Exemplo: uma tag de texto completa e válida

{full_name_es_:signer1:text:required:tooltip(Enter your full legal name)}}

Esta tag:

• Usa chaves para definir o limite e o tamanho do campo
• Cria um campo de texto
• Atribui ao primeiro signatário
• Torna obrigatório
• Exibe uma dica de ferramenta para o signatário

Para exemplos simples e compostos adicionais, consulte Exemplos de tags de texto.

Regras importantes para entender desde o início

As tags de texto são implacáveis por natureza. Tenha em mente estas regras:

• As tags são processadas quando o documento é carregado.
• Não há validação durante a criação.
• Os erros não geram avisos.
• As tags malformadas são tratadas como texto simples.

Se algo não funcionar, considere primeiro um problema de sintaxe e verifique Solução de problemas com tags de texto.