DataSources

Nessa seção, apresentamos a estrutura de DataSources e todas as propriedades de cada um de seus respectivos níveis. A seguir, apresentamos uma possível estrutura para DataSources:

../_images/dataSources1.png

Fig. Estrutura completa de um DataSource de exemplo

DataSources

icon1 DataSources é o primeiro nível da estrutura, que contém um ou mais DataSourceGroups.

Identificação

Propriedade

Descrição

Default

Nome do item

Define o nome do item que será exibido na árvore do painel de projeto e será utilizado quando necessário referenciar o mesmo.

Item_NNN

Comentário

Permite a inclusão de um comentário acerca do objeto. Este campo não é obrigatório.

(Nenhum)

DataSourceGroup

icon2 DataSourceGroup é o segundo nível da estrutura, que pode apresentar um ou mais DataSources. Também é possível criar mais de um DataSourceGroup de acordo com a necessidade do usuário.

Propriedades de identificação do objeto

Propriedade

Descrição

Default

Nome do item

Define o nome do item que será exibido na árvore do painel de projeto e será utilizado quando necessário referenciar o mesmo.

Item_NNN

Comentário

Permite a inclusão de um comentário acerca do objeto. Este campo não é obrigatório.

(Nenhum)

Descrição

Texto opcional que permite a inclusão de uma breve descrição do item associado. Este campo é apenas documental.

(Nenhum)

DataSource

icon3 DataSource é o terceiro nível da estrutura, onde cada DataSource apresenta como subnível as colunas (também chamadas de fields) que formam todo um registro de um DataSource.

Propriedades de identificação do objeto

Propriedade

Descrição

Default

Nome do item

Define o nome do item que será exibido na árvore do painel de projeto e será utilizado quando necessário referenciar o mesmo.

Item_NNN

Comentário

Permite a inclusão de um comentário acerca do objeto. Este campo não é obrigatório.

(Nenhum)

Argumentos

Neste campo pode-se inserir uma string que será o valor da propriedade Argument do item. A string fornecida é uma forma geral de passagem de parâmetros para os scripts associados ao objeto durante sua execução.

(Nenhum)

Propriedades Específicas

Propriedade

Descrição

Default

Query

Define um item Query previamente criado que retorna as colunas e os respectivos registros da consulta para utilização no DataSource. É importante observar que o item Query configurado aqui deve estar associado a um item de Database cujo o proprietário da conexão seja o Viewer ou Kernel e Viewer e que o driver da conexão não seja o SQLite.

Somente leitura

Define se o DataSource selecionado pode ter seus registros alterados ou se é permitida apenas a leitura de seus registros.

Não

Modo de atualização

Define por qual modo o DataSource receberá as atualizações feitas pelo usuário.

Opções:

  • Utiliza apenas a chave primária

  • Utiliza todas as colunas

  • Utiliza a chave primária e o valor original das colunas

Utiliza apenas a chave primária

Exibe mensagem de confirmação para atualização dos registros

Define se uma mensagem de confirmação será exibida sempre que o Data Source for atualizado.

Não

Atualiza objetos após evento de atualização da Query

Define se os objetos associados ao DataSource receberão as atualizações de forma automática.

Sim

Habilita atualização periódica Z1

Define se os registros do DataSource serão atualizados após o tempo de atualização definido.

Não

Tempo de atualização(ms)

Z1 Define um tempo de atualização para os campos do DataSource.

1000

Obtém metadados da base de dados

Define se o DataSource utilizará metadados definidos no DataBase associado à Query.

Sim

Atualiza lista campos

Botão para atualizar os campos(fields) do DataSource .

Lista de campos(fields) do DataSource

Apresenta a lista de campos(fields) do DataSource em que a Query trás na consulta no DataBase.

obs

Conforme explicado acima, o item Query a ser utilizado na propriedade Query de um DataSource deve estar associado a um item de DataBase cujo proprietário da conexão com o banco de dados seja o Viewer ou Kernel e Viewer. Isso significa que o recurso de DataSource não é compatível com conexões realizadas apenas pelo Kernel e logo, com o banco de dados SQLite. Para maiores informações, acesse: Definindo o módulo Proprietário da conexão de um item DataBase.

Propriedades de Edição de Registros

Propriedade

Descrição

Default

Permite edição de registros Z1

Define se os registros do DataSource podem ser editados.

Não

Grupo com permissão para edição

Z1 Define qual grupo tem permissão para editar o DataSource.

Todos os grupos

Exibe mensagem de confirmação

Z1 Define se uma mensagem será exibida quando a edição de um ou mais registros ocorrer.

Não

Propriedades de Inserção de Registros

Propriedade

Descrição

Default

Permite inserção de registros Z1

Define se podem ser inseridos registros no DataSource.

Não

Grupo com permissão para inserção

Z1 Define os grupos que tem permissão para inserir registros no DataSource.

Todos os grupos

Exibe mensagem de confirmação

Z1 Define se uma mensagem será exibida quando a inserção de um ou mais registros ocorrer.

Não

Propriedades de Exclusão de Registros

Propriedade

Descrição

Default

Permite remoção de registros Z1

Define se podem ser removidos registros no DataSource.

Não

Grupo com permissão para exclusão

Z1 Define os grupos que tem permissão para excluir registros no DataSource.

Todos os grupos

Exibe mensagem de confirmação

Z1 Define se uma mensagem será exibida quando a remoção de um ou mais registros ocorrer.

Não

Propriedades de Aplicação de Alterações no Banco de Dados

Propriedade

Descrição

Default

Permite aplicar alterações no banco de dados Z1

Define se as alterações realizadas no DataSource podem ser aplicadas no DataBase.

Não

Grupo com permissão para aplicar alterações

Z1 Define os grupos que tem permissão para aplicar as alterações do DataSource no DataBase.

Todos os grupos

Exibe mensagem de confirmação

Z1 Define se uma mensagem será exibida quando a aplicação das alterações de registros do DataSource ocorrer no DataBase.

Não

DataSourceFields

icon4 DataSourceFields é o quarto nível da estrutura, que apresenta de forma agrupada todos os campos(fields) de um DataSource.

Identificação

Propriedade

Descrição

Default

Nome do item

Define o nome do item que será exibido na árvore do painel de projeto e será utilizado quando necessário referenciar o mesmo.

Item_NNN

Comentário

Permite a inclusão de um comentário acerca do objeto. Este campo não é obrigatório.

(Nenhum)

Propriedades Específicas

Propriedade

Descrição

Default

Gera Itens de campos(fields)

Selecionada uma Query, faz com que os campos (fields) do DataBase sejam gerados no DataSource, caso a criação não ocorra automaticamente.

DataSourceField

icon5 DataSourceField é o último nível da estrutura que representa uma coluna do DataSource.

Propriedades de identificação do objeto

Propriedade

Descrição

Default

Nome do item

Define o nome do item que será exibido na árvore do painel de projeto e será utilizado quando necessário referenciar o mesmo.

Item_NNN

Comentário

Permite a inclusão de um comentário acerca do objeto. Este campo não é obrigatório.

(Nenhum)

Argumentos

Neste campo pode-se inserir uma string que será o valor da propriedade Argument do item. A string fornecida é uma forma geral de passagem de parâmetros para os scripts associados ao objeto durante sua execução.

(Nenhum)

Propriedades Específicas

Propriedade

Descrição

Default

Nome do Campo(field) do Data Source

Define no DataSource o nome da coluna recebido do DataBase de acordo com a Query associada.

Depende N

Tipo de dado

Define o tipo de dado da coluna que é recebido do DataBase.

Depende N

Requerido

Define se o campo(field) recebido do DataBase é requerido na inserção e/ou edição.

Depende N

Somente leitura

Define se o campo(field) recebido do DataBase é somente para leitura ou se permite edição.

Depende N

Formato de apresentação

Define o formato de apresentação do dado do campo(field) de acordo com o Tipo de dado definido no DataBase.

Depende N

obs

Os valores de Formatação de um DataSourceField dependem da definição do tipo de dado no DataBase. Se o tipo de dado é Integer, então o formato de apresentação será %d. Para saber mais sobre tipos de dados e seus formatos, acesse Formatação de Valores em Edit e Display.

Opções de utilização

Propriedade

Descrição

Default

Nas cláusulas de todas instruções SQL

Define se o campo(field) será utilizado nas cláusulas de todas as intruções SQL definidas na query.

Sim

Nas cláusulas de atualização

Define se o campo(field) será utilizado nas cláusulas de atualização do Data Source.

Sim

Como chave única das cláusulas de atualização

Define se o campo(field) será utilizado como chave única nas cláusulas de atualização do DataSource.

Não

API Lua

A lista das propriedades e atributos deste e outros componentes estão documentadas em Scripts e Acesso a atributos e funções de Componentes de Tela. A seguir apresentamos as tabelas com as propriedades e atributos de gerenciamento que podem ser utilizados via scripts, para o objeto descrito nessa página:

DataSources

DataSources

Funções

Descrição

GetSelectedFieldValueFromName

Retorna o valor de um campo(field) do DataSource, dado o nome da coluna. Se um registro estiver selecionado em um objeto de tela para banco de dados, retorna o valor correspondente. Caso contrário, retorna o valor do priemiro registro da coluna.

SetSelectedFieldValueFromName

Atribui um novo valor ao campo(field) do DataSource selecionado em um objeto de tela para banco de dados.

ExecuteDataSourceCommand

Permite executar comandos para manipular os registros do DataSource. A seguir temos a lista de possiveis operações que podem ser realizadas via script.

Opções:

  • 0 = Edit (Edição)

  • 1 = Post (Postagem)

  • 2 = Insert (Inserção)

  • 3 = Append (Acréscimo)

  • 4 = ApplyUpdates (Aplicar atualizações)

  • 5 = CancelUpdates (Cancelar atualizações)

  • 6 = Refresh (Recarregar)

  • 7 = Delete (Deleção)

  • 8 = Open (Abrir)

  • 9 = Close (Fechar)

  • 10 = Cancel (Cancelar)

  • 11 = Active (Ativação)

  • 12 = ActiveFalse (Não fazer Ativação)

  • 13 = ActiveTrue (Fazer Ativação)

FilterRecordsDataSource

Permite filtrar os dados de um DataSource definindo, como parâmetro do método, um tipo de filtro e um valor. A seguir são apresentados os possiveis tipos de filtros que podem aplicados sobre os registros do DataSource.

Opções:

  • 0 = Equal (Igual)

  • 1 = Otherwise (Diferente)

  • 2 = Smaller (Menor)

  • 3 = Bigger (Maior)

  • 4 = Smaller or Equal (Menor ou Igual)

  • 5 = Bigger or Equal (Maior ou Igual)

  • 6 = Not (Não)

  • 7 = Like (Semelhante)

  • 8 = Not Like (Não Semelhante)

RemoveFilterRecordsDataSource

Permite remover uma filtragem previamente realizada em um DataSource.

LocateRecordDataSource

Permite localizar no DataSource um valor especificado como parâmetro da função.

SortRecordsDataSource

Permite ordenar os dados do DataSource tomando uma coluna como base para a ordenação. A ordenação pode ser feita de três formas.

Opções:

  • 0 = Descendente

  • 1 = Ascendente

  • 2 = Ambos

Se o modo de ordenação é Ambos, uma primeira ação ordena de forma Descendente, uma segunda ação ordena de forma Ascendente, e uma terceira ação retorna os dados para o estado original.

Exemplos de uso de DataSources

GetSelectedFieldValueFromName
-- DataSources é o manager para trabalhar com Data Sources via Scripts.
-- GetDataSource é uma função que retorna um objeto Data Source dado uma String que informa o
-- caminho do Data Source na árvore de projeto
datasource = DataSources.GetDataSource('Viewers.DataSources.DataSourceGroup_001.DataSource_001')
-- A variável valor recebe , através da função GetSelectedFieldValueFromName() , o campo/valor,
-- selecionado em um objeto de tela, da coluna 'nome' armazenado no DataSource
valor = datasource:GetSelectedFieldValueFromName('nome_coluna')
print(valor)
SetSelectedFieldValueFromName
 local datasource = DataSources.GetDataSource('Viewers.DataSources.DataSourceGroup_001.DataSource_001')
 -- Parâmetro 1 : Nome da coluna (string)
 -- Parâmetro 2 : Novo valor a ser inserido no registro (string)
 -- Parâmetro 3 : Flag para indicar se alteração deve ser persistida no DataBase ou não (boolean)
 -- Se 0, alteração não persiste
 -- Se 1, alteração persiste
 datasource:SetSelectedFieldValueFromName('nome_coluna','novo_valor',1)

-- Print para verificação da alteração
print(datasource:GetSelectedFieldValueFromName('nome_coluna'))

-- Opcional: utilize um DBLookupListBox na interface para verificar aplicação desta FUNCTION
ExecuteDataSourceCommand
local datasource = DataSources.GetDataSource('Viewers.DataSources.DataSourceGroup_001.DataSource_001')
-- Dada a lista de comandos na descricao da tabela de funções:
-- Parâmetro 1 : Comando a ser executado sobre o DataSource (inteiro de 0 a 13)
-- Parâmetro 2 : Flag que indica a execucao da FUNCTION (inteiro)

-- 6 indica comando de atualizacao (Refresh) do DataSource
datasource:ExecuteDataSourceCommand(6,0)

-- Opcional: utilize um DBGrid na interface para verificar a aplicação desta FUNCTION
--           e também um botão para acionar o script.
FilterRecordsDataSource
local datasource = DataSources.GetDataSource('Viewers.DataSources.DataSourceGroup_001.DataSource_001')
-- Parâmetro 1 : Nome da coluna do DataSource onde sera feita a filtragem (string)
-- Parâmetro 2 : Valor que deve ser filtrado de acordo com um tipo de filtro (string)
-- Parâmetro 3 : Tipo de filtro aplicado (inteiro de 0 a 8)
datasource:FilterRecordsDataSource('nome_coluna','valor_filtrado', 0)

-- Opcional: Utilize um DBGrid na interface para verificar a aplicação desta FUNCTION
--           e também um botão para acionar o script.
RemoveFilterRecordsDataSource
local datasource = DataSources.GetDataSource('Viewers.DataSources.DataSourceGroup_001.DataSource_001')
-- Essa função não recebe parâmetro pois apenas remove um filtro previamente aplicado ao DataSource.
datasource:RemoveFilterRecordsDataSource()

-- Opcional: Utilize um DBGrid na interface para verificar a aplicação desta FUNCTION
--           e também um botão para acionar o script.
LocateRecordDataSource
local datasource = DataSources.GetDataSource('Viewers.DataSources.DataSourceGroup_001.DataSource_001')
-- Parâmetro 1 : Nome da coluna do DataSource onde sera feita a busca (string)
-- Parâmetro 2 : Valor que deve ser buscado na coluna (string)
datasource:LocateRecordDataSource('nome_coluna', 'valor_buscado')

-- Opcional: Utilize um DBGrid na interface para verificar a aplicação desta FUNCTION
--           e também um botão para acionar o script.

-- Exemplo de script que utiliza um campo Edit, um Botão e o DBGrid na interface para digitar o valor a
-- ser buscado:

local datasource = DataSources.GetDataSource('Viewers.DataSources.DataSourceGroup_001.DataSource_001')
local tag = Tags.Get('Kernel.Tags.Local.TagLocalGroup_001.TagLocal_001')
datasource:LocateRecordDataSource('nome', tostring(tag.Value))
SortRecordsDataSource
local datasource = DataSources.GetDataSource('Viewers.DataSources.DataSourceGroup_001.DataSource_001')
-- Parâmetro 1 : Nome da coluna do DataSource que é tomada como base para a ordenacao (string)
-- Parâmetro 2 : Valor que especifica o tipo de ordenacao (inteiro de 0 a 2)
-- Parâmetro 3 : Valor que especifica se a ordenacao será aplicada ao DataSource (inteiro)
   -- se Parâmetro 3 = 0 , então ordenacao não é aplicada
   -- se Parâmetro 3 = 1 , então ordenacao é aplicada

datasource:SortRecordsDataSource('nome_coluna', valor_ordenacao, valor_aplicacao_no_DataSource)

-- Opcional: Utilize um DBGrid na interface para verificar a aplicação desta FUNCTION
--           e também um botão para acionar o script.

Ver também