Manual de Padres Metadados

Sumrio
Manual de Padres Metadados .................................................................................................... 5
Propsito deste documento...................................................................................................... 5
Caractersticas ........................................................................................................................... 5
Quem deve usar? ...................................................................................................................... 5
Regras ............................................................................................................................................ 6
Usurio ...................................................................................................................................... 6
Ciclo de vida dos cdigos fonte ................................................................................................. 6
Acesso ao banco de metadados ................................................................................................ 6
Uso do importador do DDD....................................................................................................... 6
Nomenclatura................................................................................................................................ 6
Programas ................................................................................................................................. 6
Includes ..................................................................................................................................... 7
Variveis .................................................................................................................................... 7
Variveis globais .................................................................................................................... 8
Prticas de programao............................................................................................................... 9
Documentao .......................................................................................................................... 9
Estrutura do cdigo ................................................................................................................... 9
Tamanho do cdigo ................................................................................................................... 9
Qual o tamanho recomendado? ......................................................................................... 10
Uso de temp-tables ................................................................................................................. 10
Indentao .............................................................................................................................. 10
Regras de interface ..................................................................................................................... 10
Padro de interface ................................................................................................................. 10
Mensagens de tela .................................................................................................................. 10
Validaes ............................................................................................................................... 14

Parametrizao de formulrios ............................................................................................... 15

Chamadas ao servidor ............................................................................................................. 15
Processos demorados ............................................................................................................. 15
Formulrios ............................................................................................................................. 16
Filtros Rpidos ......................................................................................................................... 17
Filtro Simples ........................................................................................................................... 17
Datagrid ................................................................................................................................... 17
Advanced Datagrid .................................................................................................................. 17
Rodap .................................................................................................................................... 18
Ao Focal ............................................................................................................................... 18
Aes Neutras ......................................................................................................................... 18
Aes Relacionadas ................................................................................................................. 18
Datasul Janela.......................................................................................................................... 19
Datasul Zoom .......................................................................................................................... 19
DateField ................................................................................................................................. 19
RadioButton ............................................................................................................................ 19
FormItem (I18N) ...................................................................................................................... 19
Feedback ................................................................................................................................. 19
Tooltip ..................................................................................................................................... 19
Totalizadores ........................................................................................................................... 20
Espaamento e Ancoramento de Objetos .............................................................................. 20
Layout Constraints............................................................................................................... 20
Hierarquia e destaque de Informaes ................................................................................... 21
Quando usar ........................................................................................................................ 21
Boas Prticas ....................................................................................................................... 21
Manipulao Direta (Drag n Drop) .......................................................................................... 21
Quando usar ........................................................................................................................ 21
Estrutura .............................................................................................................................. 21

Comportamentos ................................................................................................................ 21
Boas Prticas ....................................................................................................................... 22
Menu Contextual (Boto Direito) ............................................................................................ 22
Quando usar ........................................................................................................................ 22
Estrutura .............................................................................................................................. 22
Comportamentos ................................................................................................................ 22
Atalhos de Teclado .................................................................................................................. 22
Viso Geral .......................................................................................................................... 22
Comportamentos ................................................................................................................ 22
Definio de Textos e Nomenclatura ...................................................................................... 23
Auto-preenchimento de entradas........................................................................................... 23
Quando usar ........................................................................................................................ 23
Estrutura .............................................................................................................................. 23
Comportamentos ................................................................................................................ 24
Boas Prticas ....................................................................................................................... 24
Formataes e uso de Mscaras ............................................................................................. 24
Quando usar ........................................................................................................................ 24
Comportamentos ................................................................................................................ 25
Boas Prticas ....................................................................................................................... 25
Validaes e tratamento de excees .................................................................................... 25
Quando usar ........................................................................................................................ 25
Comportamentos ................................................................................................................ 25
Boas Prticas ....................................................................................................................... 25
Resolues Suportadas ........................................................................................................... 26
Viso Geral .......................................................................................................................... 26
Comportamentos ................................................................................................................ 26
Boas Prticas ....................................................................................................................... 26
Dicas Gerais ............................................................................................................................. 26

Dicas de Performance ................................................................................................................. 15

Manual de Padres Metadados

Este documento uma extenso do Manual de Padres Programao EMS 2.0 Maro/2010
que se encontra publicado em x:\ferramentas\ddk2000\manual recomenda-se que as
prticas Progress sejam observadas e seguidas. Nesta documentao encontra-se somente a
documentao criada para atender as demandas especficas de Metadados.

Propsito deste documento

Descrever o conjunto de boas prticas que devem ser seguidas quando for escrito um cdigo
ABL Script/Tela de Metadados gerando cdigos mais fceis de entender, manter e evoluir.
Ateno: Antes de chamadas para BO/API colocar um comentrio sobre o objetivo da
chamada para simplificar a leitura.

Caractersticas
Boas prticas de mercado so seguidas sempre que possvel; prticas pr-existentes no
produto Datasul so mantidas aqui para evitar que tenhamos mais de um padro para itens
semelhantes.
O padro aqui apresentado baseia-se em prticas comprovadamente eficazes da engenharia
de software.

Quem deve usar?

Desenvolvedores envolvidos em escrever cdigo para metadados linha Datasul.

Regras
Usurio
No deve ser usado o usurio super para trabalhar com o metadados ou qualquer derivado
deste. Cada desenvolvedor deve ter seu prprio usurio; isto facilita busca de logs de
alteraes no produto e garante isolamento entre atividades.

Ciclo de vida dos cdigos fonte

O controle do estado dos objetos no seu ciclo de vida de responsabilidade dos
desenvolvedores, cabe a cada um garantir que seus objetos encontram-se no estado correto
(Desenvolvimento/Qualidade/Liberado).

Acesso ao banco de metadados

No pode ser realizado nenhum acesso ao banco metadados por fora da IDE Metadados
(houve casos de acesso direto via SQL Clients que geraram inconsistncia na base).

Uso do importador do DDD

No utilizar importador DDD para tabelas j existentes no metadados e usadas via CRUD
clssico1 (fazer isso ocasiona em eliminao das referncias e configurao da tabela
atualmente presente no MD). Essa regra somente vlida para verses antigas, uma vez que
as novas utilizam Dataset.

Nomenclatura
O objetivo deste captulo descrever as regras de nomenclatura para os objetos dentro do
Metadados.

Aplicaes
As aplicaes devem seguir um modelo padro, obedecendo regra imposta pelo sistema
operacional e aos seguintes tpicos:
1) Nunca usar acentuao no nome dos arquivos;
2) Para melhor visualizao, pode-se utilizar algumas letras em maiscula;
3) Nunca usar a palavra teste no nome de um programa sem deixar claro qual tipo de
teste est sendo realizado, por exemplo, TestedeQualidadedeProduto.

CRUDS anteriores ao modelo CRUD FREE FORM

Includes
Da mesma maneira que as aplicaes, os includes tambm podem possuir algumas letras em
maiscula, obedecendo seu propsito.
Ateno: Um bom uso de includes pode auxiliar a melhorar o tamanho e a leitura do seu
cdigo.

Variveis
O padro de nomenclatura adotado depende do que a varivel representa sempre tomando
muita ateno para jamais usar palavras reservadas da linguagem ABL ou do banco de dados
do OpenEdge. Tambm devemos considerar para no usar palavras reservadas do SQL ou dos
bancos de dados Oracle/SQL Server.
Importante: Os prefixos utilizados, no devem conter hfen -, pois todo o cdigo ABLScript
compilado para Java e quando encontrado o -, o compilador remove o mesmo. Ento, uma
varivel bt-ok, aps a compilao vira btOk (padro Java). Para o programador, esse processo
transparente, porm, caso seja debugado o cdigo vai encontrar referncias ao nome da
varivel dada pelo compilador.
Basicamente temos um dos dois casos a seguir:
a) A varivel representa um widget (componente de interface), neste caso ela deve
possuir um prefixo que identifique o widget e este prefixo seguido de um nome
significativo. Alguns prefixos so apresentados a seguir:
Widget

Prefixo

Exemplo

Boto

bt

btOk

Browse

br

brZoom

Combo-box

cb

cbTipoConta

Fill-in

fi

fiTexto

Radio-set

rs

rsModoExecucao

Retngulo

rt

rtMoldura

Selection-list

ls

lsEstados

Slider

sl

slPercentual

Chart

ch

chParticipacaoNosResultados

Tree

Tr

trCentrodeCusto

Toggle-box

tb

tbAtivo

Outro objeto de ui

uiElemento

interface
b) Quando uma varivel no for um widget o seu tipo de dado determina o prefixo que
deve ser utilizado para nome-la, conforme tabela a seguir:
Tipo de dado

Prefixo

Exemplo

Caracter

cConta

Inteiro

iContador

Data

da

daAtualizacao

Decimal

de

deTotalGeral

Handle

hAcomp

Lgico

lAtivo

Raw

raw

rawParam

Rowid

rw

rwParam

Widget-handle

wh

whBotao

Variveis globais
Toda e qualquer varivel global deve ter seu nome seguido de um sufixo que indique a
aplicao que criou a varivel evitando desta forma conflito entre aplicativos instalados.

Prticas de programao
Documentao
Use comentrios no cdigo sempre que considerar apropriado. Se voc parou para pensar
para programar vale a pena documentar, ou seja, qualquer trecho de cdigo que sua
elaborao exigiu um esforo requer ao menos uma simples explicao.

Estrutura do cdigo
Comece pelo comeo, siga at chegar ao fim e ento, pare.
Lewis Carroll em Alice no Pas das Maravilhas

Para evitar a proliferao de cdigo emaranhado transformando nossos cdigos ABLScript em

verdadeiros spaghetti codes recomenda-se estruturar o cdigo conforme a sequncia abaixo:
1. Header
Comentrio contendo o objetivo do programa
2. Variable definitions
Declarao de variveis locais e compartilhadas quando esta rea contiver muitas
variveis e tornar o cdigo muito longo recomenda-se o uso de includes
3. Other definitions (exemplo: temp-tables)
Definies das tabelas temporrias que sero usadas devem ser feitas dentro de
includes para garantir o reuso onde necessrio minimizando os esforos de cpia
(control + <c>, control + <v>)
4. Corpo do Script
5. Exit Point

Tamanho do cdigo
Um cdigo muito grande em geral indica um problema em potencial (code smell).
Normalmente este tipo de cdigo desempenha mais de uma funo e sua complexidade tende
a crescer rapidamente tornando difcil o entendimento do comportamento por parte de outros
desenvolvedores.
Recomenda-se refatorar cdigos longos criando procedures que possuem um nico objetivo e
possuem um ciclo de vida curto.
Ateno: Um cdigo ABLScript muito longo pode indicar que no metadados esto sendo
colocadas regras de negcio que deveriam ficar dentro da BO.

Qual o tamanho recomendado?

Recomenda-se que um cdigo no ultrapasse uma tela, ou seja, para ler o cdigo e entender a
funcionalidade no deve ser necessrio fazer scroll. Se a rea de declarao de varivel tomar
muito espao do cdigo ela deve ser realizada dentro de um include simplificando a leitura.
Os demais trechos do cdigo devem ser quebrados usando procedimentos (procedures) de
forma que cada procedure seja responsvel por uma nica tarefa.
Ateno: Para garantir um padro uniforme o metadados em breve bloquear procedures com
mais de 200 linhas de cdigo em um primeiro momento gerando um warning e futuramente
bloqueando a edio.

Uso de temp-tables
A quantidade de campos utilizados em uma temp-table e a quantidade de registros retornados
por uma consulta podem ocasionar problemas e risco de travar o APP Server, Flex ou at
mesmo a JVM. Para tabelas de movimento as consultas devem sempre ser feita sobre
agrupamentos de dados (sumrios) de forma a evitar um uso excessivo da memria do
servidor.

Indentao
Para melhorar legibilidade todo cdigo deve ser indentado, ou seja, statements dentro de um
bloco recomenda-se que sejam usados trs espaos para indentar.
Ateno: Se usar qualquer outro editor evite usar TAB ou o configure para trocar o caracter
especial por espaos, pois o editor do metadados trabalha com espaos.

Regras de interface
Padro de interface
Todas as telas feitas para o produto Datasul devem estar de acordo com o Guia de Estilo
TOTVS definido pelo comit de interface o documento com as regras encontra-se publicado
em http://sdk.datasul.com.br/confluence/pages/viewpage.action?pageId=27067221

Mensagens de tela
Mensagens toaster ainda no so possveis de se inserir no metadados.

Mensagens Modais: http://sdk.datasul.com.br/confluence/display/UIE/Mensagens+Modais

As mensagens modais, so parte do mecanismo de dilogo do sistema para se comunicar com
o usurio. Mensagens modais interropem a atividade corrente do usurio requerendo sua
ateno para prosseguir atravs geralmente de botes de ok ou confirmao.
Quando usar?

Quando o sistema precisa de uma confirmao do usurio;

Para alertar sobre situaes crticas, inesperadas ou erros que necessitam de ateno

Para informar que algo foi executadao e retornou erro.

Boas Prticas!

Evitar sempre que possvel mensagens modais para no interromper o usurio,

preferir toaster

Aplicar mensagens curtas, de leitura rpida

Utilizar termos comuns ao negcio, evitar termos tcnicos ou em outro idioma

Evite textos em negrito.

Templates de Mensagens

http://sdk.datasul.com.br/confluence/display/SDKV1/MessageUtil+%28UIMessage%29
A seguir so representadas todas as mensagens suportadas no metadados. Devem ser
utilizadas mensagens claras e objetivas aos usurios, evitando exageros.
possuem campos de mais informaes, relatar sucintamente as informaes.
Dica!
Nunca esquea do ttulo da janela de mensagem!

Figura 3 - Mensagem informativa

Figura 4 - Mensagem de alerta

Nos itens que

Figura 5 - Mensagem de Confirmao

Figura 6 - Mensagem de erro

Figura 7 - Mensagem com link

Figura 8 - Mensagem com informaes adicionais no estado aberto.

Figura 9 - Pergunta com opes Sim/No/Cancelar.

Validaes

As validaes de campo simples permanecem no Field Validation (VALEXP), no

dicionrio de dados, entende-se por validaes simples aquelas que dependam apenas
do dado informado do prprio campo, no fazendo referncia a outros campos da
tabela. Exemplo: item.descrio-1 <> "";

Todas as validaes, inclusive as constantes no Field Validation dos campos atualizados

na tela, devem ocorrer no momento de confirmao de gravao

No implementar qualquer validao no evento de leave dos campos;

Parametrizao de formulrios
Chamadas para os programas (.p) que retornam parametrizao do formulrio devem ser
realizadas apenas uma vez no buildComplete, pois o processo da chamada e retorno deste
lento e se executado cada vez que um parmetro for necessrio pode gerar uma percepo
negativa e desperdiar tempo e recursos computacionais.

Chamadas ao servidor
Evite realizar chamadas repetidas ao servidor para buscar um mesmo valor, crie variveis
visveis dentro do escopo do formulrio que sirvam como uma memria cache. Evite usar
variveis globais para realizar caches entre formulrios, pois isto tende a aumentar a
complexidade dos programas e a dependncia entre eles.

Processos demorados
Todo e qualquer processamento que leve mais de 15s para ser executado deve ser direcionado
para o RPW.

Dicas de Performance
Nunca crie regras de negcio ou clculos em ABLScript. Isso deve ser feito sempre nas BOs.
O ABLScript deve ser utilizado apenas para lgica de tela como:

preenchimento e leitura de valores nos campos de tela

validaes simples (exemplo: verificar se um campo foi preenchido)

controle de habilitao e visibilidade de campos

comunicao com o AppServer para envio e obteno de dados

navegao entre telas

apresentao de mensagens para o usurio

Sempre que houver a possibilidade de reutilizao de um trecho de cdigo, coloque o mesmo

em uma include ou procedure.
Evite scripts grandes, se um script tiver mais que 200 linhas, reanlise o mesmo. Se no tiver
como reduzir, coloque parte do cdigo em include ou procedure.

Variveis globais podem ser acessadas/alteradas por qualquer script de qualquer formulrio.
Portanto necessrio muito cuidado na escolha do nome da varivel, acrescente sempre o
nome da aplicao como prefixo no nome da varivel. Isso evitar que uma varivel global com
o mesmo nome seja criada em outra aplicao.
Muitas BOs retornam TEMP-TABLES com quantidades muito grande de campos e registros.
Nesses casos, utilize sempre uma fachada no lado Progress para ser chamada pelo ABLScript.
Essa fachada chamar a BO e retornar para o ABLScript uma TEMP-TABLE reduzida, contendo
apenas os campos a serem utilizados na tela. O mesmo vale para o sentido contrrio, quando o
ABLScript precisar enviar uma TEMP-TABLE que na BO existam muitos campos, mas nem todos
so preenchidos no lado do metadados, mande uma TEMP-TABLE menor para uma fachada,
que por sua vez passar para BO a TEMP-TABLE completa.
Centralize em includes a declarao de TEMP-TABLEs que sejam utilizadas em diversos scripts.

Sempre coloque comentrios nos scripts. Os comentrios devem ser curtos e fceis de
entender. Devem estar presentes em pontos chaves dos scripts, tornando fcil o
entendimento do trecho de cdigo. Por outro lado, evite comentrios de coisas muito bvias
que acabam poluindo o cdigo.
O ABLScript oferece alguns recursos para debugar o cdigo, lembre-se deles e utilize sempre
que necessrio para encontrar problemas:

DISPLAY DEBUG-ON. (coloca mensagens detalhadas sobre os comandos executados

tanto no console do ABLScript quanto no .ablscript.log)

DISPLAY FORM-VARS e DISPLAY GLOBAL-VARS (apresenta valores das variveis no

console do ABLScript)

DISPLAY WIDGETS. (apresenta lista dos IDs dos componentes de tela)

Declarao inicial (DEFINE NEW) de variveis de globais ou de formulrio, devem ser feitas
sempre em eventos que acontecem apenas uma vez no formulrio (exemplo:
creationComplete).

Evite chamar BOs que executam chamadas demoradas que possam deixar o usurio esperando
muito. Nesses casos utilize o RPW.