Manual do Metadados – Linha Datasul

Parte 2
Framework


2
Versão 1.0
Manual do Metadados
Sumário (Parte 2)
7. Criando Formulários de CRUD ........................................................................................................................................... 2
8. Utilizando Zoom em Formulários de CRUD ........................................................................................................................ 2
9. Criando CRUDs Pai/Filho ................................................................................................................................................... 2
10. Introdução ao ABLScript .................................................................................................................................................... 2
11. Definindo Lógica de Tela em ABLScript para Formulários de CRUD ................................................................................... 2
12. Criando Formulários FreeForm .......................................................................................................................................... 2
13. Utilizando ABLScript em Formulário FreeForm .................................................................................................................. 2
14. Utilizando Includes e Procedures no ABLScript .................................................................................................................. 2



3
Manual do Metadados






Nesse capítulo veremos passo a passo como criar uma nova aplicação(módulo) e formulários de CRUD para
pesquisa e cadastramento de entidades de negócio.

Todo formulário deve estar associado a uma aplicação, dessa maneira devemos utilizar uma aplicação já
existente ou criar uma aplicação nova.

Para criar uma nova aplicação devemos fazer o seguinte:

 Na IDE do Metadados selecione na TAB Navegador o ítem Aplicações e em seguida clique em
Manutenção de Aplicações.

 Pressione o botão Adicionar e informe os campos Nome e Área de Negócio. Não utilize caracteres
acentuados e nem espaço nesses campos.

 Por fim pressione o botão Salvar.
As figuras a seguir mostram os passos para criação de um novo CRUD:


Figura 7a – Criando Formulários de CRUD – Passo 1

7. Criando Formulários de CRUD



4
Versão 1.0
Manual do Metadados

Figura Figura 7b – Criando Formulários de CRUD – Passo 2




Figura 7c – Criando Formulários de CRUD – Passo 3


5
Manual do Metadados





Figura 7d – Criando Formulários de CRUD – Passo 4




Figura 7e – Criando Formulários de CRUD – Passo 5



6
Versão 1.0
Manual do Metadados

Figura 7f – Criando Formulários de CRUD – Passo 6




Figura 7g – Criando Formulários de CRUD – Passo 7


7
Manual do Metadados




Figura 7h – Criando Formulários de CRUD – Passo 8





Figura 7i – Criando Formulários de CRUD – Passo 9



8
Versão 1.0
Manual do Metadados

Figura 7j – Criando Formulários de CRUD – Passo 10




As figuras 7k e 7l mostram telas do CRUD criado nos passos anteriores.



9
Manual do Metadados



Figura 7k – Tela de Pesquisa do CRUD


Figura 7l – Formulário de Filtro Avançado do CRUD


Ao solicitar a execução de um formulário de CRUD (linkbutton Executar na IDE), a Engine de Metadados
obtém os dados de cadastro do CRUD em questão, do dataset e da tabela. Com essas informações a Engine gera o
XML de Runtime que será utilizado pelo renderizador para criar a tela para o usuário. Os XMLs gerados para os
formulários ficam armazenados em uma estrutura de pastas no servidor do JBoss, conforme mostra a figura a seguir:


Figura 7m



10
Versão 1.0
Manual do Metadados
Na Figura 7m, a pasta raiz chama-se MD_DES, é dentro dessa pasta que são gerados os XMLs ao executar os
mesmos pela IDE. A segunda pasta indica a versão do produto que está selecionada na IDE, esse número representa
o fullNumber da versão. A terceira pasta que nesse exemplo está como framework, é o nome do usuário que está
utlizando a IDE. Então para cada usuário haverá uma geração de XML em pastas separadas.

Uma vez finalizado o desenvolvimento de uma aplicação ou módulo, devemos gerar os XMLS através do
seguinte item de menu: Assistente > Instalar Produto. Essa operação irá gerar os XMLs na pasta raiz MD sem criar
sub-pastas por usuário. Esses XMLs serão utilizados quando um usuário solicitar a execução de um formulário
através do Menu do Produto.
Na imagem a seguir vemos um exemplo de XML gerado:


Figura 7n

Nesse capítulo vimos como criar um CRUD e definir as telas de consulta, inclusão e alteração. Nessas telas,
além dos campos incluídos através do Dataset, podemos também acrescentar outros campos. Esses campos
adicionais podem ser de qualquer um dos tipos disponíveis na paleta de componentes. Para que esses campos
adicionais tenham funcionalidades, é necessário definir código ABLScript para os eventos correspondentes nesses
componentes.


11
Manual do Metadados





Em um CRUD cuja entidade(tabela) possua chaves estrangeiras, nos formulários do inclusão/alteração do
mesmo, podemos utilizar componentes do tipo Zoom para representar esse campos que são chave estrangeira.

Na Figura 8a, temos um exemplo de Zoom para a chave estrangeira Pais. Através desse componente é
possível informar manualmente o código da chave estrangeira diretamente no campo texto, ou clicar na lupa realizar
uma pesquisa de entidade. Ao clicar na lupa, será aberto o CRUD de Pais.



Figura 8a – Exemplo de Zoom




8. Utilizando Zoom em Formulários de CRUD



12
Versão 1.0
Manual do Metadados
Na Figura 8b, temos um diagrama que apresenta o relacionamento entre Editora e Pais.


Figura 8b – Exemplo de Zoom (chave estrangeira)

As figuras a seguir mostram os passos para cadastrar referências entre tabelas e criar campos de zoom.


Figura 8c – Cadastrando um Referência na Tabela Editora

13
Manual do Metadados






Figura 8d – Cadastrando um Referência na Tabela Editora



Figura 8e – Cadastrando um Referência na Tabela Editora


14
Versão 1.0
Manual do Metadados
Após cadastrar a referência, vamos no CRUD de Editora para informar para o campo codPais a propriedade
xmlName. Isso indicará para o componente de Zoom qual é o formulário de CRUD que deve ser aberto ao clicar na
lupa do Zoom.



Figura 8f – Definindo campo de Zoom



15
Manual do Metadados



Criando Legendas

Para pequenas listas de itens que não mudam e não requerem uma tabela no banco, podemos cadastrar
legendas para um determinado campo de tabela. Quando um campo possuir legendas cadastradas, no CRUD que
utilizar esse campo, o mesmo será representado por um combobox ou checkbox, de acordo com a quantidade de
legendas associadas ao campo. A figura 9g mostra um exemplo de cadastramento de legenda.



Figura 8g




16
Versão 1.0
Manual do Metadados



Nesse capítulo veremos os passos para criar formulários cuja entidade possua relacionamento do tipo
Pai/Filho (ou Mestre/Detalhe) com outras entidades. Por exemplo Pedido/Itens conforme o diagrama da figura a
seguir:

Figura 9a

Antes de criar um CRUD Pai/Filho precisamos definir corretamente as referências nas tabelas. No nosso exemplo
iremos criar uma referência na tabela Pedido conforme a Figura 10b. Onde selecionamos a cardinalidade para Many.


Figura 9b

9. Criando CRUDs Pai/Filho


17
Manual do Metadados



Para os CRUDs filhos apareçam nas ações relacionadas do Cadastro do PAI é necessário:

 Estar cadastrado no Foundation > Menu > Manutenção de Programa Produto Datasul;

 Neste programa usar o botão cadeado para liberar acesso para o grupo de usuário desejado
“Papel”.

 No metadados deve ter uma FK de 1 x N, desta forma é incluido nas ações relacionadas.

Essa tarefa é ilustrada na imagens a seguir:



Figura 9c





18
Versão 1.0
Manual do Metadados


O ABLScript é uma linguagem de script que permite a definição de lógicas de tela, como por exemplo:

• habilitação/desabilitação de campos e botões.
• validações de conteúdos de campos
• abertura/fechamento de formulários
• solicitação de execução de regras de negócio no servidor
• solicitação de dados ao servidor via execução de programas Progress
• entre outros.

Características Principais do ABLScript

• Sintaxe do Progress (linguagem utilizada na construção das lógicas de negócio no lado servidor)
• Subset de comandos/funções do Progress
• Orientada a Eventos
• Executa 100% no lado Cliente (browser)
• Editor com syntax highlight e code complete
• Suporte a mais de 100 comandos/funções
• Suporte a TEMP-TABLE e FOR EACH
• Suporte a Includes e Procedures


Figura 10a

A linguagem de programação nas versões atuais do Progress (OpenEdge) chama-se ABL (Abstract Business
Language).
Como o script do Metadados utiliza a mesma sintaxe e é um subset do ABL, o mesmo passou a ser chamado
de ABLScript.
O ABLScript é orientado a eventos, ou seja, os scripts são associados a eventos que podem ocorrer em
formulários ou em um de seus componentes.
Eventos de formulário podem ser por exemplo: beforeInsert, afterInsert, beforeDelete, creationComplete,
etc.
Eventos de componentes de um formulário podem ser: click, focusOut, change, hide, etc.

10. Introdução ao ABLScript


19
Manual do Metadados




Figura 10b

Uma vez escrito um script para um determinado evento de um formulário, basta executar o formulário e
fazer acontecer o evento para testar o script criado. Não é necessário nenhum tipo especial de compilação ou deploy
dos scripts.

A criação e edição de scripts é feita diretamente na IDE do Metadados através do editor de ABLScript aberto via
IDE. O editor possui alguns recursos que agilizam a criação de scripts:
• code complete com ajuda aos comandos (help)
• syntax highlight
• diversas teclas de atalho para inserção de código





20
Versão 1.0
Manual do Metadados
A figura 10c mostra a tela do Editor de ABLScript.


Figura 10c

Um script possui acesso a todos os componentes gráficos de seu formulário (campos, botões, etc), através
da declaração de variáveis específicas. Através dessas variáveis é possível ler ou definir atributos nesses
componentes ou executar funções disponíveis nos mesmos.

A documentação dos comandos disponíveis no ABLScript encontram-se no TDN, no endereço:

http://tdn.totvs.com.br/display/dts/ABLScript


21
Manual do Metadados




Figura 10d




22
Versão 1.0
Manual do Metadados


Em formulários de CRUD podemos criar scripts para dois tipos de eventos:

• Eventos de Formulário
o beforeInsert
o afterInsert
o beforeUpdate
o afterUpdate
o beforeDelete
o afterDelete
o onDetailFormShow
o onDetailFormHide
o onEditFormShow
o onEditFormHide
o onGridFormShow
o onNewRecord
o ....

• Eventos de Componentes (varia de acordo com o tipo de componente)
o change
o click
o doubleClick
o focusIn
o focusOut
o creationComplete
o hide
o show
o ....














11. Definindo Lógica de Tela em ABLScript para Formulários de CRUD


23
Manual do Metadados




Figura 11a


Figura 11b



Veremos a seguir um exemplo simples de script de formulário para o evento buildComplete do CRUDPais:


24
Versão 1.0
Manual do Metadados


Figura 11c

Ao executar o CRUD, após abrir a tela com o grid, será disparado o evento buildComplete. O script em
questão possui apenas um comando(DISPLAY) que imprime no console do ABLScript a string “Hello ABLScript
World!” conforme mostrado na figura 11d.


Figura 11d


Ao criar um ABLScript e executar o formulário, o Engine de Metadados ao gerar o XML de Runtime do
formulário, compila o ABLScript para Java e inclui o código no arquivo XML. Conforme mostra a figura 11e.


25
Manual do Metadados




Figura 11e


Figura 11f

Na figura 11f, a caixa em azul representa o tempo de deploy (geração do XML de Runtime). A IDE do
Metadados solicita a Engine do Metadados (representada pelos módulos MDGenerator e ABLScriptCompiler) que
gere o XML de runtime. A Engine obtém os registros referentes ao formulário no banco do Metadados, incluindo os


26
Versão 1.0
Manual do Metadados
códigos ABLScript. O MDGenerator, responsável por gerar o XML, passa os códigos ABLScript para serem compilados
pelo módulo ABLScriptCompiler. O código compilado em formato Java é então incluído no XML.
A caixa amarela representa o tempo de execução do formulário. Quando acontece um evento no formulário que
tenha um ABLScript associado, o renderizador de formulários (representado pela caixa verde), passa o código do
script (em formato Java) para ser executado pelo ABLScriptApplet. Esse último por sua vez, comunica-se com a
camada Flex toda vez que precisa ler ou alterar propriedades nos componentes do formulário.

Exemplo de Evento de Componente (nome.focusOut):



Figura 11g

Mais Exemplos:

CRUDPais.nome.focusOut:

DEFINE VARIABLE nome AS WIDGET-HANDLE.
DEFINE VARIABLE sigla AS WIDGET-HANDLE.
DEFINE VARIABLE value AS CHARACTER.

value = nome:SCREEN-VALUE.

sigla:SCREEN-VALUE = SUBSTRING(value, 0, 2).

-----------------------------------------------------------

CRUDPais.nome.focusOut:

DEFINE VARIABLE nome AS WIDGET-HANDLE.
DEFINE VARIABLE sigla AS WIDGET-HANDLE.
DEFINE VARIABLE value AS CHARACTER.

value = nome:SCREEN-VALUE.

27
Manual do Metadados



value = SUBSTRING(value, 0, 2).
value = CAPS(value).

sigla:SCREEN-VALUE = value.

-----------------------------------------------------------

CRUDPais.beforeInsert:

DEFINE VARIABLE sigla AS WIDGET-HANDLE.
DEFINE VARIABLE tam AS INTEGER.

tam = LENGTH(sigla:SCREEN-VALUE).

IF tam = 0 THEN DO:
MESSAGE "Sigla nao informada. Sera utilizado o valor padrao."
VIEW-AS ALERT-BOX.
sigla:SCREEN-VALUE = "NI".
END.

----------------------------------------------------------------------------------------------------------

CRUDPais.codigo.focusOut:

DEFINE VARIABLE primaryKey_codigo AS WIDGET-HANDLE.
DEFINE VARIABLE sigla AS WIDGET-HANDLE.
DEFINE VARIABLE x AS INTEGER.

x = INTEGER(primaryKey_codigo:SCREEN-VALUE).

IF x < 10 THEN DO:
MESSAGE "Codigo deve ser maior do que 10!"
VIEW-AS ALERT-BOX.
END.
ELSE IF x > 200 THEN DO:
sigla:SENSITIVE = FALSE.
END.




28
Versão 1.0
Manual do Metadados



O FreeForm é um tipo de formulário utilizado pelo Metadados que não possui nenhum layout previamente
definido. Com ele é possível criar os mais variados tipos de tela. Cada tela do tipo FreeForm poderá ter vários
componentes e sub-componentes que irão possuir propriedades e eventos associados. Tanto as propriedades
quanto os eventos irão variar de acordo com o componente em questão. Por exemplo, para um componente do tipo
Button, poderemos ter propriedades como label, width, height e eventos como click, focusIn, focusOut, etc. O
renderizador cria o componente de acordo com seu tipo e aplica as propriedades e valores informados no momento
em que a tela for apresentada pela primeira vez ao usuário.





Nas figuras a seguir veremos os passos para criar um formulário do tipo FreeForm(View):


Figura 12a




12. Criando Formulários FreeForm


29
Manual do Metadados





Figura 12b


Figura 12c



30
Versão 1.0
Manual do Metadados

Figura 12d


Figura 12e


31
Manual do Metadados



Após finalizar a distribuição dos componentes no formulário e setar as propriedades dos mesmos, salve e
execute o formulário.

O próximo passo é adicionar scripts para os eventos dos componentes do formulário como veremos no
próximo capítulo.





No capítulo 11 vimos como criar scripts para formulários de CRUD. Nesses formulários existem dois tipos de
eventos: eventos de formulário e eventos de componentes. No caso de formulários FreeForm, existem apenas
eventos de componente. Fora isso, a criação e utilização de ABLScript é igual para os formulários FreeForm. Nesse
capítulo veremos mais uma série de exemplos, orientações e dicas para utilização do ABLScript.

No exemplo a seguir veremos como utilizar os componentes ComboBox, DataGrid e diversos comandos
ABLScript, incluindo o comando RUN para realizar chamadas ao Progress.

Utilizaremos o seguinte FreeForm:


Figura 13a

Na área de declaração de variáveis do formulário, defina as variáveis para representar os componentes de
tela (do tipo WIDGET-HANDLE). No navegador da IDE abra o formulário e na tab de Estrutura selecione o nome do
formulário (raiz da árvore). Clique em Código, em seguida no combo de eventos selecione varDefinition e clique no
link button Editar para abrir o editor de ABLScript.

A figura a seguir mostra a declaração de variáveis que será utilizadas nos demais scrits do formulário.

13. Utilizando ABLScript em Formulário FreeForm



32
Versão 1.0
Manual do Metadados

Figura 13b

Importante:

 No varDefinition só é possível declarar variáveis, não é permitido qualquer tipo de comando do
ABLScript que não seja para criar variáveis.
 Todas as variáveis declaradas no varDefinition estarão disponíveis em todos os scripts do formulário.
Para reduzir o uso de memória, evite declarar variáveis nessa área que seja usada em apenas um ou
dois scripts. Nesses casos declare essas variáveis no próprio script.

Dica: para declarar variáveis do tipo WIDGET-HANDLE utilize o atalho: CTRL + SHIFT + H. Isso abrirá a janela
conforme figura 13c.


Figura 13c





33
Manual do Metadados



No evento creationComplete do canvas iremos realizar duas tarefas, inicializar o combobox com itens e
definir as colunas do grid através da declaração de uma TEMP-TABLE, conforme a figura 13d.


Figura 13d


No click do botão Filtrar teremos um script que irá através do comando RUN realizar uma chamada a um
programa Progress (livrosvendidos.p), que por sua vez retornará uma TEMP-TABLE populada para preencher o grid.


Figura 13e

Por fim teremos o script do evento btoLimpar.click para limpar a tela, conforme figura 13f.




34
Versão 1.0
Manual do Metadados

Figura 13f

Exemplos de leitura dos registros do grid, uso de FOR EACH e FIND:


Figura 13g



35
Manual do Metadados



Recursos para Encontrar Problemas em Código ABLScript


 Utilize o comando DISPLAY para apresentar no console do ABLScript valores de variáveis ou strings.
Exemplos:


DISPLAY varX.
DISPLAY “Habilitando campos...”.


 Utilizar o DISPLAY DEBUG-ON para habilitar o log de execução do script no console do ABLScript e no
arquivo <USER_HOME>\.ablscript.log. Esse log apresenta além das mensagens de erro, informações
detalhadas sobre os comandos executados no script.


Figura 13h




36
Versão 1.0
Manual do Metadados


Figura 13i





O ABLScript permite a criação e utilização de Includes e Procedures, que possibilita uma forma eficiente de
reaproveitamento e organização de código.

Uma Include é um trecho de código que pode conter declarações de variáveis ou lógica e pode ser incluído
em tempo de compilação dentro de um outro script.

Considere que no exemplo a seguir, as primeiras 5 linhas de código precisam ser reutilizadas em outros
scripts.

DEFINE VARIABLE nome AS WIDGET-HANDLE.
DEFINE VARIABLE sobreNome AS WIDGET-HANDLE.
DEFINE VARIABLE nomeCompleto AS CHARACTER.
nomeCompleto = nome:SCREEN-VALUE + “ “ + sobreNome:SCREEN-VALUE.
DEFINE VARIABLE codigo AS INTEGER.
RUN VerificaNome.p (INPUT nomeCompleto, OUTPUT codigo).
IF codigo = -1 THEN DO:
MESSAGE “Pessoa não encontrada!” TITLE “Atenção”
VIEW-AS ALERT-BOX.
END.

14. Utilizando Includes e Procedures no ABLScript


37
Manual do Metadados



Podemos então definir a seguinte Include:

Include NomeCompleto:
DEFINE VARIABLE nome AS WIDGET-HANDLE.
DEFINE VARIABLE sobreNome AS WIDGET-HANDLE.
DEFINE VARIABLE nomeCompleto AS CHARACTER.
nomeCompleto = nome:SCREEN-VALUE + “ “ + sobreNome:SCREEN-VALUE.

Para utilizar uma Include em um script basta colocar uma chamada a mesma entre chaves, conforme
exemplo abaixo:

{NomeCompleto}
DEFINE VARIABLE codigo AS INTEGER.
RUN VerificaNome.p (INPUT nomeCompleto, OUTPUT codigo).
IF codigo = -1 THEN DO:
MESSAGE “Pessoa não encontrada!” TITLE “Atenção”
VIEW-AS ALERT-BOX.
END.

Uma Procedure tem uma utilizadade parecida com a de uma Include, porém uma procedure funciona
como uma função independente, que pode receber parâmetros, executar uma lógica e devolver valores.

A chamada a uma Procedure no ABLScript é semelhante a chamada de um programa Progress no servidor.
Utilizamos o comando RUN da seguinte forma:

RUN NomeProcedure (parametros...).

O exemplo de Procedure abaixo realiza o cálculo da área de uma circunferência:

PROCEDURE CalculaAreaCirculo:
DEFINE INPUT PARAMETER raio AS DECIMAL.
DEFINE OUTPUT PARAMETER area AS DECIMAL.
DEFINE VARIABLE PI AS DECIMAL INITIAL 3.1416.
Area = PI * raio * raio.
END PROCEDURE.

Obs.: No ABLScript não é necessário utilizar as declarações PROCEDURE … END PROCEDURE, como veremos mais
adiante.

Para executar a procedure anterior em um script basta fazer a seguinte chamada:

DEFINE OUTPUT PARAMETER area AS DECIMAL.

RUN CalculaAreaCirculo (INPUT 30.5, OUTPUT area).
DISPLAY area.









38
Versão 1.0
Manual do Metadados

Figura 14a


As Includes e Procedures colocadas na pasta Bibliotecas (Figura 14a) são públicas e podem ser utilizadas por
qualquer script de qualquer aplicação.

São utilizadas/chamadas da seguinte forma:

{NomeInclude}

RUN NomeProcedure (parametros...)





39
Manual do Metadados




Figura 15b


As Includes e Procedures colocadas na pasta Library de uma aplicação, são privadas e só podem ser
utilizadas por scripts daquela aplicação.

São utilizadas/chamadas da seguinte forma:

{NomeAplicacao\NomeInclude}

RUN NomeAplicacao\NomeProcedure (39arâmetros...)


No exemplo a seguir veremos um simples formulário FreeForm utilizado como conversor de temperaturas.
Veja a figura 14c, depois de digitar um valor no campo Temp C (temperatura em graus Celcius), ao sair do campo
o evento focusOut é disparado. O script desse evento chama uma procedure para realizar a conversão da
temperatura conforme mostra as imagens a seguir.




40
Versão 1.0
Manual do Metadados

Figura 14c



Figura 14d




41
Manual do Metadados




Figura 14e



Figura 14f