nginstack

Class: Field

@nginstack/engine/lib/classdef/Field~ Field

new Field(name, type [, opt_size])

Classe Field Utilizada para criar campos, determinar seus tipos e setar seus valores. Utilizada tanto no x-class como na grade.

Parameters:
Name Type Argument Description
name string

Nome único que identificará o campo.
type string

Tipo do campo, observe a propriedade #type para mais detalhes .
opt_size number <optional>

Tamanho do campo, requerido apenas para campos do tipo "string" e "password".

Extends

  • Emitter

Members

autoSanitize :boolean

Determina se os valores informados no campo, no rótulo e no nome do grupo devem ser tratados para remover tags que possam ser utilizadas com o objetivo de injetar scripts maliciosos em ataques do tipo Cross Site Scripting (XSS).

Ao desativar esta propriedade, é de crítica importância que algum tipo de validação ou sanitização seja realizada com o valor do campo, preferencialmente no evento beforeChange. A validação do rótulo do campo e do grupo também são desativadas, portanto deve-se ter atenção ao seus valores caso eles não sejam textos fixos.

Importante: a sanitização realizada por esta classe tem o objetivo de prevenir ataques do tipo XSS, mas os valores recebidos devem ainda ser validados para outros tipos de ataque, como o de injeção de SQL. Jamais utilize os valores oriundos dos campos ou de outras fontes, como propriedades de processos, registros da base de dados, arquivos ou dados de uma requisição, sem realizar algum tipo de sanitização desses valores, principalmente na construção de expressões SQL. Para a construção de expressões SQL, é recomendado o uso das funções toSqlString e toSqlIdentifier.

Type:
  • boolean

autoTrim :boolean

Determina se o campo excluirá automaticamente os espaços encontrados no início e no fim do valor atribuído a ele.

Type:
  • boolean

caseType :string

Em campos do tipo "string" ou "memo", determina como será tratado o texto informado com relação à caixa das letras (maiúsculas/minúsculas).

Valores suportados:

  • upper: todo o texto será convertido para caixa alta.
  • lower: todo o texto será convertido para caixa baixa.
  • name ou mixed: cada palavra será iniciada com uma letra maiúscula exceto as preposições mais comuns utilizadas em nomes próprios. Atualmente não são capitalizadas as preposições "of", "da", "do", "de", "dos" e "das".
  • title: cada palavra com mais de uma letra será iniciada com maiúscula, exceto as preposições mais comuns em títulos.
  • statement: cada palavra que inicie um parágrafo será iniciada com letra maiúscula.
Type:
  • string
See:

charLength :number|null

Para campos que possuem #databaseType igual a varchar ou char, indica a quantidade de caracteres que serão armazenados na coluna.

A diferença desta propriedade para #size é que tipos que representam máscaras de valores são normalizados para o tipo real utilizado para guardar o dado. Exemplo: um campo com tipo 'hour' possui o charLength igual a 8.

Campos do tipo combo, terão o seu tamanho calculado a partir dos valores do combo. Tipos que não tem representação de tamanho, como number, integer, masterdetail, têm o charLength igual a null.

Type:
  • number | null

classKey :number

Define que o campo será um lookup para a classe informada.

  • Se o campo for do tipo "int64", "int32" ou "integer" será um lookup simples, permitindo selecionar apenas um registro da classe informada. O valor deste campo será a chave do registro selecionado.
  • Se o campo for do tipo "memo", "string" ou "file" será um lookup múltiplo, permitindo selecionar vários registros da classe informada. O valor deste campo será uma lista separada por "," dos registros selecionados.

A tabela utilizada para realizar o lookup dependerá da propriedade lookupType. Valores possíveis:

  • LookupType.RECORD: será utilizada a tabela configurada na propriedade tableName do x-class da classe informada.
  • LookupType.CLASS: será utilizada a tabela CLASSE. Serão exibidas apenas as classes filhas da classe informada.
  • LookupType.FILE: será utilizada a tabela iVfs. Serão exibidos apenas os arquivos filhos da classe informada ou uma de suas filhas.
Type:
  • number
See:

databaseType :DatabaseDataType

Tipo de dados utilizado para armazenar este campo no banco de dados. A diferença desta propriedade para #type é que tipos que representam máscaras de valores são normalizados para o tipo real utilizado para guardar o dado. Exemplo: um campo com tipo 'hour' possui o databaseType com o tipo 'varchar'.

Campos do tipo combo, terão o seu tipo de dado calculado a partir dos valores do combo. Tipos que não tem representação direta na tabela, como masterdetail, têm o databaseType igual a null.

Type:
  • DatabaseDataType
See:

dataDictionary :Object

Ajuda para o dicionário de dados, quando se aplicar.

Este tipo de ajuda serve de base para o conhecimento técnico sobre a modelagem das tabelas no banco de dados. Deve indicar, entre outras coisas, o relacionamento entre o campo na tabela em que se está documentando e o campo de referência na outra tabela.

Type:
  • Object
See:

dataSetType :DataSetDataType

Tipo de dados utilizado para armazenar este campo em um DataSet. A diferença desta propriedade para #type é que tipos que representam máscaras de valores são normalizados para o tipo real utilizado para guardar o dado. Exemplo: um campo com tipo 'hour' possui o dataSetType com o tipo 'string'.

Campos do tipo combo, terão o seu tipo de dado calculado a partir dos valores do combo. Tipos que não tem representação direta na tabela, como 'masterdetail', têm o dataSetType igual a null.

Type:
  • DataSetDataType
See:

dateFormat :DateFormat

Formato de exibição de campos do tipo "date". Valores possíveis:

Type:
  • DateFormat
Deprecated:
  • Utilize a propriedade displayFormat.
Example
DateFormat.DDMMYYYY: dia/mês/ano(4 dígitos)
 DateFormat.DDMMYY:   dia/mês/ano(2 dígitos)
 DateFormat.MMYYYY:   mês/ano(4 dígitos)
 DateFormat.WWYYYY:   semana/ano(4 dígitos)

decimalPrecision :number

Determina a quantidade de casas decimais que devem ser exibidas quando o campo for do tipo "number".

Type:
  • number
Default Value:
  • 2

defaultValue :Object

Sugestão de preenchimento do campo.

Será ignorada caso a propriedade saveInputAsDefault seja true e o usuário já tenha informado um valor para este campo.

Recurso disponível apenas em grades de variáveis.

Type:
  • Object
See:
  • Field#saveInputAsDefault

detailFieldNames :string

Lista de campos da grade detalhes que devem ser pesquisados com os valores dos campos da mãe definidos em masterFieldNames com o objetivo de criar um relacionamento masterDetail. Recurso disponível apenas para campos do tipo "grid".

Type:
  • string

detailFilter :string

Filtro que será aplicado ao DataSet da grade detalhe.

Recurso disponível apenas para campos do tipo "grid" e "masterdetail".

Type:
  • string

displayFormat :DateFormat|LatitudeFormat|LongitudeFormat|AngleFormat

Formato de exibição dos tipos "date", "longitude", "latitude", "angle". Valores possíveis:

  • DateFormat.DDMMYYYY: dia/mês/ano(4 dígitos)
  • DateFormat.DDMMYY: dia/mês/ano(2 dígitos)
  • DateFormat.MMYYYY: mês/ano(4 dígitos)
  • DateFormat.WWYYYY: semana/ano(4 dígitos)
  • LatitudeFormat.DDD_DDDDD: graus decimais°
  • LatitudeFormat.DDD_MM_MMM_DIR: graus° minutos' {N|S}
  • LatitudeFormat.DDD_MM_SS_S_DIR: graus° minutos' segundos" {N|S}
  • LongitudeFormat.DDD_DDDDD: graus°
  • LongitudeFormat.DDD_MM_MMM_DIR: graus° minutos' {E|W}
  • LongitudeFormat.DDD_MM_SS_S_DIR: graus° minutos' segundos" {E|W}
  • AngleFormat.DDD: graus°
  • AngleFormat.DDD_DD: graus decimais°
Type:
  • DateFormat | LatitudeFormat | LongitudeFormat | AngleFormat

group :FieldGroup

Nome ou instância da classe FieldGroup, que será utilizado para agrupar visualmente os campos na grade. É importante que os campos a serem agrupados sejam vizinhos na ordem de exibição (configuração realizada através da propriedade order).

Type:
  • FieldGroup
See:
  • Field#order

help :String

Ajuda para o campo a ser utilizada pelas interfaces. Recomenda-se que a ajuda seja a mais intuitiva possível.

Pode-se utilizar alguns caracteres para melhorar a apresentação da ajuda como, por exemplo, "n" para quebrar a linha.

Type:
  • String
See:
Example
var fld = grid.field("ajuda", number)
fld.help = "isto é uma ajuda e tanto"

integrityCheck :boolean

Determina se a exclusão de um registro na tabela associada à propriedade classKey deve checar neste campo se existe referência à chave excluída.

Propriedade válida apenas para campos que possuam a propriedade classKey preenchida.

ATENÇÃO: Definir esta propriedade como false poderá permitir que este campo tenha referência a chaves que foram excluídas, o que consiste em uma falha de integridade. Deve haver uma validação manual que garanta a integridade do modelo de dados.

Type:
  • boolean

isClassLookup :boolean

API desaconselhada, equivalente a definir LookupType.CLASS na propriedade lookupType.

Type:
  • boolean
Deprecated:
  • Yes
See:

isDatabaseField :boolean

Informa se este campo possui uma representação no banco de dados. Caso não possua, o valor do campo em uma grade de DataSet não persistirá após o post do registro, precisando ser calculado por eventos ou processos.

Type:
  • boolean

isDataBaseField :boolean

Informa se este campo possui uma representação no banco de dados.

Type:
  • boolean
Deprecated:
  • Utilize #isDatabaseField.

label :String

Título atribuído ao campo. Por padrão a propriedade "name" do campo é atribuída automaticamente ao título do campo.

Em uma grade de variáveis, os nomes serão atribuídos obedecendo ao critério da primeira letra em caixa baixa e, quando mudar a palavra, a primeira letra da palavra deve ser digitada em caixa alta (mesmo padrão utilizado na nomenclatura das variáveis).

Type:
  • String
See:
Example
Se a propriedade "name" estiver preenchido com "dataInicial", a propriedade "label"
receberá automaticamente: "Data Inicial".

lookupType :number

Define o tipo de "lookup" do campo. O tipo será interpretado somente se a propriedade "classKey" estiver preenchida.

O "lookup" é um tipo especial de "combo", que aponta para uma tabela de dados.

Observe na tabela abaixo os valores possíveis e a sua aplicação:

Type:
  • number
See:
Example
TIPO              - APLICAÇÃO

LookupType.NONE   - Sem "lookup". Este é o valor padrão, se a propriedade
                    "classKey" não estiver preenchida.
LookupType.RECORD - "Lookup" para "Registros de Tabelas". Este é o valor padrão,
                    quando a propriedade "classKey" é preenchida.
LookupType.CLASS  - "Lookup" para "Classe de Tabelas", de acordo com a propriedade
                    "classKey".
LookupType.FILE   - "Lookup" para arquivos do Sistema Virtual de Arquivos (VFS)
                    a partir da classe definida na propriedade "classKey".

lowerName :string

Nome do campo em caixa baixa.

Type:
  • string

masterDeleteAction :MasterDeleteAction

Para campos do tipo "masterDetail", indica como os registros detalhes devem ser tratados quando ocorrer a exclusão do registro mestre.

Valores possíveis: MasterDeleteAction.ERROR, MasterDeleteAction.DELETE e MasterDeleteAction.UNLINK.

Type:
  • MasterDeleteAction

masterFieldNames :string

Lista de campos da grade mãe que devem ser utilizados para pesquisar nos campos detailFieldNames da grade detalhe, criando um relacionamento masterDetail.

Recurso disponível apenas para campos do tipo "grid".

Type:
  • string

max :number|Date

Valor máximo permitido de digitação no campo. Válido para todos os caracteres (letras, número e caracteres especiais).

Type:
  • number | Date
See:
  • Field#min
Example
var gr = this.grid('vars');
gr.title = 'Variáveis';
gr.onDefineFields.set(function(grid) {
   var fld = grid.field('fator', 'integer');
   fld.max = 10;
})

// Neste exemplo, caso o usuário digite um valor superior a 10, será apresentada a mensagem:
// 'O valor digitado deve ser menor ou igual a 10.'

maxDecimalPrecision :number

Determina a quantidade máxima de casas decimais que devem ser exibidas quando o campo for do tipo "number".

Type:
  • number

min :number|Date

Valor mínimo permitido de digitação no campo. Válido para todos os caracteres (letras, número e caracteres especiais).

Type:
  • number | Date
See:
  • Field#max
Example
var gr = this.grid('vars');
gr.title = 'Variáveis';
gr.onDefineFields.set(function(grid) {
   var fld = grid.field('fator', 'int32');
   fld.min = 10;
})

// Neste Exemplo, caso o usuário digite um valor inferior a 10, será apresentada a mensagem:
// 'O valor digitado deve ser maior ou igual a 10.'

minDecimalPrecision :number

Determina a quantidade mínima de casas decimais que devem ser exibidas quando o campo for do tipo "number". Caso a quantidade mínima não seja atingida então o restante dos valores será preenchido com zero.

Type:
  • number
Default Value:
  • 2

multiple :boolean

Determina, para campos de texto ("string" e "memo") com lookup ou combo, se o campo aceita valores múltiplos.

Esta propriedade somente pode ser setada se o campo possuir uma classKey ou for combo.

Caso esta propriedade não seja setada explicitamente, será utilizado o comportamento padrão, que é a aceitação de valores múltiplos para lookup e um único valor para combo.

Type:
  • boolean

name :string

Nome único que identifica o campo na base de dados.

Type:
  • string

onAfterChange :Event

Corresponde ao evento que será executado após ser alterado o valor do campo.

O exemplo abaixo escreve no log a mudança de valores que ocorreu no campo:

Type:
  • Event
Deprecated:
  • Utilize on('afterChange', listener).
Example
field.onAfterChange.set(function (field, beforeValue) {
   log.write('Valor alterado de ' + beforeValue + ' para ' + field.value);
})

onAfterLookupAddResult :Event

Evento emitido após o filtro dos resultados de uma pesquisa de um campo lookup. Esse evento será emitido uma vez, independente da quantidade de registros filtrados pelo evento lookupAddResult. Seu uso é recomendado quando há necessidade de limpar eventuais recursos que foram alocados em listeners do evento beforeLookupAddResult.

Type:
  • Event
Deprecated:
  • Utilize on('afterLookupAddResult', listener).
Example
field.onAfterLookupAddResult.set(function (field) {
   var process = field.parent.process;
   // Por exemplo, saldo é um DataSet que foi utilizado dentro do
   // onLookupAddResult
   process.saldo.empty()
 });

onBeforeChange :Event

Evento que será emitido antes de um campo ser alterado. O exemplo abaixo verifica o valor que se quer atribuir ao campo e caso ele seja maior que 10, então é disparado um erro.

Type:
  • Event
Deprecated:
  • Utilize on('beforeChange', listener).
Example
field.onBeforeChange.set(function (field, value) {
   if (value > 10)
     throw new Error('Valor não pode ser maior que 10');
 });

onBeforeLookupAddResult :Event

Evento emitido antes do filtro dos resultados de uma pesquisa de um campo lookup. Esse evento será emitido uma vez, independente da quantidade de registros filtrados pelo evento lookupAddResult. É recomendado o seu uso para alocar recursos que serão utilizados pelos listeners do evento lookupAddResult, evitando alocar esses recursos a cada avaliação do filtro.

Type:
  • Event
Deprecated:
  • Utilize on('beforeLookupAddResult', listener).
Example
field.onBeforeLookupAddResult.set(function (field) {
   var process = field.parent.process;
   // Por exemplo, saldo é um DataSet utilizado dentro do onLookupAddResult
   process.saldo = objetoSaldo.consulta();
   process.saldo.indexFieldNames = 'LOTE';
 });

onGetOptions :Event

Evento emitido para obter as opções de valores aceitos no preenchimento deste campo.

Ao configurar o evento onGetOptions de um campo, ele passa a ser comportar como um campo do tipo "combo", independentemente do tipo de dado informado na construção do campo.

Este evento deve ser configurado apenas se as opções não forem informadas diretamente por meio da propriedade #options do campo.

Type:
  • Event
Deprecated:
  • Utilize on('getOptions', listener).

onLookupAddResult :Event

Evento emitido durante a pesquisa de um campo lookup, permitindo que o desenvolvedor filtre as opções possíveis de serem informadas neste campo.

Type:
  • Event
Deprecated:
  • Utilize on('lookupAddResult', listener).
Example
field.onLookupAddResult.set(function(field, findResult) {
   return !field.parent.ds.uf || findResult.key.uf == field.parent.ds.uf;
 })

onLookupDisplay :Event

Evento emitido quando o sistema precisa obter o valor de exibição de uma chave desta classe de dados.

No exemplo abaixo quando o campo perder o foco será exibido o valor do nome e do codigo da UF:

Type:
  • Event
Deprecated:
  • Utilize on('lookupDisplay').
Example
field.onLookupDisplay.set(function (field, value) {
  if (value) {
    const key = DBKey.from(value);
    return key.str('NOME') + ' - ' + key.str('UF.CODIGO');
  } else {
    return '';
  }
})

onValidate :Event

Corresponde ao evento que será executado para validar o conteúdo informado para o campo. Neste evento não deve existir nenhuma dependência com o process, pois poderá ser disparado de dentro de qualquer ambiente.

O exemplo abaixo verifica se o campo do dataset é null se for, seta valor 0 para o campo da grade.

Type:
  • Event
Deprecated:
  • Utilize on('validate', listener).
Example
var f = grid.field('valor', 'int32')
 f.onValidate.set(function (field, ds) {
   if (ds.valor === null) {
     field.setValue(0);
   }
 });

options :Array.<Array>

Lista das opções de valores aceitos no preenchimento deste campo.

Ao configurar a propriedade options de um campo, ele passa a ser comportar como um campo do tipo "combo", independentemente do tipo de dado informado na construção do campo. Alternativamente, pode ser utilizado o evento getOptions para configurar as opções de preenchimento do campo.

Deve ser informado um array de arrays de 2 itens:

  • nome da opção
  • valor atribuído à opção
Type:
  • Array.<Array>
Example
var fld = this.field('weekDay', 'combo')
fld.label = 'Dia da Semana'
fld.options = [
  ['Domingo', 0], ['Segunda-feira', 1], ['Terça-feira', 2],
  ['Quarta-feira', 3], ['Quinta-feira', 4], ['Sexta-feira', 5],
  ['Sábado', 6], ['Domingo', 7]
];
fld.help = 'Informe um dia da semana.';

order :number

Ordem na qual o campo deverá ser exibido.

Type:
  • number

permissionFilterFieldName :string

Determina se este campo deve ser utilizado como filtro extra para validar o poder de inserção, alteração e exclusão de um registro.

O nome do campo informado será o do campo da iPermission, que deve ser filtrado com o valor deste campo.

O uso deste recurso em uma inserção gera uma expressão equivalente a:

Type:
  • string
See:
  • module:@nginstack/engine/lib/classdef/ModelDef#getExtraFilterFields
  • module:@nginstack/engine/lib/classdef/ModelDef#getExtraFilterExpression
Example
connection.getPermission(
   Grid.classKey, 'iInsert', Grid.userKeyToValidatePermissions,
   'withoutInheritance', [ Field.permissionFilterFieldName, Field.value ]
)

rangeLimit :Limit

Indica se o campo representa início ou fim de um intervalo, atualmente rangeLimit só é suportado para campos do tipo data.

Type:
  • Limit

readOnly :ReadOnlyMode|boolean

Determina quando o campo deve ser somente para leitura. Valores possíveis:

  • ReadOnlyMode.NEVER ou false: o campo pode ser alterado;
  • ReadOnlyMode.ALWAYS ou true: o campo é somente leitura;
  • ReadOnlyMode.AFTER_INSERT: o campo pode ser modificado apenas durante a inserção. Após a inserção, o campo não poderá ser mais modificado.
  • ReadOnlyMode.FILLED: campo é somente leitura apenas se estiver preenchido, impedindo a modificação do primeiro valor informado.
Type:
  • ReadOnlyMode | boolean

required :boolean

Indica se o campo é de preenchimento obrigatório.

Type:
  • boolean

size :number

Tamanho do campo em caracteres. Utilizado apenas para campos do tipo "string" ou do tipo "password".

Type:
  • number

stringIfTrue :String

Texto que representará o campo do tipo "boolean" quando o mesmo estiver marcado ("true").

Type:
  • String
Default Value:
  • "T"

type :string

Tipo do campo. Observe na tabela abaixo os valores permitidos e sua utilização:

  • "string" - Tipo utilizado para campos que conterão texto;

  • "password" - Tipo utilizado para campos que conterão senhas;

  • "masterDetail" - Tipo utilizado para criar uma relação de 1 para N entre duas classes. Para utilizar esse tipo de campo é obrigatório o preenchimento das seguintes propriedades:

    • classKey: indica a classe de dados que contém os registros detalhes da relação. A classe de dados que definiu o campo do tipo "masterDetail" é a classe considerada mestre da relação;
    • masterFieldNames: indica os campos da classe de dados mestre que devem ser utilizados para filtrar os registros da classe de dados detalhe.
    • detailFieldNames: indica os campos da classe de dados detalhe que serão filtrados com os valores dos campos masterFieldNames da classe mestre.

    Pseudo-código para obtenção dos registros detalhes:

       var tabelaDetalhe = classes.getCachedDataSet(field.classKey);
   var camposMestre = getFieldValues(field.masterFieldNames);
   tabelaDetalhe.indexFieldNames = field.detailFieldNames;
   detail.setRange(camposMestre, camposMestre);

  • "grid" - Tipo utilizado para indicar que o campo deve ser visualizado como uma grade detalhe da classe de dados que o definiu. O seu propósito é similar ao tipo "masterdetail", no entanto, ele permite a exibição de dados detalhes cuja relação não pode ser estabelecida apenas pelas propriedades classKey, masterFieldNames e detailFieldNames. Sempre que for possível, é recomendado o uso do tipo "masterdetail". Campos do tipo "grid" não podem ser utilizados em definição de modelo de dados (x-model), sendo o seu uso restrito em definições de visão (x-view) e em processos. Campos do tipo "grid" podem ser definidos em grades de variáveis, sem DataSet associado. Nesse caso, o evento createDataSet da grade detalhe deve ser configurado e as propriedades masterFieldNames, detailFieldNames e classKey não devem ser informadas.

  • "int64" - Tipo utilizado para campos que conterão números inteiros de 64 bits. Campos que armazenem chaves ou versões do sistema devem utilizar este tipo.

  • "int32" - Tipo utilizado para campos que conterão números inteiros de 32 bits. Deve ser utilizado para valores contidos na faixa de [-Math.pow(2, 31) ~ Math.pow(2, 31) - 1] e que não sejam chaves e versões do sistema. Para esses últimos, deve ser utilizado o tipo "int64".

  • "integer" - Tipo legado que existia antes da criação dos tipos "int64" e "int32". O tipo "integer" será mapeado para um desses dois tipos de acordo com o valor retornado pela função DataSet.getIntegerDataType().

  • "number"- Tipo utilizado para campos que conterão números decimais. Por padrão terão duas casas decimais.

  • "latitude" - Tipo utilizado para campos que conterão números decimais para representar latitudes. Por padrão terão até cinco casas decimais e a parte inteira conterá até três casas.

  • "longitude" - Tipo utilizado para campos que conterão números decimais para representar longitudes. Por padrão terão até cinco casas decimais e a parte inteira conterá até três casas.

  • "angle" - Tipo utilizado para campos que conterão números decimais para representar ângulos. Por padrão terão duas casas decimais e a parte inteira conterá até três casas.

  • "memo" - Tipo utilizado para campos que conterão textos longos (mais de 4000 caracteres).

  • "date" - Tipo utilizado para campos que conterão datas.

  • "combo" - Tipo utilizado para campos que conterão listas de opções ou combinação de outros tipos. Devido ao tipo do dado e tamanho serem dinamicamente calculados com base nas opções do combo, ele deve ser evitado nas definições das classes de dados (arquivos x-model e x-class). Em seu lugar, deve ser dada preferência aos campos com tipos reais e que tenham a propriedade #options ou o evento getOptions definidos.

  • "time" - Tipo utilizado para campos que conterão horas. Utilizado para trabalhar com tempo.

  • "boolean" - Tipo utilizado para campos que conterão valores lógicos ou booleanos.

  • "file" - Tipo utilizado para campos que conterão arquivos.

  • "tree" - Tipo utilizado para campos que conterão grades do tipo treeGrid (árvore).

Para testar se o campo é de um determinado tipo, utilize as funções de teste de tipo: isString, isNumber, isMasterDetail, isGrid, etc.

Type:
  • string

upperName :string

Nome do campo em caixa alta.

Type:
  • string

userCanChangeNegativeKey :boolean

Indica se o usuário pode ou não alterar o conteúdo do campo, caso o registro seja de chave negativa (licenciado para o produto).

Type:
  • boolean

Methods

assign(field)

Copia as propriedades de um campo informado.

Parameters:
Name Type Description
field Field

Campo de onde as propriedades devem ser copiadas

assignObjectsTo(field)

Copia as propriedades que são objetos para um campo

Parameters:
Name Type Description
field

Objeto campo para onde as propriedades devem ser copiadas

assignTo(field)

Copia as propriedades de um campo para outro.

Parameters:
Name Type Description
field Field

Campo para onde as propriedades devem ser copiadas

clone(NewClass)

Cria uma cópia do campo.

Parameters:
Name Type Description
NewClass function

Classe em que o campo que será criado. Este parâmetro é opcional e deve ser utilizado apenas quando se deseja alterar a classe do campo que será clonado.
Returns:

Cópia do campo na classe informada.

Type
Field

isBoolean()

Indica se o campo é do tipo boolean.

Returns:

True se o campo é do tipo boolean, false caso contrário.

Type
boolean

isCombo()

Indica se o campo é do tipo "combo" ou se as opções de preenchimento foram configuradas pela propriedade #options ou pelo evento getOptions.

Returns:

True se o campo é do tipo combo, false caso contrário.

Type
boolean

isDate()

Indica se o campo é do tipo date.

Returns:

True se o campo é do tipo date, false caso contrário.

Type
boolean

isFile()

Indica se o conteúdo do campo são arquivos armazenados na VFS.

Returns:

True se o campo é do tipo file, false caso contrário.

Type
boolean

isInt32()

Indica se o campo é do tipo inteiro 32 bits.

Returns:

True se o campo é do tipo 'int32', false caso contrário.

Type
boolean

isInt64()

Indica se o campo é do tipo inteiro 64 bits.

Returns:

True se o campo é do tipo 'int64', false caso contrário.

Type
boolean

isInteger()

Indica se o campo é do tipo inteiro, independente da sua precisão ('int64' ou 'int32').

O tipo 'integer' sem precisão é mapeado para o tipo retornado pela função DataSet.getIntegerDataType().

Returns:

True se o campo é do tipo integer, false caso contrário.

Type
boolean

isMasterDetail()

Indica se o campo é do tipo masterdetail.

Returns:

True se o campo for do tipo masterdetail.

Type
boolean

isMemo()

Indica se o campo é do tipo memo.

Returns:

True se o campo é do tipo memo, false caso contrário.

Type
boolean

isNumber()

Indica se o campo é do tipo number.

Returns:

True se o campo é do tipo number, false caso contrário.

Type
boolean

isPassword()

Indica se o campo armazena uma senha.

Returns:

True se o campo é do tipo password, false caso contrário.

Type
boolean

isString()

Indica se o campo é do tipo string.

Returns:

True se o campo é do tipo string, false caso contrário.

Type
boolean

isTime()

Indica se o conteúdo do campo é do tipo 'time'.

Para fins de compatibilidade, campos do tipo 'string' de tamanho 5 ou 8 com as palavras 'Hour' e 'Hora' no seu nome, ou com o sufixo H, são considerados do tipo 'time'. Esse comportamento tem o objetivo de suportar códigos legados de uma época onde não existia o tipo específico 'time'. Essa lógica é falha, pois pode considerar campos do tipo 'string' como do tipo 'time' indevidamente. Novas definições de campo sempre devem definir o tipo 'time' de forma explícita, pois em algum momento esse suporte aos códigos legados poderá ser removido.

Returns:

True se o campo é do tipo 'time', false caso contrário.

Type
boolean

validateValue(value)

Valida o valor informado para um campo.

No caso dos campos do tipo legado "combo", o valor informado será considerado o índice da opção (1-indexado) e o valor zero indica que o campo deve ser limpo. Caso o valor informado não seja numérico ou seja maior que a quantidade de opções, ele será comparado com os valores das opções do combo. Esse comportamento especial do combo é mantido apenas para preservar os códigos existentes que usam o tipo "combo". Para evitá-lo, defina a propriedade options em campos com tipos reais de dados.

Parameters:
Name Type Description
value string | number | boolean | Date

O valor a ser validado.

Events

afterChange

Evento que será emitido após um campo ter sido alterado, permitindo que o desenvolvedor modifique outros campos com base no valor informado.

Type: FieldChangeEvent
Example
field('uf').on('afterChange', function (evt) {
   if (evt.newValue) {
     evt.data.localidade = null;
   }
 });

afterLookupAddResult

Evento emitido após o filtro dos resultados de uma pesquisa de um campo lookup. Esse evento será emitido uma vez, independente da quantidade de registros filtrados pelo evento lookupAddResult. Seu uso é recomendado quando há necessidade de limpar eventuais recursos que foram alocados em listeners do evento beforeLookupAddResult.

Type: FieldEvent
Example
field.on('afterLookupAddResult', function (evt) {
   evt.field.saldo_.empty();
 });

beforeChange

Evento que será emitido antes de um campo ser alterado, permitindo que o desenvolvedor impeça a alteração do campo, lançando um erro, ou altere o valor a ser informado no campo, modificando a propriedade FieldChangeEvent#newValue.

Type: FieldChangeEvent
Example
field.on('beforeChange', function (evt) {
   if (evt.newValue > 10)
     throw new Error('Valor não pode ser maior que 10');
 });

beforeLookupAddResult

Evento emitido antes do filtro dos resultados de uma pesquisa de um campo lookup. Esse evento será emitido uma vez, independente da quantidade de registros filtrados pelo evento lookupAddResult. É recomendado o seu uso para alocar recursos que serão utilizados pelos listeners do evento lookupAddResult, evitando alocar esses recursos a cada avaliação do filtro.

Type: FieldEvent
Example
field.on('beforeLookupAddResult', function (evt) {
   var process = evt.field.parent.process;
   // Saldo é um DataSet que será utilizado no evento lookupAddResult
   evt.field.saldo_ = saldo.consulta();
   evt.field.saldo_.indexFieldNames = 'LOTE';
 });

getOptions

Evento emitido para obter as opções de valores aceitos no preenchimento deste campo.

Ao configurar o evento getOptions de um campo, ele passa a ser comportar como um campo do tipo "combo", independentemente do tipo de dado informado na construção do campo.

Este evento deve ser configurado apenas se as opções não forem informadas diretamente por meio da propriedade #options do campo.

Type: FieldOptionsEvent
Example
field.on('getOptions', function (evt) {
   evt.options = [['Opção A', 1], ['Opção B', 2]];
 });

lookupAddResult

Evento emitido durante a pesquisa de um campo lookup, permitindo que o desenvolvedor filtre as opções possíveis de serem informadas neste campo. Deve ser retornado um booleano para indicar se o registro indicado por LookupAddResultEvent#key pode ser utilizado como valor deste campo.

Type: FieldEvent
Example
field.on('lookupAddResult', function (evt) {
   return !evt.data.uf || evt.key.uf === evt.data.uf;
 })

lookupDisplay

Evento emitido quando o sistema precisa obter o valor de exibição de uma chave desta classe de dados. Os listeners registrados deverão preencher a propriedade LookupDisplayEvent#displayValue do evento emitido para informar o valor de exibição da chave indicada por LookupDisplayEvent#key.

Type: LookupDisplayEvent
Example
this.on('lookupDisplay', function (evt) {
   evt.displayValue = DBKey.str(evt.key, 'NOME');
 });

validate

Evento emitido antes de efetivar uma modificação com o objetivo de validar o preenchimento do campo.

Diferentemente dos eventos beforeChange e afterChange, esse evento não deve fazer uso de componentes de interface, pois ele tem o objetivo exclusivo de realizar validações de modelo de dados e pode ser chamado em contextos sem interação com o usuário, como APIs HTTP.

Type: FieldEvent
Example
grid.field('field_name').on('validate', function (evt) {
   if (evt.data.field_name < 0) {
     throw new Error('O valor deve ser positivo.');
   }
 });