Utilização

O serviço pode ser utilizado injetando o serviço de notificação no AngularJS Controller ou Service e/ou através do disparo de eventos através do $rootScope ou $scope.

Injeção

No caso da injeção é preciso injetar o serviço propriamente dito ao AngularJS Controller ou Service:

sampleController.$inject = ['$rootScope', '$scope', 'totvs.app-notification.Service'];
function sampleController($rootScope, $scope, appNotificationService) {

	// Exemplo de chamada direta ao sistema de notificação:
	appNotificationService.message({
    	title: 'l-attention',
        text: 'Vamos lhe fazer uma pergunta.',
        help: 'Se precisar de ajuda, chame os universitários.',
        size: 'lg',  //opicional
        callback: function() {
        	appNotificationService.question({
            	title: 'l-question',
                text: 'Hoje é sexta-feira?',
                cancelLabel: 'l-no', // Padrão é 'cancel'
                confirmLabel: 'l-yes', // Padrão é 'ok'
                callback: function(isPositiveResult) {
                	var alert = {
                    	type: 'error',
                        title: 'Atenção',
				        size: 'md',  //opicional
                        detail: 'Hoje não é sexta-feira :('
                    };
                    if (isPositiveResult) {
                    	alert.type = 'success';
                        alert.detail = 'Hoje é sexta-feira :)'
                    } 
                    appNotificationService.notify(alert);
				}
			});
		}
	});
}

Evento

O disparo das mensagens também pode ocorrer através de eventos, desde que estes tenham registrados listeners no controller principal da aplicação centralizadora. O nome dos eventos fica a critério do produto ou aplicação, neste exemplo definimos os eventos no arquivo events.js para facilitar a utilização no produto, tendo disponíveis:

• TOTVSEvent.showMessage: corresponde a mensagem ('event:scope-message.app.service');
  
  
• TOTVSEvent.showQuestion: corresponde a questionamento ('event:scope-question.app.service');
  
  
• TOTVSEvent.showNotification: corresponde a notificação ('event:scope-notify.app.service').
  
  

sampleController.$inject = ['$rootScope', '$scope'];
function sampleController($rootScope, $scope) {
	// Exemplo de chamada por evento ao sistema de notificação:
	$rootScope.$broadcast(TOTVSEvent.showNotification, {
    	type: 'info',
        title: 'Evento',
        detail: 'Esta notificação foi disparada através de um evento.'
	});
}

Definição

Cada produto é livre para definir a forma como irá gerenciar suas notificações.

Utilizando como base a implementação da aplicação de referencia temos a seguinte estrutura para o sistema de notificação:

• uma tela modal para apresentação das mensagens e questionamentos;
  
  
• um AngularJS Controller para gerenciamento da modal;
  
  
• uma biblioteca para apresentação de notificações. No caso foi utilizado o JQuery Toastr;
  
  
• um AngularJS Service para gerenciamento das notificações pela aplicação.
  
  

A modal foi definida através de um template html básico (html-app/html/templates/message.html) no qual se auto gerencia para quando for apresentar uma mensagem ou questionamento ao usuário. Como toda view a modal também necessita de um AngularJS Controller, este foi definido no arquivo service-notify.js onde também se encontra definido o AngularJS Service.

O serviço de notificação, na aplicação de referência, está resumido a 3 funcionalidades:

Notificação

A notificação utiliza uma biblioteca externa (JQuery Toastr) para apresentação das mensagens ao usuário. O foco desta função é disparar notificações ao usuário sem que este perca o foco ou trave suas atividades no momento; sendo apresentado um toaster ao usuário, este toaster por padrão será disposto no canto superior direito do monitor.

Para utilização da biblioteca JQuery Toastr será preciso adicionar a biblioteca como uma dependência para a aplicação angular (como pode ser verificado no index.js) e adicionar uma tag ao index.html para que o componente possa se gerenciar e apresentar as notificações sobre as demais views.

<html>
	<head>Exemplo</head>
	<body>
		<!--
        Diretiva definida para utilização do sistema de notificação via toaster.
        Caso não seja necessária a utilização basta remover a tag abaixo.
	    -->
	    <toaster-container toaster-options="{'time-out': 5000}"></toaster-container>
	</body>
</html>

Para exibição do toaster ao usuário pode ser passado um objeto alert ou uma lista de alerts para exibição de várias notificações, desde que o objeto alert obedeça a seguinte estrutura:

• type: indica o tipo de alerta a ser apresentado, tendo como opções:
  
  
  • error: na cor vermelha;
  • info: na cor azul claro;
  • success: na cor verde;
  • warning: na cor laranja;
    
    
• title: titulo da notificação;
  
  
• detail: mensagem ou detalhamento da notificação;
  
  
• timeout: (opcional) tempo que ficará disponível em tela até desaparecer.

Mensagem

Apresenta ao usuário uma mensagem focal, a qual obrigará o usuário a tomar alguma ação para prosseguir com a operação. Diferente da notificação esta função permite a disposição de apenas uma mensagem por vez. Sendo que o objeto message deve obedecer a seguinte estrutura:

• title: (opcional) titulo da mensagem, quando não informado assume o código 'l-internal-error'. Sendo que o title deve será traduzido pelo sistema de internacionalização;
  
  
• text: breve descrição da mensagem. Este já deve ser encaminhado traduzido para o serviço;
  
  
• help: detalhamento e/ou ajuda referente a mensagem. Já deve ser encaminhado traduzido para o serviço;
  
  
• size: (opcional) define o tamanho da caixa de mensagem exibida, caso não seja informado assume o tamanho 'lg' (grande). Os valores permitidos:  lg (grande), md (médio) e sm (pequeno).
  
  
• callback: (opcional) função a ser chamada ao fechar a mensagem de notificação.
  
  
  • ao ser chamada a função de callback, não é passado nenhum parâmetro para a mesma.

Observação: Como o template de mensagem e questionamento é o mesmo é preciso definir um AngularJS Controller em runtime para utilização da modal para apresentação da mensagem.

Questionamento

Questiona o usuário referente ao conteúdo da mensagem. As respostas devem ser de forma objetiva na qual o usuário responda sim ou não. Assim como a mensagem esta função permite a disposição de apenas uma questão por vez e é preciso que o objeto question obedeça a seguinte estrutura:

• title: titulo;
  
  
• text: descrição da pergunta;
  
  
• confirmLabel: (opcional) label para o botão de confirmação (padrão 'l-ok');
  
  
• cancelLabel: (opcional) label para o botão de cancelamento (padrão 'l-cancel');
  
  
• size: (opcional) define o tamanho da caixa de mensagem exibida, caso não seja informado assume o tamanho 'lg' (grande). Os valores permitidos:  lg (grande), md (médio) e sm (pequeno).
  
  
• callback: (opcional) função a ser chamada ao responder a questão.
  
  
  • ao chamar a função de callback será passado para a função um parametro para indicar se o resultado do questionamento foi positivo (true) ou negativo (false).
    
    

Observação: Como o template de mensagem e questionamento é o mesmo é preciso definir um AngularJS Controller em runtime para utilização da modal para apresentação da mensagem.

Notificações por Eventos

Para facilitar o acesso ao serviço de notificações pode ser adicionado listeners no AngularJS Controller principal da aplicação centralizadora para que eles se encarreguem de realizar a chamada ao serviço de notificação. Utilizando a aplicação de referencia como base, temos:

// Controller principal para resolução das interações da aplicação que não 
// dizem respeito ao programa aberto (content). 
// Em resumo, é responsável pela barra de navegação e 'menus', entre outros.
appMainController.$inject = ['$rootScope', '$scope', 'totvs.app-notification.Service'];
function appMainController($rootScope, $scope, appNotificationService) {

	...

	// appNotificationService
	// Para evitar que todos os demais AngularJS Controllers e Services precisem
    // injetar o serviço de notificação, o serviço pode ficar disponível através
    // de eventos. Para isto basta injetar o appNotificationService no 
    // appMainController para dar suporte as notificações.
    $scope.$on(TOTVSEvent.showNotification, function (event, alerts) {
    	appNotificationService.notify(alerts);
	});
        
    $scope.$on(TOTVSEvent.showMessage, function (event, message) {
        appNotificationService.message(message);
    });
        
    $scope.$on(TOTVSEvent.showQuestion, function (event, question) {
        appNotificationService.question(question);
    }); 
}