Pular para o conteúdo principal

getFormByMarker

Obtendo um objeto de formulário por marcador.

Descrição​

Este método recupera um único objeto de formulário com base em seu identificador textual (marcador) da API. Ele retorna uma Promise que resolve para um objeto FormEntity.

.getFormByMarker(

,

);

Esquema de parâmetros​

Esquema

marker(obrigatório): string
Marcador do formulário
exemplo: "contact_form"

langCode: string
Códigodo idioma. Padrão: "en_US"
exemplo: "en_US"

Exemplos​

Exemplo mínimo​

const response = await Forms.getFormByMarker('my-form');

Exemplo com atributos​

const response = await Forms.getFormByMarker('my-form', 'en_US');

Exemplo de resposta​

{
  "id": 6,
  "attributeSetId": 15,
  "type": "data",
  "localizeInfos": {
    "title": "Test form",
    "titleForSite": "",
    "successMessage": "",
    "unsuccessMessage": "",
    "urlAddress": "",
    "database": "0",
    "script": "0"
  },
  "version": 15,
  "position": 1,
  "identifier": "test-form",
  "processingType": "script",
  "templateId": null,
  "attributes": [
    {
      "type": "string",
      "marker": "name",
      "position": 1,
      "settings": {},
      "isVisible": true,
      "listTitles": [],
      "validators": {
        "requiredValidator": {
          "strict": true
        },
        "stringInspectionValidator": {
          "stringMax": 0,
          "stringMin": 0,
          "stringLength": 0
        }
      },
      "multiselect": false,
      "initialValue": null,
      "localizeInfos": {
        "title": "Name"
      },
      "additionalFields": {
        "additional_field": {
          "type": "string",
          "value": "Additional field data"
        }
      }
    },
    {
      "type": "file",
      "marker": "file",
      "position": 2,
      "settings": {},
      "isVisible": true,
      "listTitles": [],
      "validators": {},
      "multiselect": false,
      "initialValue": null,
      "localizeInfos": {
        "title": "File"
      },
      "additionalFields": {}
    }
  ],
  "total": "1",
  "moduleFormConfigs": [
    {
      "id": 2,
      "formId": 6,
      "moduleId": 4,
      "moduleIdentifier": "content",
      "isGlobal": false,
      "isModerate": false,
      "isClosed": false,
      "viewOnlyUserData": false,
      "commentOnlyUserData": false,
      "entityIdentifiers": [
        {
          "id": "blog",
          "isNested": false
        }
      ],
      "ratingCalculation": "average",
      "allowHalfRatings": null,
      "maxRatingScale": null,
      "isAnonymous": null,
      "allowRerating": null,
      "isRating": null
    }
  ]
}

Esquema de resposta​

Esquema: IFormsEntity

id: number
O identificador do objeto.
exemplo: 12345

attributeSetId: number | null
O identificador do conjunto de atributos sendo usado, ou null se não aplicável.
exemplo: 1234

type: string | null
Tipo de formulário.
exemplo: "contact"

localizeInfos: IFormLocalizeInfo
O nome do formulário e campos de localização do lado do formulário (mensagens de sucesso/erro, configuração de processamento, etc.).
exemplo:

{
  "key": "value"
}

localizeInfos.title: string
Nome localizado do formulário. Opcional — o payload é um objeto vazio quando o formulário não tem localização para o idioma solicitado (por exemplo, em respostas de lista).
exemplo: "Formulário de contato"

localizeInfos.titleForSite: string
Título visível ao público exibido no site.
exemplo: "Título do formulário (para aplicação)"

localizeInfos.successMessage: string
Mensagem exibida ao usuário após o envio bem-sucedido.

localizeInfos.unsuccessMessage: string
Mensagem exibida ao usuário após um envio falho.

localizeInfos.urlAddress: string
URL onde os dados do formulário são enviados para processamento (usado por processingType: "url").

localizeInfos.database: string
Flag/id do banco de dados usado pelo processador de formulários (tipado como string na API: "0" / "1" / id).

localizeInfos.script: string
Flag/id do script usado pelo processador de formulários (tipado como string na API: "0" / "1" / id).

version: number
O número da versão do objeto.
exemplo: 1

position: number
A posição do objeto.
exemplo: 1

identifier: string
O identificador textual para o campo do registro.
exemplo: "form_contact_us"

processingType: string
Tipo de processamento do formulário.
exemplo: "async"

templateId: number | null
O identificador do template usado pelo formulário, ou null se nenhum template for usado.
exemplo: 6789

attributes: IFormAttribute[]
Campos do formulário com sua localização, validadores e flags específicas do formulário, ordenados por position. A API retorna um objeto vazio para formulários sem atributos — o SDK normaliza isso para um array vazio.

attributes.marker: string
Marcador do campo (nome da máquina).
exemplo: "email"

attributes.type: AttributeType
Tipo de dado do atributo (por exemplo, "string", "file").

attributes.position: number
Posição de ordenação do campo.
exemplo: 1

attributes.isVisible: boolean
Se o campo é exposto ao usuário.
exemplo: true

attributes.localizeInfos: IAttributeLocalizeInfo
Rótulos localizados para o campo. Para atributos timeInterval, também carrega o payload de intervals.

attributes.initialValue: unknown
Valor padrão aplicado quando o campo não é preenchido.

attributes.listTitles: IListTitle[]
Opções predefinidas para campos list/radioButton; array vazio para outros tipos.

attributes.multiselect: boolean
Para campos list — se várias opções de listTitles podem ser selecionadas. Opcional.
exemplo: false

attributes.validators: IAttributeValidators
Regras de validação; objeto vazio quando nenhum validador está configurado.

attributes.settings: Record<string, unknown>
Configuração específica do campo; objeto vazio por padrão.

attributes.additionalFields: Record<string, IFormAttributeAdditionalField>
Subcampos aninhados indexados por marcador; objeto vazio quando nenhum.

attributes.isLogin: boolean
Se este campo carrega o valor de login usado para autenticação. Opcional — presente apenas em atributos de formulários de login/cadastro.
exemplo: false

attributes.isSignUp: boolean
Se este campo é obrigatório durante o cadastro. Opcional — presente apenas em atributos de formulários de login/cadastro.
exemplo: false

attributes.isPassword: boolean
Se este campo carrega o valor de senha usado para autenticação. Opcional — presente apenas em atributos de formulários de login/cadastro.
exemplo: false

attributes.isSignUpRequired: boolean
Se este campo é obrigatório durante o cadastro. Opcional — presente apenas em atributos de formulários de login/cadastro.
exemplo: false

attributes.isNotificationEmail: boolean
Se este campo armazena o email usado para notificações. Opcional — presente apenas em atributos de formulários de login/cadastro.
exemplo: false

attributes.isNotificationPhonePush: boolean
Se este campo armazena o número de telefone usado para notificações push. Opcional — presente apenas em atributos de formulários de login/cadastro.
exemplo: false

attributes.isNotificationPhoneSMS: boolean
Se este campo armazena o número de telefone usado para notificações SMS. Opcional — presente apenas em atributos de formulários de login/cadastro.
exemplo: false

total: number | string
Contagem total de entradas relacionadas.
exemplo: "1"

moduleFormConfigs: IFormConfig[]
Array de configurações de formulário de módulo associadas ao formulário.

moduleFormConfigs.id: number
O identificador da configuração do formulário.
exemplo: 123

moduleFormConfigs.formIdentifier: string
O identificador do formulário (apenas na API de produtos/páginas).
exemplo: "review"

moduleFormConfigs.moduleIdentifier: string
O identificador do módulo associado à configuração do formulário.
exemplo: "module_identifier"

moduleFormConfigs.isGlobal: boolean
Indica se a configuração do formulário é global.
exemplo: true

moduleFormConfigs.isClosed: boolean
Indica se a configuração do formulário está fechada.
exemplo: true

moduleFormConfigs.isModerate: boolean
Indica se o formulário requer moderação (apenas na API de produtos/páginas).
exemplo: false

moduleFormConfigs.viewOnlyUserData: boolean
Indica se a configuração do formulário permite visualizar dados do usuário (usado na API de formulários).
exemplo: true

moduleFormConfigs.commentOnlyUserData: boolean
Indica se a configuração do formulário permite comentar sobre dados do usuário (usado na API de formulários).
exemplo: true

moduleFormConfigs.viewOnlyMyData: boolean
Indica se a configuração do formulário permite visualizar meus dados (usado na API de produtos/páginas).
exemplo: false

moduleFormConfigs.commentOnlyMyData: boolean
Indica se a configuração do formulário permite comentar sobre meus dados (usado na API de produtos/páginas).
exemplo: false

moduleFormConfigs.entityIdentifiers: object[]
Um array de identificadores de entidades associadas à configuração do formulário.

moduleFormConfigs.nestedEntityIdentifiers: string[]
Um array de strings de identificadores de entidades aninhadas (apenas na API de produtos/páginas).
exemplo: ["catalog"]

moduleFormConfigs.exceptionIds: string[]
Um array de identificadores de exceção.

moduleFormConfigs.formDataCount: number
Contagem total de entradas de dados do formulário (apenas na API de produtos/páginas).
exemplo: 306

moduleFormConfigs.entityFormDataCount: Record<string, number>
Contagem de dados do formulário por identificador de entidade (apenas na API de produtos/páginas).
exemplo:

{"catalog": 306}

moduleFormConfigs.isRating: boolean | null
Indica se esta configuração de formulário é para avaliações.
exemplo: null

moduleFormConfigs.isAnonymous: boolean | null
Indica se envios anônimos são permitidos.
exemplo: null

moduleFormConfigs.allowHalfRatings: boolean | null
Indica se avaliações parciais são permitidas.
exemplo: null

moduleFormConfigs.allowRerating: boolean | null
Indica se reavaliações são permitidas.
exemplo: null

moduleFormConfigs.maxRatingScale: number | null
Valor máximo da escala de avaliação.
exemplo: 5

moduleFormConfigs.ratingCalculation: string
Método de cálculo da avaliação.
exemplo: "average"

Exemplos de uso​

Passo a passo na documentação:

  • Enviar um formulário — buscar um formulário de contato pelo marcador e enviar a entrada do usuário de volta para o OneEntry.
  • Formulário de entidade — lidar com um formulário que contém um campo do tipo entidade (páginas ou produtos).
  • Registrar usuário — usar um formulário de cadastro para criar uma nova conta.

Experimente ao vivo​

Execute este método interativamente no sandbox do JS SDK — na primeira visita, conecte sua URL do Projeto e Token do App, depois abra qualquer cenário abaixo para ver Forms.getFormByMarker() em ação: