Manual do Metadados Linha Datasul

Parte 2
Framework


2
Verso 1.0
Manual do Metadados
Sumrio (Parte 2)
7. Criando Formulrios de CRUD ........................................................................................................................................... 2
8. Utilizando Zoom em Formulrios de CRUD ........................................................................................................................ 2
9. Criando CRUDs Pai/Filho ................................................................................................................................................... 2
10. Introduo ao ABLScript .................................................................................................................................................... 2
11. Definindo Lgica de Tela em ABLScript para Formulrios de CRUD ................................................................................... 2
12. Criando Formulrios FreeForm .......................................................................................................................................... 2
13. Utilizando ABLScript em Formulrio FreeForm .................................................................................................................. 2
14. Utilizando Includes e Procedures no ABLScript .................................................................................................................. 2



3
Manual do Metadados






Nesse captulo veremos passo a passo como criar uma nova aplicao(mdulo) e formulrios de CRUD para
pesquisa e cadastramento de entidades de negcio.

Todo formulrio deve estar associado a uma aplicao, dessa maneira devemos utilizar uma aplicao j
existente ou criar uma aplicao nova.

Para criar uma nova aplicao devemos fazer o seguinte:

Na IDE do Metadados selecione na TAB Navegador o tem Aplicaes e em seguida clique em
Manuteno de Aplicaes.

Pressione o boto Adicionar e informe os campos Nome e rea de Negcio. No utilize caracteres
acentuados e nem espao nesses campos.

Por fim pressione o boto Salvar.
As figuras a seguir mostram os passos para criao de um novo CRUD:


Figura 7a Criando Formulrios de CRUD Passo 1

7. Criando Formulrios de CRUD



4
Verso 1.0
Manual do Metadados

Figura Figura 7b Criando Formulrios de CRUD Passo 2




Figura 7c Criando Formulrios de CRUD Passo 3


5
Manual do Metadados





Figura 7d Criando Formulrios de CRUD Passo 4




Figura 7e Criando Formulrios de CRUD Passo 5



6
Verso 1.0
Manual do Metadados

Figura 7f Criando Formulrios de CRUD Passo 6




Figura 7g Criando Formulrios de CRUD Passo 7


7
Manual do Metadados




Figura 7h Criando Formulrios de CRUD Passo 8





Figura 7i Criando Formulrios de CRUD Passo 9



8
Verso 1.0
Manual do Metadados

Figura 7j Criando Formulrios 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 Formulrio de Filtro Avanado do CRUD


Ao solicitar a execuo de um formulrio de CRUD (linkbutton Executar na IDE), a Engine de Metadados
obtm os dados de cadastro do CRUD em questo, do dataset e da tabela. Com essas informaes a Engine gera o
XML de Runtime que ser utilizado pelo renderizador para criar a tela para o usurio. Os XMLs gerados para os
formulrios ficam armazenados em uma estrutura de pastas no servidor do JBoss, conforme mostra a figura a seguir:


Figura 7m



10
Verso 1.0
Manual do Metadados
Na Figura 7m, a pasta raiz chama-se MD_DES, dentro dessa pasta que so gerados os XMLs ao executar os
mesmos pela IDE. A segunda pasta indica a verso do produto que est selecionada na IDE, esse nmero representa
o fullNumber da verso. A terceira pasta que nesse exemplo est como framework, o nome do usurio que est
utlizando a IDE. Ento para cada usurio haver uma gerao de XML em pastas separadas.

Uma vez finalizado o desenvolvimento de uma aplicao ou mdulo, devemos gerar os XMLS atravs do
seguinte item de menu: Assistente > Instalar Produto. Essa operao ir gerar os XMLs na pasta raiz MD sem criar
sub-pastas por usurio. Esses XMLs sero utilizados quando um usurio solicitar a execuo de um formulrio
atravs do Menu do Produto.
Na imagem a seguir vemos um exemplo de XML gerado:


Figura 7n

Nesse captulo vimos como criar um CRUD e definir as telas de consulta, incluso e alterao. Nessas telas,
alm dos campos includos atravs do Dataset, podemos tambm acrescentar outros campos. Esses campos
adicionais podem ser de qualquer um dos tipos disponveis na paleta de componentes. Para que esses campos
adicionais tenham funcionalidades, necessrio definir cdigo ABLScript para os eventos correspondentes nesses
componentes.


11
Manual do Metadados





Em um CRUD cuja entidade(tabela) possua chaves estrangeiras, nos formulrios do incluso/alterao do
mesmo, podemos utilizar componentes do tipo Zoom para representar esse campos que so chave estrangeira.

Na Figura 8a, temos um exemplo de Zoom para a chave estrangeira Pais. Atravs desse componente
possvel informar manualmente o cdigo 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 Formulrios de CRUD



12
Verso 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 referncias entre tabelas e criar campos de zoom.


Figura 8c Cadastrando um Referncia na Tabela Editora

13
Manual do Metadados






Figura 8d Cadastrando um Referncia na Tabela Editora



Figura 8e Cadastrando um Referncia na Tabela Editora


14
Verso 1.0
Manual do Metadados
Aps cadastrar a referncia, vamos no CRUD de Editora para informar para o campo codPais a propriedade
xmlName. Isso indicar para o componente de Zoom qual o formulrio 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 no mudam e no 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
Verso 1.0
Manual do Metadados



Nesse captulo veremos os passos para criar formulrios 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 referncias nas tabelas. No nosso exemplo
iremos criar uma referncia 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 apaream nas aes relacionadas do Cadastro do PAI necessrio:

Estar cadastrado no Foundation > Menu > Manuteno de Programa Produto Datasul;

Neste programa usar o boto cadeado para liberar acesso para o grupo de usurio desejado
Papel.

No metadados deve ter uma FK de 1 x N, desta forma incluido nas aes relacionadas.

Essa tarefa ilustrada na imagens a seguir:



Figura 9c





18
Verso 1.0
Manual do Metadados


O ABLScript uma linguagem de script que permite a definio de lgicas de tela, como por exemplo:

habilitao/desabilitao de campos e botes.
validaes de contedos de campos
abertura/fechamento de formulrios
solicitao de execuo de regras de negcio no servidor
solicitao de dados ao servidor via execuo de programas Progress
entre outros.

Caractersticas Principais do ABLScript

Sintaxe do Progress (linguagem utilizada na construo das lgicas de negcio no lado servidor)
Subset de comandos/funes do Progress
Orientada a Eventos
Executa 100% no lado Cliente (browser)
Editor com syntax highlight e code complete
Suporte a mais de 100 comandos/funes
Suporte a TEMP-TABLE e FOR EACH
Suporte a Includes e Procedures


Figura 10a

A linguagem de programao nas verses 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 so associados a eventos que podem ocorrer em
formulrios ou em um de seus componentes.
Eventos de formulrio podem ser por exemplo: beforeInsert, afterInsert, beforeDelete, creationComplete,
etc.
Eventos de componentes de um formulrio podem ser: click, focusOut, change, hide, etc.

10. Introduo ao ABLScript


19
Manual do Metadados




Figura 10b

Uma vez escrito um script para um determinado evento de um formulrio, basta executar o formulrio e
fazer acontecer o evento para testar o script criado. No necessrio nenhum tipo especial de compilao ou deploy
dos scripts.

A criao e edio de scripts feita diretamente na IDE do Metadados atravs do editor de ABLScript aberto via
IDE. O editor possui alguns recursos que agilizam a criao de scripts:
code complete com ajuda aos comandos (help)
syntax highlight
diversas teclas de atalho para insero de cdigo





20
Verso 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 grficos de seu formulrio (campos, botes, etc), atravs
da declarao de variveis especficas. Atravs dessas variveis possvel ler ou definir atributos nesses
componentes ou executar funes disponveis nos mesmos.

A documentao dos comandos disponveis no ABLScript encontram-se no TDN, no endereo:

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


21
Manual do Metadados




Figura 10d




22
Verso 1.0
Manual do Metadados


Em formulrios de CRUD podemos criar scripts para dois tipos de eventos:

Eventos de Formulrio
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 Lgica de Tela em ABLScript para Formulrios de CRUD


23
Manual do Metadados




Figura 11a


Figura 11b



Veremos a seguir um exemplo simples de script de formulrio para o evento buildComplete do CRUDPais:


24
Verso 1.0
Manual do Metadados


Figura 11c

Ao executar o CRUD, aps abrir a tela com o grid, ser disparado o evento buildComplete. O script em
questo 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 formulrio, o Engine de Metadados ao gerar o XML de Runtime do
formulrio, compila o ABLScript para Java e inclui o cdigo 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 (gerao do XML de Runtime). A IDE do
Metadados solicita a Engine do Metadados (representada pelos mdulos MDGenerator e ABLScriptCompiler) que
gere o XML de runtime. A Engine obtm os registros referentes ao formulrio no banco do Metadados, incluindo os


26
Verso 1.0
Manual do Metadados
cdigos ABLScript. O MDGenerator, responsvel por gerar o XML, passa os cdigos ABLScript para serem compilados
pelo mdulo ABLScriptCompiler. O cdigo compilado em formato Java ento includo no XML.
A caixa amarela representa o tempo de execuo do formulrio. Quando acontece um evento no formulrio que
tenha um ABLScript associado, o renderizador de formulrios (representado pela caixa verde), passa o cdigo 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 formulrio.

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
Verso 1.0
Manual do Metadados



O FreeForm um tipo de formulrio utilizado pelo Metadados que no possui nenhum layout previamente
definido. Com ele possvel criar os mais variados tipos de tela. Cada tela do tipo FreeForm poder ter vrios
componentes e sub-componentes que iro possuir propriedades e eventos associados. Tanto as propriedades
quanto os eventos iro variar de acordo com o componente em questo. 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 usurio.





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


Figura 12a




12. Criando Formulrios FreeForm


29
Manual do Metadados





Figura 12b


Figura 12c



30
Verso 1.0
Manual do Metadados

Figura 12d


Figura 12e


31
Manual do Metadados



Aps finalizar a distribuio dos componentes no formulrio e setar as propriedades dos mesmos, salve e
execute o formulrio.

O prximo passo adicionar scripts para os eventos dos componentes do formulrio como veremos no
prximo captulo.





No captulo 11 vimos como criar scripts para formulrios de CRUD. Nesses formulrios existem dois tipos de
eventos: eventos de formulrio e eventos de componentes. No caso de formulrios FreeForm, existem apenas
eventos de componente. Fora isso, a criao e utilizao de ABLScript igual para os formulrios FreeForm. Nesse
captulo veremos mais uma srie de exemplos, orientaes e dicas para utilizao 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 declarao de variveis do formulrio, defina as variveis para representar os componentes de
tela (do tipo WIDGET-HANDLE). No navegador da IDE abra o formulrio e na tab de Estrutura selecione o nome do
formulrio (raiz da rvore). Clique em Cdigo, 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 declarao de variveis que ser utilizadas nos demais scrits do formulrio.

13. Utilizando ABLScript em Formulrio FreeForm



32
Verso 1.0
Manual do Metadados

Figura 13b

Importante:

No varDefinition s possvel declarar variveis, no permitido qualquer tipo de comando do
ABLScript que no seja para criar variveis.
Todas as variveis declaradas no varDefinition estaro disponveis em todos os scripts do formulrio.
Para reduzir o uso de memria, evite declarar variveis nessa rea que seja usada em apenas um ou
dois scripts. Nesses casos declare essas variveis no prprio script.

Dica: para declarar variveis 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 atravs da declarao de uma TEMP-TABLE, conforme a figura 13d.


Figura 13d


No click do boto Filtrar teremos um script que ir atravs 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
Verso 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 Cdigo ABLScript


Utilize o comando DISPLAY para apresentar no console do ABLScript valores de variveis ou strings.
Exemplos:


DISPLAY varX.
DISPLAY Habilitando campos....


Utilizar o DISPLAY DEBUG-ON para habilitar o log de execuo do script no console do ABLScript e no
arquivo <USER_HOME>\.ablscript.log. Esse log apresenta alm das mensagens de erro, informaes
detalhadas sobre os comandos executados no script.


Figura 13h




36
Verso 1.0
Manual do Metadados


Figura 13i





O ABLScript permite a criao e utilizao de Includes e Procedures, que possibilita uma forma eficiente de
reaproveitamento e organizao de cdigo.

Uma Include um trecho de cdigo que pode conter declaraes de variveis ou lgica e pode ser includo
em tempo de compilao dentro de um outro script.

Considere que no exemplo a seguir, as primeiras 5 linhas de cdigo 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 no encontrada! TITLE Ateno
VIEW-AS ALERT-BOX.
END.

14. Utilizando Includes e Procedures no ABLScript


37
Manual do Metadados



Podemos ento 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 no encontrada! TITLE Ateno
VIEW-AS ALERT-BOX.
END.

Uma Procedure tem uma utilizadade parecida com a de uma Include, porm uma procedure funciona
como uma funo independente, que pode receber parmetros, executar uma lgica 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 clculo da rea de uma circunferncia:

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 no necessrio utilizar as declaraes 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
Verso 1.0
Manual do Metadados

Figura 14a


As Includes e Procedures colocadas na pasta Bibliotecas (Figura 14a) so pblicas e podem ser utilizadas por
qualquer script de qualquer aplicao.

So 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 aplicao, so privadas e s podem ser
utilizadas por scripts daquela aplicao.

So utilizadas/chamadas da seguinte forma:

{NomeAplicacao\NomeInclude}

RUN NomeAplicacao\NomeProcedure (39armetros...)


No exemplo a seguir veremos um simples formulrio 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 converso da
temperatura conforme mostra as imagens a seguir.




40
Verso 1.0
Manual do Metadados

Figura 14c



Figura 14d




41
Manual do Metadados




Figura 14e



Figura 14f