Fontes de dados

O acesso aos dados com os widgets do App Maker e a API do cliente é feito por meio de fontes de dados. Essas fontes definem:

  • a consulta aos dados dos modelos pelo aplicativo;
  • como essas informações são acessadas pela IU.

As fontes de dados têm uma propriedade item que aponta para o item selecionado em uma fonte de dados. Na IU, a propriedade item é usada pelos widgets para exibir ou editar informações sobre o registro atualmente selecionado na fonte de dados. Também é possível permitir o acesso e a modificação de registros por scripts do cliente por meio dessa propriedade.

Neste artigo, você saberá mais sobre:

  1. tipos de fontes de dados;
  2. o ciclo de vida da fonte de dados;
  3. como criar uma fonte de dados de consulta, o que inclui como criar uma consulta e outras configurações da fonte de dados;
  4. como refinar uma fonte de dados de consulta com scripts do cliente;
  5. como trabalhar com fontes de dados relacionais para acessar registros associados;
  6. como usar fontes de dados de modo de criação para criar registros de rascunho a partir da entrada do usuário.

Tipos de fontes de dados

O App Maker tem três tipos de fontes de dados:

  1. Fonte de dados de consulta
  2. Fonte de dados relacional
  3. Fonte de dados de modo de criação

Uma fonte de dados de consulta armazena:

  • informações sobre uma consulta a um modelo;
  • os registros da última execução da consulta.

Por padrão, uma fonte de dados de consulta é criada para cada modelo com o mesmo nome do modelo. É possível personalizar as fontes de dados de consulta e criar mais delas para um modelo. Para modelos com várias opções selecionadas, como resultados filtrados, classificações diversas ou tamanhos de página diferentes, é indicado um número maior de fontes de dados de consulta. Também é possível usar várias fontes de dados para selecionar registros diferentes simultaneamente, como ao comparar dois valores de datasource.item. Use widgets da IU e scripts do lado do cliente para alterar e executar novamente a consulta. Os resultados da última consulta podem ser vinculados a propriedades do widget e acessados em scripts do lado do cliente.

Ao desenvolver a IU, você normalmente associa uma fonte de dados de consulta aos painéis de nível superior de páginas ou widgets compostos. Em seguida, todos os widgets filho do painel herdam automaticamente essa fonte de dados, e é possível associar propriedades de widgets a campos nos registros da fonte de dados.

Na fonte de dados relacional, é possível exibir dados sobre registros associados. Crie uma fonte de dados relacional a partir de uma fonte de dados de consulta ou outra fonte de dados relacional para uma extremidade particular da relação. As fontes de dados relacionais exibem os registros de uma extremidade da relação que estão associados ao registro atualmente selecionado da fonte de dados pai.

Um uso comum de fontes de dados relacionais é ao implementar uma visualização de detalhes mestre. Por exemplo, é possível criar uma IU para exibir um pedido do cliente e os itens relacionados. Você teria dois modelos, Pedidos e Itens, e criaria uma relação um-para-muitos entre eles. Para saber mais informações sobre como usar as fontes de dados relacionais no editor da IU, acesse vincular os dados à IU.

Nas fontes de dados de modo de criação, os itens são criados em uma fonte de dados pai de consulta ou relacional.

Ciclo de vida da fonte de dados

As fontes de dados podem estar em um dos quatro estados a seguir:

  1. Descarregada
  2. Descarregada + Carregando
  3. Carregada
  4. Carregada + Carregando

Uma fonte de dados descarregada não tem dados. Os itens dela são uma matriz vazia, e o item atualmente selecionado é null. Uma fonte de dados carregando está em processo de recebimento de dados. Uma fonte de dados carregada tem dados, mas eles podem estar vazios.

Para que uma fonte de dados esteja em um dos estados carregando, um carregamento precisa ser acionado. O carregamento pode ser acionado das seguintes formas:

  1. Por padrão, um carregamento é acionado quando um widget que usa essa fonte de dados é anexado a uma página. Geralmente, um widget é anexado quando um usuário abre a página pai dele.
  2. Por padrão, um carregamento é acionado quando um widget que tem um vínculo com as propriedades de dados da fonte de dados é anexado. Por exemplo, se você tiver um widget de rótulo em uma página Pedidos vinculado a um campo no modelo Clientes, a fonte de dados Clientes será carregada quando a página Pedidos for mostrada.
  3. Um carregamento é acionado por um script do cliente que chama os métodos load, loadPage, prevPage ou nextPage na fonte de dados.

É possível desativar o carregamento automático de dados das fontes de dados de consulta, o que impede os dois primeiros gatilhos de carregamento da lista. Para descarregar uma fonte de dados, chame o método unload nela.

As fontes de dados de consulta têm um evento onLoad que é acionado quando uma fonte de dados transita para o estado carregado. O evento onLoad é útil quando você quer executar um script para realizar uma ação após o carregamento dos dados de uma fonte. Por exemplo, insira o seguinte script no editor de código onLoad para tornar um widget visível quando os dados estiverem disponíveis:

var widget = app.pages.MyPage.descendants.MyWidget;
widget.visible = true;

Fontes de dados de consulta

Quando você cria um modelo, uma fonte de dados de consulta é criada automaticamente. É possível personalizar as fontes de dados de consulta e criar mais delas para um modelo.

Para editar ou criar uma fonte de dados de consulta:

  1. clique no modelo no painel de navegação e acesse a guia Fontes de dados dele;
  2. para editar uma fonte de dados, clique nela. Para criar uma fonte de dados, clique em Adicionar fonte de dados;
  3. configure a fonte de dados. As alterações serão salvas automaticamente.

As fontes de dados têm as seguintes opções de configuração:

Script do servidor de consulta

Por padrão, todos os registros do modelo são carregados pela fonte de dados. A propriedade de script de consulta permite que você substitua o comportamento de consulta padrão especificando uma lógica personalizada do lado do servidor, como filtros. Para modelos calculados, o script de consulta permite definir completamente o comportamento da consulta a uma fonte de dados e criar registros na fonte.

Recursos e requisitos do script de consulta:

  • É possível chamar uma função de script do servidor a partir do editor de scripts de consulta, o que é útil se o script de consulta for longo.
  • É possível transmitir parâmetros do cliente para o script de consulta com parâmetros personalizados.
  • O script de consulta precisa retornar uma matriz de registros pertencentes ao modelo da fonte de dados.

Exemplo de filtro

Por exemplo, com a consulta à fonte de dados Employee padrão, todos os registros do modelo Employee são retornados. Digamos que você queira somente funcionários com idades pares e maiores que a idade mínima especificada na consulta. Para aplicar essa consulta à fonte de dados, insira o código a seguir no editor de código de Script de consulta:

var employeeResult = [];
// Modify passed query to also filter by minimum age.
query.filters.Age._greaterThan = 20;
var employeesAboveMinimumAge = query.run();
for (var i = 0; i < employeesAboveMinimumAge.length; i++) {
  if (employeesAboveMinimumAge[i].age % 2 == 0) {
    employeeResult.push(employeesAboveMinimumAge[i]);
  }
}
return employeeResult;

Exemplo de criação de registro calculado

Modelos calculados são usados para representar os resultados do script como registros para que você possa usá-los na IU. Por exemplo, você quer consultar o modelo Employees para criar um modelo calculado que gere registros de quantos funcionários estão em cada local. Como os registros reais EmployeesByLocation não existem no banco de dados, o script de consulta precisa criar registros chamando newRecord(). Com o script a seguir, o número de funcionários em cada local é calculado, e um registro é criado para cada local no modelo calculado:

var calculatedModelRecords = [];
var recordsByLocation = {};
var allEmployees = app.models.Employees.newQuery().run();
for (var i = 0; i < allEmployees.length; i++) {
  var employee = allEmployees[i];
  if (!recordsByLocation[employee.location]) {
    var calculatedModelRecord = app.models.EmployeesByLocation.newRecord();
    calculatedModelRecord.numberOfEmployees = 1;
    calculatedModelRecord.location = employee.location;
    calculatedModelRecords.push(calculatedModelRecord);
    recordsByLocation[employee.location] = calculatedModelRecord;
  } else {
    recordsByLocation[employee.location].numberOfEmployees++;
  }
}
return calculatedModelRecords;

Parâmetros personalizados

No script de consulta, também podem ser usados parâmetros que não podem ser fornecidos pelo banco de dados. Por exemplo, você quer filtrar dados com base no preço atual da ação de uma empresa, recuperado de um serviço da Web. Transmita parâmetros do cliente para o script de consulta no servidor com parâmetros personalizados.

Para adicionar um parâmetro:

  1. na guia Fontes de dados, clique em Adicionar parâmetro;
  2. selecione o tipo de parâmetro;
  3. digite um nome para o parâmetro.

Acesse e vincule ao parâmetro na propriedade parameters da consulta à fonte de dados. Por exemplo, vincule a propriedade de valor de um widget de campo de texto ao parâmetro de consulta com vínculos:

textField.value <-> datasource.query.parameters.MyParam

Os parâmetros podem ser acessados pelos scripts de consulta como parâmetros de consulta. Para aplicar essa abordagem ao exemplo anterior, podemos adicionar o seguinte código ao script de consulta. Com essa adição, o filtro de idade mínima só é adicionado se um parâmetro personalizado booleano chamado RestrictAge for true:

// Modify query to also filter by minimum age if client enables the option.
if (query.parameters.RestrictAge) {
  query.filters.Age._greaterThan = 20;
}
var employees = query.run();

Criador de consultas

O criador de consultas está disponível para fontes de dados do Cloud SQL. Ele é um análogo simplificado da cláusula WHERE do MySQL, que é compatível com filtragem em modelos relacionados e facilita as consultas a null. Use o criador para executar consultas complexas com base nas informações enviadas pelos usuários do aplicativo.

Por exemplo, crie um aplicativo que permita aos usuários procurar em um banco de dados de RH por funcionários qualificados para planos de aposentadoria diferentes. O criador de consultas ajuda você a criar as expressões lógicas de que o aplicativo precisa para encontrar os dados. Dessa forma, você não precisa escrever um script personalizado para interpretar a entrada do usuário e aplicá-lo a uma pesquisa de banco de dados do Cloud SQL. O criador de consultas também é compatível com a conclusão de código (pressione Ctrl + Espaço).

Para implementar uma consulta com parâmetros de entrada do usuário:

  1. crie a expressão de consulta no criador de consultas e os parâmetros de entrada do usuário como de costume;
  2. vincule as propriedades do widget aos parâmetros de entrada do usuário.

Como criar uma consulta

No criador, as consultas são processadas de acordo com as seguintes regras:

  • As expressões de consulta são avaliadas da esquerda para a direita.
  • O prefixo de dois pontos (:) diferencia um parâmetro inserido pelo usuário de um campo do modelo.
  • O operador and tem precedência sobre o operador or.
  • As expressões de subconsulta entre parênteses têm precedência sobre os operadores and e or.
  • O operador "!" nega o valor booleano de uma expressão.
  • Com o modificador "?" para operadores de folha, um valor nulo para o lado direito da expressão é considerado verdadeiro. Não é possível negar expressões que usem o modificador "?".

Para nosso exemplo de banco de dados de RH, é necessário retornar os funcionários que estão dentro de determinada faixa etária ou que começaram a trabalhar após uma data específica. A consulta é:

(Age >= :AgeMin and Age < :AgeMax) or StartDate > :StartDate
  • Age: um campo no modelo do aplicativo. Contém a idade de cada funcionário. As idades mínima (:AgeMin) e máxima (:AgeMax) são solicitadas pelo aplicativo aos usuários. São retornados funcionários que se enquadrem nesse intervalo.
  • Dois pontos(:): os dois pontos identificam os parâmetros com valor gerado por meio da IU do aplicativo.
  • Parênteses: identificam uma subconsulta. A subconsulta é avaliada pelo App Maker antes de ser transmitida para :StartDate.
  • and: um operador. Ele informa ao aplicativo a necessidade de retornar empregados que atendam aos dois critérios.
  • or: um operador. Ele informa ao aplicativo a necessidade de retornar empregados que atendam a qualquer um dos dois critérios.
  • StartDate: um campo que contém a data em que um funcionário começou a trabalhar. Os usuários informam :StartDate, e o aplicativo retorna os funcionários que começaram após essa data.

Como vincular uma expressão de consulta a uma IU

À medida que você adiciona parâmetros (precedidos de dois pontos) à sua expressão, eles são reconhecidos automaticamente pelo criador de consultas, e são criados parâmetros de consulta na área abaixo dele. Esses parâmetros também são exibidos na IU de vinculação de dados, que você usa para vincular os parâmetros aos widgets do aplicativo.

Para usar o exemplo do banco de dados de RH, as próximas etapas são:

  1. abrir os widgets e adicionar duas caixas de texto a uma página;
  2. vincular as propriedades value da caixa de texto a:
    • @datasource.query.parameters.AgeMin
    • @datasource.query.parameters.AgeMax
  3. adicionar um widget de caixa de data à página;
  4. vincular a propriedade value do widget de caixa de data a:
    • @datasource.query.parameters.StartDate
  5. alterar o evento onValueChange para Recarregar fonte de dados do widget de entrada.

Mais exemplos do criador de consultas

Consulta Retorna
Age >= :AgeMin and Age <= :AgeMax and Active = :IsActive Todos os funcionários ativos entre a idade mínima e a idade máxima.
(Status = :Pending or Status = :Active) and Name startsWith :NamePrefix Todos os funcionários pendentes ou ativos com nomes que começam com NamePrefix.
!(Status = :Pending or Status = :Active) Todos os funcionários que não estão pendentes ou ativos.
Age >=? :AgeMin

Se o parâmetro de consulta AgeMin for nulo, todos os funcionários serão retornados. Caso contrário, os funcionários com idade superior à idade mínima serão retornados.

Esse operador pode ser útil quando você vincula o parâmetro de consulta AgeMin a uma IU. Por exemplo, se o parâmetro de consulta AgeMin estiver vinculado a um campo de texto, inicialmente todos os funcionários serão retornados. Os registros serão filtrados quando o usuário inserir um valor para AgeMin. Se o usuário limpar o campo de texto, todos os funcionários serão exibidos novamente.

Se a consulta usar o operador >= em vez de >=?, nenhum funcionário será retornado inicialmente ou quando o usuário limpar o campo de texto.

Role notIn :Engineering or :Marketing

Todos os funcionários que não estão em funções de engenharia ou marketing.

in e notIn funcionam bem com o widget de seleção múltipla , que permite aos usuários escolher mais de um dos vários parâmetros que você definiu.

Computer startsWith :Chromebook and notContains :Pixel Todos os funcionários que têm Chromebooks, independentemente do modelo específico, excetuando os funcionários com Chromebook Pixels.

Consulta SQL para SQL Calculado

Para saber mais informações, acesse Modelos SQL calculados.

Outras propriedades da fonte de dados de consulta

Tamanho da página

Com a configuração do tamanho da página, é possível controlar o número de registros retornados pela fonte de dados para uma consulta. Use essa configuração para controlar o número de resultados retornados na IU e melhorar o desempenho. Se o servidor tiver 10.000 registros, carregar todos de uma vez será um processo lento e não manejável na IU. Em vez disso, defina um tamanho de página e crie um botão Próximo para chamar o método nextPage na fonte de dados.

Para mostrar todos os registros, defina o tamanho da página como zero.

O tamanho da página é uma propriedade da fonte de dados. Por isso, é possível:

  • vincular propriedades do widget a ele;
  • acessar e modificar o tamanho da página em scripts do lado do cliente.

Por exemplo, deixe o usuário controlar quantos registros são mostrados vinculando a propriedade value de um widget de controle deslizante à propriedade pageSize da fonte de dados.

Classificação

Classifique os registros por qualquer campo classificável em ordem crescente ou decrescente. Para classificar por mais de um campo, use um script de consulta do cliente.

Modo de salvamento manual

Quando o valor de um item da fonte de dados é alterado no App Maker, a alteração é salva automática e imediatamente no servidor por padrão. Por exemplo, se um usuário alterar o valor em um widget de campo de texto, o novo valor será salvo automaticamente no campo do registro vinculado.

Para desativar esse comportamento de salvamento automático, configure a fonte de dados para o modo de salvamento manual. Na guia Fontes de dados do editor de Modelos, selecione a caixa de seleção Modo de salvamento manual.

No modo de salvamento manual, as alterações precisam ser salvas explicitamente na IU ou no script. Na IU, seus campos e formulários de entrada se comportam como formulários tradicionais da Web e necessitam da ação do usuário. Um usuário precisa clicar em um botão Salvar que tenha a ação onClick Salvar alterações na fonte de dados.

Em um script do lado do cliente, use os seguintes métodos para o gerenciamento de alterações:

  • saveChanges: as alterações atuais são salvas no servidor.
  • clearChanges: todas as alterações feitas após a última chamada a saveChanges são abandonadas.
  • hasChanges: true é retornado se a fonte de dados tiver alterações não salvas.

As alterações feitas nos registros acessados por meio das propriedades item e items da fonte de dados, incluindo aqueles acessados por meio das propriedades relacionais, são armazenadas localmente no cliente e podem ser salvas ou revertidas.

Carregar dados automaticamente

Por padrão, os dados das fontes são carregados automaticamente sempre que um widget é vinculado aos dados delas. Quando você desmarca a caixa de seleção Carregar dados automaticamente, os dados só são carregados quando você chama os métodos load, loadPage, nextPage ou prevPage.

Atrase o carregamento dos dados quando você quiser que o usuário informe o valor de um filtro de consulta antes do carregamento.

Ação OnLoad

Para executar o JavaScript do lado do cliente sempre que a fonte de dados for carregada, insira o script na caixa de código. A ação onLoad é acionada sempre que os resultados de uma consulta são retornados do servidor para o cliente. Há mais informações sobre o carregamento na seção ciclo de vida da fonte de dados.

Ação de alteração no item

Para executar o JavaScript do lado do cliente sempre que o item atual for alterado, insira o script na caixa de código.

O item atual pode ser alterado pelos seguintes motivos:

  • Os dados da fonte são recarregados, e o item atual não está nos dados retornados.
  • Os métodos next ou prev são chamados por um script do lado do cliente na fonte de dados.
  • Um valor é atribuído à propriedade item da fonte de dados por um script ou vínculo do lado do cliente.
  • Os métodos selectIndex ou selectKey são chamados na fonte de dados por um script do lado do cliente.
  • Em alguns widgets, o item atual da fonte de dados é alterado automaticamente. Por exemplo, no widget de lista, o item atual da fonte de dados é alterado sempre que o usuário clica em uma linha.

Pré-busca

A pré-busca é usada para carregar, de maneira eficiente, registros associados de uma extremidade da relação quando são usados por um script ou IU do lado do cliente. Se os registros das relações forem usados pelos scripts do cliente, será necessário carregar explicitamente os registros associados do servidor, porque os registros associados da outra extremidade da relação não serão carregados automaticamente. Uma forma de carregar registros associados é ativar a pré-busca, o que instrui o App Maker a carregar registros relacionados ao carregar os resultados da consulta.

A pré-busca pode melhorar o desempenho da IU quando a fonte de dados tem muitos registros e você precisa carregar os registros associados a todos eles. Por exemplo, você tem um modelo Funcionários com uma relação Gerente para ele mesmo com duas extremidades de relação: Gerente e TeamMembers. A IU exibe uma lista de registros de Funcionários com base em uma fonte de dados de consulta e o Gerente de cada funcionário.

Sem a pré-busca, o registro do gerente associado a cada registro de funcionário na fonte de dados é solicitado. Esse processo é potencialmente lento porque requer muitos pedidos para o servidor. Com a pré-busca ativada, os registros associados são carregados com os resultados da consulta, e a IU fica mais rápida após o carregamento inicial.

Aprenda outras formas de carregar registros associados ao cliente em Modificar associações com um script do cliente.

Refinar a consulta à fonte de dados no cliente

Uma fonte de dados de consulta contém propriedades e métodos que podem ser usados para modificar a consulta com um script do cliente. O objeto da consulta representa a consulta que é enviada ao servidor quando uma fonte de dados é carregada. Ele contém propriedades que especificam as condições da consulta e a página de resultados a serem retornados.

Quando você aciona uma carga em uma fonte de dados de consulta:

  1. a consulta atual é enviada ao servidor;
  2. os dados da fonte de consulta são atualizados com os resultados da consulta;
  3. os registros do cliente também são atualizados com os resultados da consulta.

Quando você carrega uma fonte de dados de consulta, pode receber alterações nos valores dos registros no cliente, mesmo que os registros no resultado da consulta não sejam alterados. Isso acontece quando um script do lado do servidor ou outro cliente altera o registro.

Filtros

A propriedade filters do objeto de consulta contém as condições da consulta aos campos de um modelo. Use a seguinte sintaxe para especificar um filtro:

datasource.query.filters.field-id.filter-operator = value

Em que:

  • field-id é um campo no modelo que pode ser usado para filtragem.
  • filter-operator é a ação do filtro, como equals ou contains. Os operadores de filtro compatíveis dependem do tipo de campo e do banco de dados. Saiba mais sobre os operadores de filtro na documentação de consulta da API do cliente.
  • value é o parâmetro usado para o campo e o operador na consulta. O tipo de valor precisa corresponder ao tipo do campo, exceto para os operadores in e notIn. Para os operadores in e notIn, os valores dos parâmetros precisam ser matrizes do tipo de campo.

Para um campo de lista, um ou mais itens na lista precisam satisfazer o filtro de consulta. Se você atribuir vários valores a propriedades em filters, os registros precisarão corresponder a todos os filtros a serem carregados.

O objeto de consulta de fontes de dados de modelo do Cloud SQL também contém propriedades de filtro relacional. Com essas propriedades, é possível filtrar registros por um registro associado, o campo ou a chave dele. A filtragem é compatível apenas com relações um para um e muitos para um.

Exemplos de consulta do cliente:

  • Filtro único: com o código a seguir, um filtro de consulta é adicionado a uma fonte de dados de widget que retorna registros com o nome "John Smith":

    var datasource = widget.datasource;
    datasource.query.filters.Name._equals = 'John Smith';

  • Mais de um filtro: com o código a seguir, são adicionados filtros de consulta que correspondam aos registros que começem com o nome "John" e com idade maior que 18.

    var datasource = widget.datasource;
    datasource.query.filters.Name._startsWith = 'John';
    datasource.query.filters.Age._greaterThan = 18;

  • Correspondência de campo da lista: com a consulta a seguir, é carregado o registro record.Emails = ['smith.j@example.com', 'john@example.com'] porque um dos itens do campo da lista de e-mails começa com john@:

    datasource.query.filters.Emails._startsWith = 'john@';

  • Operador in: no código a seguir, o operador in é usado em um filtro de consulta para carregar registros em que o valor do campo favoriteColor é azul ou verde:

    var datasource = widget.datasource;
    var colors = ['blue', 'green'];
    datasource.query.filters.FavoriteColor._in = colors;

  • Filtro de campo relacional: se o modelo Empregado tiver uma relação um para muitos consigo mesmo que represente os gerentes e os membros da equipe, será possível:

    • carregar registros de membros da equipe atribuídos ao manager1:

      var datasource = widget.datasource;
      datasource.query.filters.Manager._equals = 'manager1';

    • filtrar por chaves de registro do gerente:

      datasource.query.filters.Manager._key._in = ['manager1RecordKey', 'manager2RecordKey'];

    • filtrar pelo nome do gerente:

      datasource.query.filters.Manager.Manager.Name._equals = 'John Doe';

    Como em outros filtros de campo, se você definir o valor da propriedade de filtro relacional como null, o filtro não será aplicado.

Classificação

Substitua a classificação configurada em um script do cliente para a fonte de dados. Classifique os dados por um ou mais campos classificáveis do modelo da fonte de dados. Para fontes de dados de modelo do Cloud SQL, também é possível classificar por campos em registros relacionados, desde que as extremidades das relações sejam de um para um ou de muitos para um. Por exemplo, se você tiver uma relação de muitos para um entre Cidades e Estado, poderá classificar as cidades pelo estado delas.

Saiba mais sobre a propriedade de classificação de consultas.

Índice da página

A propriedade de índice da página especifica o número da página a ser carregada. Por padrão, a página 1 dos resultados da consulta é carregada. Altere essa propriedade para qualquer número positivo. Os registros desse número de página serão carregados na próxima vez em que a fonte de dados da consulta for carregada.

Tamanho da página

A propriedade de tamanho da página especifica o número de registros a serem retornados do servidor para um resultado da consulta.

Fontes de dados relacionais

Com as fontes de dados relacionais, é fácil exibir os registros associados a um registro a partir da fonte de dados de uma extremidade da relação.

Defina uma fonte de dados relacional para um widget no Editor de propriedade. A caixa de diálogo da fonte de dados mostra uma fonte de dados relacional para cada relação configurada para o modelo pai. Saiba como selecionar as fontes de dados relacionais na IU em Como vincular dados à IU. Trabalhe com um exemplo no tutorial Conectar modelos de dados.

Carregar registros associados

Quando o widget configurado com uma fonte de dados relacional é carregado, os registros associados ao registro atual são carregados automaticamente. Registros associados também são carregados quando você ativa uma carga em uma fonte de dados relacional.

Certifique-se de que os registros associados sejam carregados antes que o aplicativo use os dados. Para executar um script ou ser notificado quando as associações de um registro forem carregadas, use o evento onDataLoaded para um widget. Uma abordagem comum para usar registros associados em seu aplicativo é:

  1. criar um painel invisível que use uma fonte de dados relacional para garantir que os dados relacionados sejam carregados;
  2. usar o evento onDataLoaded no painel invisível para executar alguma lógica que use os dados relacionados.

Para recarregar registros associados do servidor, chame load em uma fonte de dados relacional. Pode ser melhor recarregar os registros associados quando eles forem alterados por um script do servidor em vez de por scripts ou vínculos do lado do cliente.

Também é possível usar o método _reload no registro atual para recarregar os registros associados.

Fontes de dados de modo de criação

Use uma fonte de dados de modo de criação para criar itens em uma fonte de dados de consulta pai/mãe ou fonte de dados relacional que não são salvos automaticamente no banco de dados. Em vez disso, os dados são armazenados em um registro de rascunho no lado do cliente até que o usuário acione uma ação para salvar o registro. O registro de rascunho também pode servir de modelo para novos registros. A fonte de dados de modo de criação pertence ao mesmo modelo que a fonte de dados pai/mãe.

Com a fonte de dados de modo de criação, é possível:

  • vincular elementos da IU a campos na fonte de dados de modo de criação. Esses campos preencherão o registro de rascunho com valores;
  • definir valores de campo padrão para o registro da fonte de dados. Com essa abordagem, os campos obrigatórios sempre terão valores. Depois que um registro é salvo no banco de dados por uma fonte de dados de modo de criação, os valores do campo são redefinidos para seus valores padrão. Defina valores padrão com um script ou na IU.

Trabalhe com fontes de dados de modo de criação com a IU do aplicativo e com um script do cliente.

Criar registros com um formulário

Valores em formulários de tipo entrada são vinculados a campos na fonte de dados de modo de criação por padrão. Quando um usuário preenche o formulário, os valores são salvos no registro de rascunho. A fonte de dados de modo de criação é @datasource.parent-datasource.modes.create, relatada pela IU como parent-datasource (create). Cada campo do formulário está vinculado a datasource.item.field, que corresponde aos campos no registro de rascunho.

Quando um usuário preenche o formulário, o registro é salvo no cliente até que o usuário clique em Enviar. A ação onClick do botão Enviar é datasource.item.createItem(), que cria o item e o adiciona à fonte de dados pai/mãe. A ação onClick do botão Limpar é widget.datasource.clearChanges(), que limpa o registro da fonte de dados de criação.

Saiba mais em Widgets de dados: formulário e no tutorial Trabalhar com dados.

Criar registros com um script

Os scripts do cliente podem adicionar registros a fontes de dados de modo de criação. Adicione registros dessa maneira quando quiser:

  • adicionar automaticamente dados da sessão, como o nome de usuário e a data de criação do registro;
  • processar dados de um formulário antes de criar o registro para que ele corresponda a um campo na fonte de dados, como para concatenar nomes e sobrenomes.

Por exemplo, você tem um modelo People com um campo DateAdded. Se você definir a propriedade DateAdded do registro da fonte de dados de modo de criação como new Date();, um registro criado por essa fonte de dados terá a data atual do fuso horário do usuário para iniciar:

var createDatasource = app.datasources.people.modes.create;
var draft = createDatasource.item;
draft.DateAdded = new Date();
createDatasource.createItem(function(createdRecord) {
 alert('Created record on ' + createdRecord.DateAdded)
});

Saiba mais sobre CreateDataSource.