Utilizando o sistema de reporte de Erros e Mensagens no AMADIS 1.x

Da AMADIS

Índice

Introdução

Reportar os erros e mensagens corretamente uma das partes mais importantes da interface. Um usuário final não possuí a mesma compreensão que um desenvolvedor sobre o funcionamento de um sistema. Para ele, não existe uma distinção clara entre interface e programa, ou seja, para ele a interface é todo o programa. Assim um usuário só consegue saber o que está ocorrendo dentro do sistema(estado do sistema) se o desenvolvedor proporcionar tal visibilidade por meio de elementos de interface. Um dos elementos de interface para implementar tal visibilidade são as mensagens de erro, alerta e sucesso.

Para simplificar o processo de reporte de erros, mensages de sucesso e alertas, foi implementado no AMADIS um sistema padrão, chamado de mensagens de estado. Esse sistema evita que o desenvolvedor fique criando formas de reportar os erros durante o processo de programação e ao mesmo tempo garanta uma forma padrão de comunicação visual como usuário final.

Exemplo mensagem de sucesso

Todas as mensagens são exibidas para o usuário em um local privilegiado (imagem acima), o qual tenta chamar a atenção do usuário para a condição em questão.

Para poder diferenciar situações distintas, foram criados três tipos de reportes de estado no AMADIS.

Reportes de Erro (error)
deve ser utilizado quando um erro grave aconteceu no sistema, impedindo a operação requisitado de ser completada;
Mensagem de Erro
Reportes de Sucesso (message)
deve ser utilizado quando a operação requisitada pelo usuário foi totalmente executada;
Mensagem de Sucesso
Reportes de alerta (alert)
deve ser utilizada quando a operação requisitada pelo usuário não foi completada com total sucesso devido a alguma excessão a qual não impede o prosseguimento da operação.
Mensagem de alerta


É importante utilizar cada tipo de mensagem de estado nas situações acima definidas. Isso cria uma consistência na plataforma que possibilida ao usuário, a medida que se apropria da mesma, identificar as diferentes semânticas de cada tipo de mensagem.

Como utilizar o sistema

Criar mensagens de estado é uma tarefa simples que pode ser executada por três métodos: pelo instanciação de uma classe, pela passagem de um parâmetro pela URL ou ainda por JavaScript/JScript. Toda a renderização da mensagem é executada pela classe AMMain, não existindo a nescessidade do desenvolvedor adicionar qualquer elemento de interface.

Instanciando objetos de Mensagens de Estados

Esse método é utilizado quando o desenvolvedor deseja adicionar um mensagem de estado para a página que será exibida na requisição sendo executada. Para tanto basta instanciar uma das três classes correspondentes aos tipos de mensagem de estado, como no exemplo.

<codehighlight language="php"> <?php $pag = new AMTWebfolio; $err = new AMError('Error Message','AMMain', $exception); //adds an error message $men = new AMMessage('Success Message'); //adds a success message $alert = new AMAlert('Alert Message'); //adds an alert message $echo $pag; ?> </codehighlight>


O simples fato da classe ser instanciada já garante e exibição da mensagem na próxima página que for renderizada. Não existe a nescessidade de adicionar o objeto da mensagem a página, até mesmo porque isso geraria uma mensagem de erro na medida em que nenhuma das três classes extende CMHTMLObj.

Passando Mensagens de Estados pela URL

Em muitas situação, é nescessário exibir a mensagem de estado em uma página que será renderizada em uma requisição futura. Nesses casos, é possível enviar codificado na URL um parâmetro que será interpretado por AMMain e que exibirá a mensagem correspondente. Observe o exemplo.

<codehighlight language="php"> <?php if($success) {

 header("Location:$_CMAPP[services_url]/webfolio/webfolio.php?frm_ammsg=data_changed");

} ?> </codehighlight>

Esse exemplo foi retirado do arquivo changedata.php, o qual altera dos dados de um usuário. A condição acima representada ocorre quando a operação de alteração do cadastro é um sucesso, e deseja-se retornar para o script webfolio.php exibindo uma mensagem de sucesso. Para tanto, injeta-se a variável frm_ammsg na URL, com o valor data_changed. Quando o script webfolio.php renderizar a página (utilizando AMMain) ele procurá se a variável frm_ammsg não está vazia, como no exemplo, e exibirá a mensagem de estado correspondente. Para adicionar erros e alertas deve-se utilizar as variáveis frm_amerror e frm_amalert, respectivamente.

Para evitar ter que enviar longas mensagens de erro como parâmetros da URL, o valor passado por essas variáveis não é a mensagem em sí, mas sim uma chave. O valor do parâmetro recebe um prefixo (error_ para erros, msg_ para sucesso e alert_ para alertas) e essa composição serve como um indice para o arquivo de linguagem. No exemplo anterior, foi enviada uma mengagem de sucesso com o valor data_changed. Após a composição a chave resultante será msg_data_changed, o qual está no arquivo de linguagem:

<codehighlight language="php"> msg_data_changed = "Seus dados foram alterados com sucesso." </codehighlight>

Portanto, a mensagem exibida não será data_changed mas sim Seus dados foram alterados com sucesso.. Deve-se destacar que a mensagem correspondente deve fazer parte do array $_language do script de destino.

Também é possível exibir várias mensagens de estado por meio da URL, simplesmente considerando o parâmetro como um array, como no exemplo abaixo.


<codehighlight language="php"> <? header("Location:$_CMAPP[services_url]/webfolio/webfolio.php?frm_ammsg[]=data_changed&frm_ammsg[]=picture_chaged"); ?> </codehighlight>

Passando Mensagens de Estado utilizando JavaScript

Boa parte do código do AMADIS é executado no browser cliente. Cada vez mais os requisitos de interação têm levado ao uso intensivo do Ajax e, portanto, ao uso do JavaScript e do JScript. Assim, uma das ações usualmente necessárias durante o desenvolvimento de scripts client-side é reportar erros e mensagens de estado.

Até pouco tempo o suporte do AMADIS para esse tipo de mensagens via JavaScript ainda era limitado. Ele era constituído por duas funções que posicionavam um html enviado pelo servidor na posição correta do layout. Essa abordagem foi desenvolvida para funcionar junto com funções Ajax. Quando um estado precisava ser reportado ao usuário, o servidor retornava um campo com o código HTML do box default de erro, mensagem ou alerta. O código HTML era então passado para as funções encontradas no arquivo lib.js, as quais posicionavam corretamenta as mensagens no layout.

Existiam duas funções que poderiam ser utilizadas:

AM_addMessage(html)
posiciona um código HTML na posição do layout para as mensagens de sucesso.
AM_addError(html)
posiciona um código HTML na posição do layout para as mensagens de erro.

Abaixo pode-se observar uma código JavaScript que utiliza as funções de erro.

<codehighlight language="javascript"> var AMBGroupRequestActionCallBack = {

 handleResponse: function(result) {
   AM_parseRequires(result.requires);
   if(result.success==true) {
     AM_addMessage(result.message);
     AM_hiddeDiv('request-'+result.request);
     
     GroupMembersRequestCount--;
     if(GroupMembersRequestCount==0) {
         AM_hiddeDiv('projectRequestBox');
     }
   }
   else {
     AM_addError(result.message);
   }
 },

} </codehighlight>

No código acima, o objeto de callback é utilizado para receber a resposta de uma requisição Ajax. Abaixo a função PHP que chama essa função de callback:

<codehighlight language="php"> <?php

 public function accept($codeRequest,$codeGroup,$codeUser,$text) {
   global $_CMAPP;
   $ret = array ('success'=>false,

'request'=>$codeRequest, 'message'=>, 'group'=>$codeGroup, 'blockMessage'=>);

   try {
     $group = new CMGroup;
     $group->codeGroup = $codeGroup;
     $group->load();
   } catch (CMObjException $e) {
     return "This Group does not exists";
   }
   try {
     $user = new CMUser;
     $user->codeUser = $codeUser;
     $user->load();
   } catch (CMObjException $e) {
     return "This User does not exists";
   }
   try {
     $group->acceptRequest($codeRequest,$text);
     $msg = new AMAlertBox(AMAlertBox::MESSAGE,$user->name." ".self::$_lang['msg_user_added']);
     $ret['success'] = true;
   }
   catch(CMDBException $e) {
     $msg = new AMAlertBox(AMAlertBox::ERROR,$_language['error_joining_user']);
   }
   $ret['requires'] = $msg->getRequires();
   $ret['message'] = $msg->__toString();
   return $ret;
 }

?> </codehighlight>

Essa abordagem está sendo marcada como decrepted, pois, apesar de funcional, ela está muito amarrado do uso do Ajax e do JPSpan. O desenvolvimento de funções JavaScript que não utilizem o Ajax não possuem uma forma padrão de reportar mensagens de erro para o usuário, o que gerou os mais diversos usos possíveis da função alert. Além disso, ela não da suporte para o reporte de estado de alerta.

Sua descrição neste documento deve-se ao fato de ainda encontrar-se muito código no AMADIS que se vale desta técnica. A seguir descrevemos uma nova abordagem para o tratamento de error.

Nova abordagem para reportar Mensagens de Estado utilizando JavaScript

Sobre o texto das mensagens

Uma das mais importantes considerações sobre as mensagens de estado é sobre o texto nelas contido. Mesmo o texto do AMADIS sofrer uma revisão antes de uma versão estável ser lançada, é importante que o desenvolvedor crie textos que possuam algumas características:

  • As mensagens de erro devem ser escritas com uma linguagem clara (sem utilizar códigos), indicando precisamente o problema ou situação e sugerindo construtivamente uma solução. Caso seja nescessário registrar a situação de erro claramente para fins de debug, deve-se utilizar o sistema de log e não a interface com o usuário;
  • As mensagens devem proporcionar ao usuário uma compreensão sobre o que aconteceu (ou está acontecendo no sistema), proporcionando que ele reconheça o problema, faça um diagnóstico e corrija sua ação(quando possível);
  • Os usuários não devem ter que ficar adivinhando quando palavras, situações ou ações significam a mesma coisa. Siga as convenções do AMADIS. Caso a parte do sistema que você está codificando não exista, envie uma mensagem para a lista correspondente lançando uma discussão sobre o melhor termo a ser utilizado;
  • É muito importante que exista um cuidado com a ortografia das mensagens no AMADIS, principalmente considerando os objetivos da plataforma. Utilize ferramentas de correção ortogŕafica para evitar o tipo de erros simples que podem ser evitados;

Referências

Ferramentas pessoais
Parceiros
















SourceForge.net Logo

Supported by Cenqua