Camada de Visualização

Conforme citado na seção de contextualização, a arquitetura proposta visa eliminar os problemas identificados em diversos projetos já executados, onde foi possível identificar a falta de padronização para realizar tarefas comuns no processo de desenvolvimento. Assim, temos como objetivo principal desta seção o detalhamento do projeto Commons UI que provê soluções para que seja possível estabilizar, o que era previamente uma atividade caótica, em uma atividade produtiva e padronizada. Em busca deste equilíbrio, foram estudadas soluções e padrões de mercado que balizam o desenvolvimento de software atualmente.

O framework AngularJS foi a opção escolhida após compararmos as soluções disponíveis. A possibilidade de extensão do framework nos proporciona a flexibilidade necessária para criar componentes personalizáveis que atendem plenamente as nossas necessidades. Além do benefício da extensibilidade, o framework possui uma documentação detalhada, comunidade participativa e componentes genéricos já desenvolvidos e inclusos na solução. Para maiores detalhes, consulte o guia para desenvolvedores do AngularJS.

Tomando como base os motivos citados acima, criamos o projeto commons-ui. Este projeto compõe a camada de apresentação. Ao iniciar um projeto é possível ter o commons-ui como dependência para ter acesso a suas funcionlidades e compartilhar a padronização através de componentes como: directives, services, providers, factories, controllers, scopes, partials, etc.

Esta seção será dividida em três grandes tópicos: estrutura, detalhamento da estrutura e melhorias futuras. O primeiro tópico aborda a organização do projeto e responsabilidade de cada componente, descrevendo breviamente o comportamento dos componentes que compõem a estrutura do projeto. O tópico de detalhamento mostra detalhadamente o funcionamento dos componentes, a comunicação entre diferentes componentes e sua utilização pelo desenvolvedor. E por fim, o tópico de melhorias, no qual irá listar diversas melhorias que podem ser realizadas pela equipe de arquitetura para facilitar na construção de novos componentes e manter a atual estrutura da arquitetura estável.

O diagrama abaixo ilustra, de forma macro, a comunicação e organização dos componentes na atual versão da arquitetura.

Recipients

Recipients é um termo utilizado na documentação do framework AngularJS para referir-se a um agrupador contendo os componentes: service, factory e provider. Os componentes deste agrupador são abordado no decorrer desta seção.

O que é um Service? 

São objetos que compartilham funcionalidades através de APIs públicas para toda aplicação que faz uso do AngularJS. Services fornecem injeção de dependência e padronização quanto a criação de APIs públicas. 

Services são registrados a partir da Module API. Ao registrar um service, dá-se um nome no qual será utilizado para injeção de dependências em quaisquers outros componentes do AngularJS. Abaixo temos um exemplo da utização de services para manter estados de um dialog.

// aqui o service com nome DateUtil (primeiro parâmetro na chamada da função service()) é registrado no módulo treelayer.commons.ui.util
angular.module('treelayer.commons.ui.util').service( 'DateUtil', function() {
	
	this.format = function( date ) {
		new Date(date).format('dd-mm-yyyy');
	};	
});
 
// em um modulo que depende do commons (shieldApp no caso da aplicação Shield) o componente DateUtil é injetado
// em um controller através do array de string (segundo argumento da função controller()) onde este argumento
// deve conter o nome que o componente foi registrado, ou seja, 'DateUtil'
shieldApp.controller( 'PeriodController', [ 'DateUtil', '$scope', function( DateUtil, scope ) {
	
	// ...

	// metodo chamado para formatar a data escolhida em um widget calendar
	scope.formatCurrentDate = function(date) {
		scope.formattedDate = DateUtil.format(date); // utilização do service DateUtil
	};
	
}]);

Note a forma que declaramos a função format no service acima. Internamente, ao declarar um service, a função retornada será instanciada apenas quando necessário (lazy). Esta instanciação dá-se chamando construtor da função através do operador new. Services são estruturas simples, expoem métodos declarados no contexto (variável implícita this) e serão instanciados pelo AngularJS a partir de um construtor padrão. São utilizados quando não há necessidade de manter estado nos objetos e/ou criar objetos que necessitam de parâmetros para sua instanciação. 

O que é um Factory? 

Assim como o service, factories também são objetos que compartilham interfaces públicas de API e são passíveis a injeção de dependências.

Factories são registradas através da Module API . Ao registrar uma factory, dá-se um nome no qual será utilizado para injeção de dependências em quaisquers outros componentes do AngularJS. Abaixo temos um exemplo de como registrar uma factory e como utiliza-la através da injeção de dependências.

// aqui a factory com nome $dialog(primeiro parâmetro na chamada da função service()) é registrada no módulo treelayer.commons.ui
angular.module('treelayer.commons.ui').factory('$dialog', function() {

    var Dialog = function(isOpen, operation) {
        this.isOpen = isOpen ? isOpen : false;
        this.operation = operation ? operation : '';
    };

    Dialog.prototype.close = function() {
        this.isOpen = false;
        this.operation = '';
    };

    Dialog.prototype.open = function(op) {
        this.isOpen = true;
        if (op) this.operation = op;
    };

    return {
      'new': function(isOpen, operation) {
		return new Dialog(isOpen, operation);
      }
    };
});


// em um modulo que depende do commons (shieldModule no caso da aplicação Shield) o componente $dialog é injetado
// em um controller através do array de string (segundo argumento da função controller()) onde este argumento
// deve conter o nome que o componente foi registrado, ou seja, '$dialog'
shieldApp.controller( 'PeriodCtrl', ['$dialog', '$scope', function ( Dialog, scope ) {
	
	// ...
	$scope.view = {
		detailDialog: Dialog.new() // utilização da factory $dialog
	};
 
	// ...
	
}]);

Note a forma que declaramos a função foo na factory acima. Internamente, ao declarar uma factory, a função foo já esta instanciada e apenas será executada, diferentemente do service onde uma nova função será instanciada através do operador new. A factory $dialog oferece um método público new que constroi uma nova instância do objeto Dialog. Factories fornecem mais flexibilidade na sua instanciação, possibilitando a construção de objetos que possuam parametro, por isso, em casos como mostrado no exemplo acima são preferíveis ao invés de services.

O que é um Provider? 

Providers, assim como services e factories provem interfaces públicas e são passíveis de dependência. Diferentemente destes outros componentes, providers são expostos antes da inicialização da aplicação. Este atributo fornece aos providers um mecanismo de configuração, tornando-os uteis onde o comportamento de seus métodos públicos diferem conforme a configuração realizada em um bloco de inicialização do AngularJS. 

São registrados através da Module API . Ao registrar um provider, dá-se um nome (primeiro parâmetro na chamada de função angular.module('treelayer.commons.ui').provider) no qual será utilizado para injeção de dependências em qualquer outro componente do AngularJS. Abaixo temos um exemplo de como registrar um provider e como utiliza-lo através da injeção de dependências.

angular.module('treelayer.commons.ui').provider('$message', function () {

	// ...
	this.baseUrl = '';
 
	// ...
 
	this.$get = ['$q', '$http', function ($q, $http) {
        return this.$message($q, $http);
    }];
 
	// ...
});

Todo provider deve possuir um método $get. Este será invocado pelo AngularJS para instanciar o provider e deixa-lo disponível para o bloco de configuração da aplicação. Internamente, services e factories são instancias de providers, onde o método $get é injetado automaticamente pelo framework para facilitar o desenvolvimento.

A injeção de dependências de providers mudam conforme a localidade que estão sendo injetados. Como podemos perceber no bloco de código acima, o provider de exemplo foi registrado com o nome fooProvider. Para injetarmos providers em controllers, retira-se o prefixo provider, restando apenas $message, como pode ser visto no bloco de configuração da aplicação Shield. Em blocos de configuração, mantem-se o prefixo como no bloco de exemplo abaixo.

shieldApp.config(['$messageProvider',
                  '$routeProvider',
                  'partialsPath',
                  function ($messageProvider, $routeProvider, partialsPath) {

	// ...

    $messageProvider.baseUrl = AJS.contextPath() + '/rest/shield/latest';

	// ...

}]);

O que é uma Directive?

Diretivas são marcadores (podem ser atributos, classes ou novos elementos) em nodos da árvore DOM, como uma extensão da especificação construída pela W3C. Em sua inicialização, o framework AngularJS percorre a árvore HTML, compila e executa as directives declaradas. Durante sua execução directives são capazes de anexar novos comportamentos e funcionalidades que não existiam, até então, na estrutura especificada pela W3C.

O framework AngularJS disponibiliza, por padrão, um conjunto de directives.Assim como você pode criar controllers e services, directives também podem ser customizadas. A partir desta extensibilidade foram criadas directives que atendem as necessidades de padronização, como por exemplo a directive tl-key.

Abaixo temos um exemplo da utilização da directive tl-key e ng-click que ilustra como utilizar a directive customizada e uma directive empacotada com o AngularJS.

<!-- ... -->
 
<div class="inline-field-container" tl-ref="common">
	<button class="aui-button align-right" ng-click="view.detailDialog.open('create')" tl-key="button.add"></button>
</div>
 
<!-- ... -->

 shieldApp.controller( 'PeriodCtrl', ['$scope', '$http', '$property', '$resourceLocator', '$dialog', function ( $scope, $http, $property, $resourceLocator, $dialog ) {
	
	// ...
 
	$scope.view = {
		
		// ...

		detailDialog: $dialog.new()

		// ...

	};
 
	// ...
	
}]);

No primeiro blocos acima temos o exemlo do uso da directive tl-key e ng-click; um partial, de onde retiramos um fragmento do HTML. A directive tl-key, insere os labels de forma internacionalizada a partir de uma chave. A directive ng-click, invoca o método open do objeto view.detailDialog contigo no controller PeriodCtrl.

Nestes exemplos podemos ver como é dada a interação entre controllers, scopes, partials e directives, onde o conjunto destes itens implica em uma interface dinâmica para o usuário final, agregando qualidade e padronização no processo de desenvolvimento.

O que é um Partial?

Partials são páginas HTML que podem ser incorporadas em outras páginas através da directive ng-include. Todas as páginas de listagem e detalhe da arquitetura são partials que compoem a estrutura HTML da aplicação.

Abaixo temos um exemplo que da utilização da directive ng-include para incorporar o dialog de detalhe na página de períodos da aplicação Shield.

 <!-- ... -->
 
	<div ng-include="view.detailDialogUrl.url" />
 
 <!-- ... -->

<div tl-object="period" tl-context="detail" tl-dialog tl-opened="$parent.view.detailDialog.isOpen">
 
 <!-- ... -->
 
 <!-- ... -->
 
</div>

O que é um Controller?

De acordo com a Wikipedia, um controller pode enviar comandos para sua visão associada para alterar a apresentação da visão do modelo (por exemplo, percorrendo um documento). Ele também pode enviar comandos para o modelo para atualizar o estado do modelo (por exemplo, editando um documento). 

Adaptando a citação para o contexto do AngularJS, o controller interage com directives (presentes em elementos HTML nos partials) através do escopo, podendo modificar o comportamento na apresentação de conteúdos ou regras para o usuário final.

O exemplo abaixo mostra como o controller PeriodCtrl preenche uma combo-box na partial period-list.html através da directive ng-option.

<!-- ... -->
 
<select class="select field-short" ng-model="model.enabled" tl-key="enabled" ng-options="key.bool() as value for (key, value) in view.status">
	<option value=""></option>
</select>
 
<!-- ... -->

shieldApp.controller( 'PeriodCtrl', ['$scope', '$http', '$property', '$resourceLocator', '$dialog', function ( $scope, $http, $property, $resourceLocator, $dialog ) {
 
	// ...
 
		$scope.view = {
 
			// ...

            status: $property.range({object: 'period', attribute: 'enabled'}),
 
			// ...
 
		};
 
	// ...
 
}]);

O que é um Scope?

É um link entre partials e controllers, onde tudo que declaramos em scopes é exposto para ser utilizado em partials, por directives. Contudo, scopes possuem outras funcionalidades, como por exemplo a função $watch que fornece ao desenvolvedor uma forma de observer valores contidos no scope e realizar ações conforme a interação do usuário com a UI.

Exemplo de código onde uma variável declarada em um escopo do controller PeriodCtrl é exposta para a directive ng-options.

<!-- ... -->
 
<select class="select field-short" ng-model="model.enabled" tl-key="enabled" ng-options="key.bool() as value for (key, value) in view.status">
	<option value=""></option>
</select>
 
<!-- ... -->

shieldApp.controller( 'PeriodCtrl', ['$scope', '$http', '$property', '$resourceLocator', '$dialog', function ( $scope, $http, $property, $resourceLocator, $dialog ) {
 
	// ...
 
		$scope.view = {
 
			// ...

            status: $property.range({object: 'period', attribute: 'enabled'}),
 
			// ...
 
		};
 
	// ...
 
}]);

No exemplo acima, acessamos o scope do controller PeriodCtrl através de injeção de dependencias no construtor do controller (variável declarada como $scope). Valores são expostos para partials e directives através do operator . (dot). No exemplo, um objeto de nome view é criado no scope, e internamente este objeto possui um atributo status. A partir daí, a partial pode referenciar o objeto status através da atributo view do scope; como vemos na delcaração view.status.

Estrutura do Projeto Commons UI

Conforme a imagem abaixo, o projeto é estruturado por pastas, cada qual refletindo a responsabilidade de seus componentes. Como este projeto é inteiramente composto de arquivos Javascript, não existem dependencias de outros projetos.

Além das pastas que agrupam os componentes por responsabilidade, o projeto possui o arquivo treelayer-bootstrap que provê um módulo onde estão listadas todas as dependencias. Este arquivo existe para que quando necessário, projetos especifiquem como dependência apenas este módulo e todos os componentes estarão automaticamente associados ao projeto.

Providers Disponibilizados pela Arquitetura

Providers são objetos expostos para toda a aplicação, passíveis de injeção, oferecem funções públicas e podem ser utilizados dentro de um bloco de configuração do AngularJS. Para maiores informações leia a documentação oficial sobre providers.

Message Provider 

É o componente responsável por disponibilizar mensagens, descrições e validações e controlar o fluxo de execução das diretivas que fazem uso destes itens. Este componente é apoiado por endpoints RESTful que fornecem estas informações de forma dinâmica. Para realizar estas chamadas, em um bloco de configuração do AngularJS é possível configurar as diferentes URLs através de injeção de dependências. Abaixo temos uma imagem do projeto Shield, onde é configurado as URLs utilizadas pelo MessageProvider.

As funções disponíveis publicamente são:

Nome	Descrição	Utilização
whenMessageLoads	Fornece uma forma de se registrar a este provider e, quando o back-end retornar, o provider irá alertar os componentes registrados.
getRawMessages	Retorna um objeto contendo todas as mensagens, validações e descrições. Este objeto não sofreu nenhuma modificação por directives, esta no formato raw.
getValidations	Retorna um objeto contendo todas as validações.
createReference	Usado principalmente pela directive tl-ref, na qual cria o cache de referências. Este método é público mas não deve ser utilizado, foi criado para estabelecer a comunicação entre a directive e o cache de referências.
findMessagesByKey	Busca uma determinada mensagem pela chave contida no arquivo property.

Busca de Mensagens

A partir de uma chamada da principal directive, tl-object, é disparada uma requisitção HTTP para um método genérico da arquitetura para buscar mensagens internacionalizadas. Esta funcionalidade baseia-se no nome do objeto passado para a directive tl-object para buscar as mensagens. Mensagens são compostas de labels, descriptions, validations, etc.

As URLs previamente configuradas ao inicializar um aplicação AngularJS servem como endpoint para esta funcionalidade.

Armazenamento de Mensagens

Após a resposta do servidor, se ocorrida com sucesso, todas as mensagens são armazenadas em cache no formato raw, ou seja, sem alteração nenhuma. Assim que possível outras diretivas irão processar estas mensagens e preencher outras áreas de cache deste provider.

Controle de Fluxo

Logo após a busca de mensagens e a resposta do servidor, todas as diretivas que se registraram neste provider serão avisadas que há mensagens não processadas. A directive tl-ref iniciará sua execução preenchendo o cache referenceMessages a com uma nova estrutura, oriunda do cache no formato raw. Este cache é disponibilizado para outras diferitvas através da função pública exposta findMessagesByKey.

Services Disponibilizados pela Arquitetura

Services são objetos compostos por funções, passíveis de injeção de dependências e inicializados . Um serviço no framework AngularJS é tratado como um singleton e pode ser injetado através de seu nome, bastando declara-lo como parametro em seus componentes (no caso, um controller, por exemplo). Para maiores informações acesse a documentação oficial sobre services.

Dialog Service 

É um serviço declarado através do framework AngularJS que possui unicamente a funcionalidade de retornar um objeto que controla estados de um dialog. Mencionamos na introdução de services que estes não possuem estado, porém o que citamos na anteriormente foi que o Dialog Service tem como unica funcionalidade retornar um objeto com estados. Como isto se dá? Basicamente este serviço possui uma única função, a função responsável por criar o objeto dialog, ou seja, o Dialog Service não possui estado, mas sim objeto obtido no retorno desta chamada.

As funções disponíveis publicamente são:

 new

Dialog  

Dialog é um objeto definido internamente no service DialogService e tem como responsabilidade controlar os estados de um dialog. O estado é basicamente quando o dialog está aberto e a operação que esta ocorrendo no momento. Para obter um objeto do tipo Dialog basta realizarmos uma chamada para a função new no DialogService.

Os atributos disponíveis publicamente são:

Nome	Descrição	Utilização
operation	Define se o dialog quando exibido esta no modo de leitura ou edição.
isOpen	Variável de controle utilizada para determinar se o Dialog está visível.

As funções disponíveis publicamente são:

Nome	Descrição	Utilização
new	Inicializa um objeto do tipo Dialog e retorna.
open	Altera o valor da atributo isOpen para false. Esta faz com que o dialog seja exibido para o usuário. No exemplo de utilização ao lado é possível notar que podemos passar um valor do tipo String. Este valor é a operação executada no dialog, quando aberto. Os valores aceitos são: create, update, delete e view.
close	Altera o valor da atributo isOpen para false. Esta torna o dialog (se visível) oculto para o usuário.

Property Service

É um serviço declarado através do framework AngularJS que expõe funções públicas para trabalhar com propriedades, encapsulando a complexidade de realizar requisições HTTP para o desenvolvedor. Para maiores informações, leia a documentação de resources.

As funções disponíveis publicamente são:

Nome	Descrição	Utilização
properties	A partir do nome de objeto, busca todas as propriedades deste objeto no back-end.
range	A partir de um objeto e um atributo, busca a série se existente no arquivo de internacionalização.

Submit Service

Que expõe funções que mapeiam os métodos genéricos CRUD da arquitetura back-end. Internamente as requisições HTTP são tratadas e processadas, tornando-se transparente para o desenvolvedor.

As funções disponíveis publicamente são:

Nome	Descrição	Utilização
create	Realiza uma chamada HTTP POST para a URL configurada no MessageProvider durante a inicialização da aplicação. Esta configuração mapeia a URL base dos endpoints RESTful genéricos que implementam as operações CRUD. O objeto enviado como primeiro argumento deve conter o atributo object com valor do tipo String, contendo o nome da entidade que será persistida. O segundo parâmetro é o objeto JSON com os dados a serem persistidos. O terceiro é quarto parametro são callbacks opcionais, de sucesso e falha. Após sua execução, este método delega ao back-end a responsabilidade de inserção e recebe como resposta, no caso de sucesso, um objeto contendo o id do objeto gerado pelo back-end ou, caso de falha, os erros gerados pelo back-end na inserção.
update	Realiza uma chamada HTTP PUT para a URL configurada no MessageProvider durante a inicialização da aplicação. Esta configuração mapeia a URL base dos endpoints RESTful genéricos que implementam as operações CRUD. O objeto enviado como primeiro argumento deve conter o atributo object com valor do tipo String, contendo o nome da entidade que será atualizada e um atributo id com o identificador unico da entidade já persistida no banco de dados. O segundo parâmetro é o objeto JSON com os dados a serem atualizados. O terceiro é quarto parametro são callbacks opcionais, de sucesso e falha. Após sua execução, este método delega ao back-end a responsabilidade de atualização de um objeto já persistido. Se a operação ocorrer com sucesso e houver um callback registrado, este é executado e não recebe nenhum parametro . Em caso de falha, se houver callback de falha registrado, é executado e recebe os erros gerados pelo back-end.
delete	Realiza uma chamada HTTP DELETE para a URL configurada no MessageProvider durante a inicialização da aplicação. Esta configuração mapeia a URL base dos endpoints RESTful genéricos que implementam as operações CRUD. O objeto enviado como primeiro argumento deve conter o atributo object com valor do tipo String, contendo o nome da entidade que será excluida e um atributo id com o identificador unico da entidade já persistida no banco de dados. O segundo é terceiro parametro são callbacks opcionais, de sucesso e falha. Após sua execução, este método delega ao back-end a responsabilidade de deleção de um objeto já persistido. Se a operação ocorrer com sucesso e houver um callback registrado, este é executado e não recebe nenhum parametro . Em caso de falha, se houver callback de falha registrado, é executado e recebe os erros gerados pelo back-end.
retrieve	Realiza uma chamada HTTP GET para a URL configurada no MessageProvider durante a inicialização da aplicação. Esta configuração mapeia a URL base dos endpoints RESTful genéricos que implementam as operações CRUD. O objeto enviado como primeiro argumento deve conter o atributo object com valor do tipo String, contendo o nome da entidade que será persistida. O segundo parâmetro é o objeto JSON com os dados a serem persistidos. O terceiro é quarto parametro são callbacks opcionais, de sucesso e falha. Após sua execução, este método delega ao back-end a responsabilidade de busca de um objeto já persistido. Se a operação ocorrer com sucesso e houver um callback registrado, este é executado e recebe o objeto encontrado ou nulo, caso não foi possível encontrar um objeto através do identificador informado. Em caso de falha, se houver callback de falha registrado, é executado e recebe os erros gerados pelo back-end.
find	Realiza uma chamada HTTP GET para a URL configurada no MessageProvider durante a inicialização da aplicação. Esta configuração mapeia a URL base dos endpoints RESTful genéricos que implementam as operações CRUD. O objeto enviado como primeiro argumento deve conter o atributo object com valor do tipo String, contendo o nome da entidade que será persistida. O segundo parâmetro é o objeto JSON com os dados a serem persistidos. O terceiro é quarto parametro são callbacks opcionais, de sucesso e falha. Após sua execução, este método delega ao back-end a responsabilidade de deleção de um objeto já persistido. Se a operação ocorrer com sucesso e houver um callback registrado, este é executado e recebe um array de objetos encontrados, ou um array vazio, caso não foi possível encontrar objetos persistidos. Em caso de falha, se houver callback de falha registrado, é executado e recebe os erros gerados pelo back-end.

Todos os métodos executados retornam um $promise. Promises são promessas de execução, em algum momento no futuro, da operação desejada (ex.: execução de uma chamada HTTP PUT). Algumas directives conseguem trabalhar com promises e com isso eliminamos a necessidade de callbacks. Para maiores informações, consulte a especificação Promises/A+.

Directives Disponibilizadas pela Arquitetura

O framework AngularJS já possui um conjunto de directives implementadas e disponíveis para construir a camada de apresentação. Contudo, requisitos como: internacionalização, estruturação, padronização, temas, reuso, não foram totalmente satisfeitos com as directives já implementadas. Entretanto, foi possível criar directives customizadas que atendem estes requisitos, graças a extensibilidade do framework. Nesta seção mostraremos as directives disponíveis na arquitetura, como utiliza-las em partials e quais são suas funcionalidades.

TL Object

A directive tl-object é uma das mais importantes directives criadas na arquitetura. Tem como responsabilidade indicar em qual objeto estamos trabalhando em uma determinada UI e em qual contexto que estamos trabalhando, listagem ou detalhe, além de inicializar a busca de mensagens para a internacionalização.  Através de herança, outras directives utilizam-se destas duas característica para implementar suas funcionalidades e manipular a UI conforme necessário. 

Listagem de atributos disponibilizados pela directive tl-object:

Além das funcionalidades e comportamentos acima, a directive tl-object possibilida que outras directives se registrem (através de callbacks) e sejam alertadas quando o back-end retornar as mensagens internacionalizadas. Esta directive faz uso do MessageProvider para inicializar a busca por mensagens de internacionalização.

Abaixo temos um exemplo prático da utilização desta directive em dois contextos diferentes; tela de listagem e detalhe de períodos.

<div id="content" tl-object="period" tl-context="list">
 
	<!-- ... -->
 
	<!-- body -->
 
	<!-- ... -->
 
</div> 

Neste exemplo temos um outer div, ou seja, um div que engloba todos os outros elementos presentes na partial, utilizando a directive tl-object. Quando identificada, o seu construtor é executado e a partir dos valores de atributos em elementos HTML, incializa-se a busca de mensagens para a internacionalização.Toda e qualquer funcionalidade executada por outras directives nesta partial, incorporarão dois parâmetros na sua execução: objeto de negócio e contexto de visualização.

TL Key

A directive tl-key foi criada para atender o requisito de internacionalização e a padronização de leiaute para mensagens e validações. Esta directive faz uso da directive tl-object, a fim de obter o contexto da partial e então renderizar estes elementos no formato apropriado e, para registrar-se e obter as mensagens de internacionalização assim que a busca for finalizada pelo MessageProvider.

Listagem de atributos disponibilizados pela directive tl-key:

Abaixo temos um exemplo prático da utilização desta directive em dois contextos diferentes, tela de listagem e detalhe de períodos, e a estrutura final destas telas após a execução das directives.

<div id="content" tl-object="period" tl-context="list">
 	
	<h2 tl-ref="search.period" tl-key="title"/>
 

	<!-- ... -->
 
</div> 

Em sua execução, alguns elementos serão acrescentados e/ou modificados baseado no contexto adquirido através da directive tl-object.

TL Ref

A directive tl-ref visa facilitar a vida do desenvolvedor. Em conjunto com a directive tl-key, é possível criar referencias para chaves evitando a repetição de longos prefixos. Internamente, a directive tl-ref, assim como a directive tl-key, faz uso da directive tl-object a fim de obter o contexto e objeto da partial. Contudo, a tl-ref não manipula, de forma alguma, a árvore DOM, trabalhando unicamente em conjunto com o MessageProvider.

Listagem de atributos disponibilizados pela directive tl-ref:

Abaixo temos um exemplo prático de como esta directive pode ser utilizada para tornar o processo de desenvolvimento mais produtivo, evitando repetições de prefixos em chaves de internacionalização.

<div tl-object="company" tl-context="detail" tl-dialog tl-opened="detailDialog.isOpen">
 	
	<!-- ... -->
 
	<!-- Neste elemento é declarado o tl-ref, informando que todos os filhos deste nó referenciarão model.company -->
	<div class="dialog-page-body" tl-ref="model.company as model">

            <form class="aui">
                <div class="dialog-panel-body panel-body">

                    <div class="field-container">
 
						<!-- Este elemento é filho da div onde declaramos o tl-ref, ou seja, este tl-key agora é mapeado para "model.company.name" eliminando
a necessidade de informar o prefixo model.company -->
                        <input type="text" class="field-medium" tl-key="name" ng-model="model.0x1.name" />

                    </div>
 
				<!-- ... -->
 
	<!-- ... -->
 
</div> 

Internamente, no momento de execução do construtor da directive tl-ref, todas as mensagens presentes no MessageProvider, que estão no formato raw, são processadas conforme a referencia informada para a directive e colocadas em cache.

TL Find

A directive tl-find disponibiliza busca genérica a partir da interação do usuário com a UI sem a necessidade implementar as chamadas HTTP e event handlers. A partir de um objeto preenchido pelo usuário via data-binding (uso da directive ng-model), internamente a directive percorre os atributos deste objeto e monta uma consulta padrão. Esta consulta padrão leva em consideração os tipos de dados e é construída através de cláusulas AND (por padrão) e a concatenação dos atributos e valores do objeto. 

Listagem de atributos disponibilizados pela directive tl-find:

Abaixo temos um exemplo prático de como esta directive pode ser utilizada para realizar buscas genéricas de qualquer entidade já persistida no back-end.

<!-- partial que possui a estrutura apresentada para o usuário, com campos que estão mapeados (estes campos estão omitidos para simplicar o exemplo) em um objeto de nome 'model' no controller deste partial -->
<div id="content" tl-object="company" tl-context="list">
 	
	<!-- ... -->
 
	<!-- este botão contem a directive tl-find, na qual recebe o objeto model que contem os valores preechidos pelo usuário -->
	<!-- também esta mapeado o atributo tl-result, no qual diz que a resposta desta busca deve ser mapeada para o objeto 'list' presente no scope do controller desta partial -->
	<button class="aui-button align-right" tl-ref="common" tl-key="button.search" tl-find="model" tl-result="list" />

	<!-- ... -->
 
</div> 

Quando ocorrer um evento de click neste botão, a directive tl-find irá ler o objeto model, construir a consulta, realizar as chamadas ao back-end e preencher o objeto do tipo Array com nome list. Qualquer falha durante neste processo é descartada silenciosamente e a operação é interrompida.

TL Dialog

A directive tl-dialog quando aplicada em um elemento do tipo block, faz com que todos os elementos filhos sejam encapsulados em um container maior que é representado visualmente como um dialog. Esta directive também fornece um objeto a nível de controller, possibilitando que o desenvolvedor manipule suas propriedades de visibilidade.

Para criar este dialog, a factory $dialog esta disponível através de injeção de dependências e fornece métodos para criar um objeto do tipo Dialog. Uma referencia deste objeto deve ser informado em alguns atributos da directive, realizando a ligação entre as interações do controller, dialog e directive.

Listagem de atributos disponibilizados pela directive tl-dialog:

Abaixo temos um exemplo prático de como esta directive pode ser utilizada para termos a representação visual de dialogs para o usuário.

<!-- elemento div (do tipo block) que sinaliza para a arquitetura que este deve ser um dialog através do atributo tl-dialog -->
<!-- o atributo tl-opened referencia um objeto do tipo "Dialog" e a variável do tipo Boolean "isOpen" -->
<div tl-object="company" tl-context="detail" tl-dialog tl-opened="detailDialog.isOpen">

Durante a sua execução, a directive tl-dialog transforma este elemento em um dialog e controla sua visibilidade através da referencia passada para o atributo tl-opened.

Abaixo temos uma representação visual da directive tl-dialog da tela detalhe de Companhias da aplicação Shield.

TL Submit

A directive tl-submit, assim como a directive tl-find, executa operações no back-end utilizando os endpoints que expoe os métodos genéricos da arquitetura. Porém, a directive tl-submit realiza operações de edição, remoção e adição enquanto a directive tl-find executa apenas buscas genéricas.

Listagem de atributos disponibilizados pela directive tl-dialog:

TL Action 

A directive tl-action habilita a edição, deleção e visualização de dados já persistidos pelo back-end através do componente de dropdown list da Atlassian. Esta directive é utilizada em conjunto com o elemento <table> e com a directive tl-action-model para possibilitar que outros controlers recebam os dados. Cada linha da tabela renderiza um botão mostrando o menu de ações que podem ser executadas pelo usuário em um determinado objeto.

Listagem de atributos disponibilizados pela directive tl-action:

Abaixo temos um exemplo prático de como esta directive pode ser utilizada para habilitarmos as ações que podem ser tomadas pelo usuário de forma automática.

<table class="aui">
 
	<!-- ... -->
	
	<!-- neste exemplo a directive esta recebendo o objeto 0x1 do tipo array, através do atributo tl-action em conjunto com ng-repeat -->
	<tr ng-repeat="company in list.0x1" tl-action="list.0x1">
		<td>{{company.name}}</td>
    	<td>{{company.abbreviation}}</td>
    	<td>{{status[company.enabled]}}</td>
	</tr>
 
	<!-- ... -->
 
</table>

Durante sua execução, a directive tl-action altera os elementos <tr> para incluir a estrutura do menu e disponibilizar as funcionalidades de edição, visualização e deleção.

Abaixo temos uma representação visual da directive tl-action da tela listagem de Companhias da aplicação Shield.

TL Action Model 

A directive tl-action-model recebe o objeto em que ocorreu a ação do usuário, através da directive tl-action e atribui para o scope onde ela esta presente. A fim de padronizar as ações de usuário, usualmente dois controllers e duas partials são criadas para representar uma determinada entidade; listagem e detalhe, respectivamente. Conforme esta estrutura, utiliza-se a directive tl-action na tela de listagem e a directive tl-action-model na tela de detalhe para habilitar a manipulação de dados a partir de ações realizadas na directive tl-action.

Listagem de atributos disponibilizados pela directive tl-dialog:

Abaixo temos um exemplo prático de como esta directive pode ser utilizada para habilitarmos as ações que podem ser tomadas pelo usuário de forma automática.

<!-- o objeto que sofreu a ação através da directive tl-action será transportado para este controller e atribuído a variável de scopoe 'model'  -->
<div ng-controller="CompanyAddDialogCtrl" tl-action-model="model">
</div>

Durante sua execução, as directives tl-action e tl-action-model trocam mensagens utilizando o sistema de eventos do AngularJS para transportar os objetos que sofreram ações nas  telas de listagem.

TL Calendar

A directive tl-calendar disponibiliza o widget de calendário da API AUI da Atlassian. Esta directive funciona como um wrapper para a funcionalidade já implementada, facilitando a integração com o AngularJS e eliminando instruções em Javascript que manipulam a HTML DOM.

Listagem de atributos disponibilizados pela directive tl-calendar:

Abaixo temos um exemplo prático de como esta directive pode ser utilizada para habilitarmos um calendário de fácil usabilidade para o usuário final.

<!-- ... -->
 
	<!-- no input abaixo temos a presença da directive tl-calendar que transforma este input em um calendário  -->
	<input tl-calendar ng-model="view.startDate" tl-key="startdate" ng-change="splitStartDate()">
<!-- ... -->

Durante sua execução, a directive tl-calendar transforma esta directive anexando <div>s para construir a estrutura HTML necessária para montar o calendário.

Abaixo temos uma representação visual da directive tl-calendar da tela detalhe de Períodos da aplicação Shield.

TL Tab

A directive tl-tab disponibiliza o widget de tab-panels (abas). Dividida em dois atributos, tl-tabset e tl-tab, a directive tl-tab estrutura as abas de forma hierárquica. O atributo tl-tabset deve estar presente em um outer element ou nó pai, tendo como nós filhos o número desejado de elementos <div> contendo o atributo tl-tab.

Listagem de atributos disponibilizados pela directive tl-calendar:

Abaixo temos um exemplo prático de como esta directive pode ser utilizada para habilitarmos um calendário de fácil usabilidade para o usuário final.

<!-- inicializa este elemento como nó pai de todas as abas, controlando sua visibilidade -->
<div tl-tabset>
		
	<!-- transforma esta div em uma aba, internacionaliza seu título através da directive tl-key e determina a visiblidade através do atributo active apontando para a variável "active" nos objetos "view.tabs.dates" -->
	<div tl-tab tl-key="detail.period.dates" active="view.tabs.dates.active">
 
	<!-- ... -->
 
</div>

Abaixo temos uma representação visual da directive tl-tab da tela detalhe de Períodos da aplicação Shield.