Propriedades e vinculações

Uma das tarefas mais comuns ao desenvolver um aplicativo com uma GUI é manter os dados e a interface do usuário sincronizados. Por exemplo, imagine que você usa ferramentas de desenvolvimento convencionais na criação de um aplicativo da Web para pesquisar e editar registros de clientes. Sem o App Maker, você precisaria criar um meio de manter os registros do banco de dados e a IU do aplicativo sincronizados das seguintes maneiras:

  1. Atualizar todos os elementos da IU que exibem dados quando o próximo registro no banco de dados é solicitado.

  2. Adicionar listeners de alteração a todos os elementos da IU para garantir que as edições do usuário sejam refletidas no registro do cliente.

  3. Atualizar o registro atual do cliente para receber os dados novos.

Isso gera muito boilerplate para você gravar e manter, o que já é algo complicado para os programadores e que pode ser um obstáculo enorme para outros profissionais.

No App Maker, em vez de gravar todo esse boilerplate, são usadas vinculações para indicar que uma propriedade no registro do cliente e outra de um widget precisam estar sincronizadas. E isso tudo é feito em uma interface visual fácil de usar. Resumindo, o App Maker faz todo o restante do trabalho para você.

Além desse caso comum, as vinculações do App Maker fazem mais do que apenas manter os elementos da IU sincronizados com os valores subjacentes. Use-as para sincronizar duas propriedades do App Maker, como o e-mail do usuário conectado no momento e um parâmetro de consulta da fonte de dados. Na verdade, é possível usar vinculações em várias propriedades do App Maker, já que elas estão em praticamente todos os componentes dessa ferramenta, como modelos, fontes de dados, widgets e scripts.

Propriedades

Basicamente, uma propriedade é um valor nomeado de um objeto do App Maker. É possível receber e definir os valores das propriedades na ferramenta, e a maioria dos objetos do App Maker tem propriedades que podem ser acessadas em diferentes partes do aplicativo.

Defina propriedades de várias maneiras:

  • na IU usuário do App Maker: quando você define o nome de um widget
  • por vinculação: quando uma propriedade é alterada para refletir as atualizações de outra propriedade
  • em um script: é possível definir uma propriedade com JavaScript

É possível acessar uma variedade de propriedades:

  • campos nos registros do banco de dados
  • o endereço de e-mail do usuário conectado no momento
  • atributos do widget, como posição, nome ou valor

Na verdade, há propriedades em todo o App Maker, principalmente no Editor de propriedades:

E no seletor de vinculação:

Objetos

Vejamos mais detalhes sobre as propriedades falando sobre os objetos. Os objetos são os elementos que compõem o App Maker e os aplicativos dessa ferramenta. Praticamente tudo no App Maker é um objeto. O que são esses elementos? Eles são os widgets que compõem a IU, os registros que representam os dados, os objetos da fonte de dados que fazem leitura e gravação e muito mais. Até mesmo o próprio aplicativo é um objeto.

Por exemplo, um widget de Área de texto é um objeto do App Maker com várias propriedades, incluindo name e label. Um registro de dados é um objeto do aplicativo com propriedades definidas por você, como um registro do cliente com uma propriedade name.

Tipos

Todas as propriedades do App Maker têm um tipo de dados (em inglês), ou seja, elas aceitam apenas tipos específicos de valores, como números ou strings. Muitas propriedades têm tipos simples, como string, número ou booleano, mas outras têm tipos complexos. Por exemplo, a propriedade parent de um widget também é um widget, então o tipo dela é widget.

Caminhos

O App Maker usa uma notação de caminho para se referir a propriedades ao indicá-las em vinculações ou em scripts. Por exemplo, um objeto de modelo de dados chamado Person com uma propriedade denominada Name é indicado como Person.Name.

Indefinido

Valores de caminho e propriedade podem ser indefinidos. Isso é diferente de ser null. Um exemplo de propriedade indefinida é uma propriedade de relação de registro que ainda não foi carregada. Um caminho como datasource.item.Name é indefinido se a última propriedade dele (Name) for indefinida, ou se alguma das partes, como datasource ou item, estiver indefinida ou null. Em geral, o App Maker trata valores indefinidos como null. No entanto, os widgets de entrada serão desativados se os valores estiverem configurados como indefinidos. Por exemplo, é possível usar o seguinte script para apagar o valor de uma caixa de texto e desativá-la:

textBox.value = undefined;
    

Exemplo

Neste exemplo, são mostradas duas propriedades complexas: Person e Address. Cada um desses tipos especiais podem ser definidos em um modelo criado por você. Eles não são tipos integrados do App Maker.

Pessoa
Nome da propriedadeTipo
Namestring
Agenúmero
AddressEndereço
Endereço
Nome da propriedadeTipo
Streetstring
Citystring
Zipstring

Como o tipo da propriedade Address de Person é Address, é possível usar a notação de caminho para indicar a localização da pessoa usando Person.Address.City.

Vinculações

A vinculação é um mecanismo para manter duas propriedades sincronizadas. Como autor do App Maker, você geralmente declara que quer vincular duas propriedades, como o valor de uma entrada de texto e um campo de um registro. O App Maker mantém essas propriedades sincronizadas automaticamente, ou seja, quando uma é alterada, a outra é definida.

Todas as propriedades do App Maker são observáveis, o que significa que é possível detectar alterações nelas. Quando é feita uma vinculação entre duas propriedades, ela detecta ou observa alterações em ambas. Quando uma delas é alterada, a outra é atualizada.

Um exemplo comum no App Maker é vincular um valor de entrada de texto à propriedade de item de uma fonte de dados. Isso é feito usando o Editor de propriedades do App Maker. Por extenso, a vinculação é assim:

@widget.text <-> @datasource.item.MyField
    

Conversor de tipos de valores vinculados

Toda propriedade tem um tipo e um valor. O valor em si também tem um tipo, que corresponde ao valor da propriedade. Por exemplo, a propriedade Name de um widget é um tipo de string. Por isso, os valores de nomes são strings e não podem ser tratados como números inteiros.

Para vincular duas propriedades, é necessário que elas tenham o mesmo tipo, ou que seja possível converter o tipo dos valores. Esse processo é chamado de conversão de tipo.

Por exemplo, se você atribuir um valor "6" à propriedade Name de um widget, esse valor "6" será tratado como uma string, e não como um número. É possível vincular essa propriedade a outra do tipo de número inteiro. Nesse caso, o conversor de tipo do App Maker tentará transformar os tipos de valor dessas duas propriedades.

O App Maker inclui muitas conversões de tipo integradas para que a maioria das vinculações funcione. Os conversores funcionam em ambas as direções da melhor maneira sempre.

DeParaCondições
stringnúmeroSomente se de pode ser analisado como um número.
stringbooleanoSomente se de for "verdadeiro" ou "falso" (não diferencia maiúsculas e minúsculas).
stringdataSomente se de for uma data no formato AAAA-MM-DD.
númerobooleanoZero é convertido para falso e qualquer outro valor para verdadeiro.
Matriz <A>Matriz <B>A e B precisam ser compatíveis.

Transformadores

Às vezes, pode ser útil vincular duas propriedades que tenham uma conversão personalizada de dados entre elas. Por exemplo, vincular um campo em um registro a um campo de texto na IU, mas de modo que os espaços em branco na entrada do usuário sejam apagados antes de ela ser salva no banco de dados. Ou talvez você queira converter uma data em uma string por meio de um padrão diferente daquele usado pela conversão de tipo padrão do App Maker. Com transformadores, é possível especificar transformações em caminhos de propriedade. Cada transformador recebe um valor de entrada e gera um valor de saída. A maioria dos transformadores também converte os valores de saída de volta para os de entrada. É possível encadear essas transformações simultaneamente. Por exemplo, para apagar espaços em branco de entradas e saídas do caminho de uma string, vincule a propriedade value de um campo de texto ao campo Name de um registro de fonte de dados:

@value <-> @datasource.item.Name#trim()
    

Se preferir, especifique a formatação personalizada da conversão de data para string quando vincular uma propriedade value de campo de texto e um timestamp de campo de data no banco de dados:

@value <--> @datasource.item.TimeStamp#formatDate('yyyy/MM/dd HH:mm:ss');
    

É possível encadear transformadores:

@value <-> @datasource.item.Name#nullToEmpty()#trim()
    

Consulte uma lista de todos os transformadores integrados.

Os transformadores também podem ser aplicados a elementos de uma matriz, em vez da matriz em si. Por exemplo, se você estiver preenchendo a propriedade name de um widget de lista suspensa com itens de uma projeção. A sintaxe é a mesma, mas use duas cerquilhas em vez de uma.

@names <-> @datasources.items..TimeStamp##formatDate('yyyy/MM/dd HH:mm:ss')
    

Propriedades de nível superior em vinculações

Ao vincular a propriedade de um objeto, como um nome de widget, você usa o seletor de vinculação para navegar pelas propriedades disponíveis. O App Maker ajusta automaticamente as propriedades disponíveis, dependendo do objeto usado na vinculação. Isso simplifica o processo de vinculação a determinadas propriedades comuns. Por exemplo, se você vincular um valor para um widget de Botão, o seletor de vinculação será padronizado automaticamente para a propriedade datasource.item do widget, que geralmente contém campos de um modelo.

No entanto, talvez você queira vincular um widget ou outro objeto a algo diferente das sugestões fornecidas automaticamente no seletor de vinculação. Para isso, é importante entender as duas categorias gerais de propriedades que podem ser usadas ao vincular objetos no aplicativo.

Propriedades disponíveis globalmente

É possível vincular qualquer propriedade do aplicativo. Essas propriedades geralmente são acessadas usando o objeto app. Durante a vinculação, todas as propriedades de objetos app são categorizadas e expostas. Para mais informações sobre todas as propriedades, consulte a documentação da API do objeto app.

Propriedades disponíveis para widgets

É possível vincular um widget a todas as propriedades do objeto app e a duas outras propriedades:

  • widget: o próprio widget.
  • datasource: a fonte de dados do widget, que é o objeto mais comum para vincular a um widget. A propriedade também está disponível como @widget.datasource, mas, por conveniência, datasource é exibido no seletor de vinculação do editor da IU.

Expressões de vinculação

Às vezes, não basta vincular duas propriedades diretamente. É possível combinar vinculações e JavaScript para transformar um valor a que você está vinculado. Para isso, use expressões no editor de vinculações da IU do App Maker. O App Maker avalia a expressão sempre que uma das propriedades usadas nela é alterada. Observação: isso torna a vinculação unidirecional.

Por exemplo, imagine que você tenha um botão Excluir denominado MyDeleteButton e queira criar uma vinculação para que ele seja desativado se não houver nenhum registro a ser removido no banco de dados. No entanto, não há uma propriedade que represente esse conceito diretamente. Temos as propriedades enabled e @datasource.item e sabemos que, se não houver nenhum item, o valor do item será null. Portanto, com essas informações, podemos fazer esta vinculação:

@widget.enabled <-> @datasource.item != null
    

O botão só será ativado quando houver um registro.

Outros recursos

Para mais informações sobre como criar expressões de vinculação, consulte Expressões de vinculação e Scripts do lado do cliente. Para mais informações sobre todas as propriedades e métodos disponíveis para widgets e objetos de cliente, consulte a API Widgets e a API Client.