Skip to end of metadata
Go to start of metadata

Os controles são conjuntos de códigos HTML (template) agrupados em componentes. O uso dos controles do CronApp facilitam muito o desenvolvimento de telas (mobile ou web), graças a sua simplicidade, bastando arrastar os controles enquanto monta layout 

A adição ou alteração dos atributos HTML, diretivas do AngularJS ou propriedades do CSS Bootstrap podem ser feitos através das propriedades do controle de forma totalmente visual na aba à direita do editor HTML, sem a necessidade de edição no código fonte durante o desenvolvimento do seu sistema. 

Além dos diversos controles já existentes nCronApp, é possível criar novos, adicionar propriedades e tipos de eventos próprios.

Pré-requisitos

Antes de começar a seguir os passos do tutorial é preciso ter certeza de que se tem um ambiente minimamente preparado para reproduzir o exemplo. Abaixo estão os requisitos principais.

Requisitos:

  1. Projeto do tipo web criado. Caso haja dúvidas de como criar esse tipo de projeto acesse o link (Criando Projeto Web).

Visão geral: exemplo

Nesse tutorial iremos aprender a criar um novo controle e inserir propriedades e eventos a ele utilizando o arquivo components.json.

O controle que iremos criar é o badge, ele é um botão ou link que possui um circulo com um número que representando a quantidade de um grupo de itens, ao clicar no link ou botão, o usuário visualiza esses itens. Costuma ser usado em caixa de e-mails, carrinho de compras em sites de vendas e mensageiros, informando o número de mensagens que ainda não foram lidas (Figura 1).

Para simplificar o teste em nosso tutorial, iremos adicionar um botão que incrementará o valor do badge. 


Figura 1 - Exemplo de uso do componente Badge.

Passos 

1-Criação do "Novo Componente Visual"

Primeiramente vamos criar um Novo Componente Visual no pacote META-INF que faz parte do pacote “Código Fonte Servidor” em Código Fonte → Principal → “Códigos Fonte Servidor” META-INF . Clicando com o botão direito do mouse em META-INF, selecione Novo > Novo Componente Visual (Figura 2). 

Figura 2 - Criação do Novo Componente Visual


Na janela de escolha de modelo do componente json, selecione a opção Novo Componente e clique em Avançar (Figura 3).

Figura 3 - Seleção Componente json

 

Na Próxima etapa, devemos inserir informações para o componente: nomes do arquivo, componente e id, template HTML, controladores Angular, endereços do JavaScript e CSS (Tabela 1) e logo em seguida clicamos em Finalizar (Figura 4). 


Figura 4 - Preenchendo dados do novo componente visual


CampoConteúdo
Nome do Arquivo badge
Id do Coimponente crn-badge
Nome do Componente Badge
URL de JavaScripts Requeridos

 

URL de CSS Requeridos  
Template HTML 
<a href="#" > 
    <span>Badge</span> 
    <span class="badge"
      ng-model="vars.valorBadge${RANDOM}">
            {{vars.valorBadge${RANDOM}}}
    </span>
</a>
Controladores Angular (se houver)

 

Tabela 1 - Dados para criação do componente

Dica:

Em nosso template, estamos incluindo o "${RANDOM}" nas diretivas AngulaJS para gerar um número aleatório no nome do componente. Isso será necessário quando tivermos mais de um controle badge na mesma página, permitindo tratamento diferente para cada controle.

    1.1-Alterando as propriedades

Nesse momento o badge já está entre os controles no editor HTML. Porém, ainda teremos que adicionar um seletor dos elementos do controle no editor HTML, isso permitirá a configuração de cada parte do nosso controle (Figura 5).


Figura 5 - Novo componente sem as subabas de seleção dos seus elementos

Dica:

Sempre que um controle for criado ou seu template ou component alterado, é necessário fechar a aba do editor HTML (*.view.html) e abri-la novamente para que seja renderizada a atualização.

Se um controle já estiver na tela antes de uma atualização, será necessário excluí-lo e arrastá-lo novamente. Controles já utilizados não recebem atualizações de forma automática.

    1.2-Arquivos template e components.json

Ao criarmos um novo componente visual, são criados dois arquivos:

  • *.template.html, onde ficam o html do template do componente e
  • *.components.json, é a partir desse arquivo que o editor HTML irá buscar e exibir as propriedades e tipos de eventos específicos para esse controle.

Enquanto o template.html exibe a forma mais básica do nosso componente, o components.json nos permite personalizar de forma visual esses controle no editor HTML, sem a necessidade de mexer no código fonte.

Ambos arquivos ficam no mesmo local onde foi criado o componente visual, no diretório META-INF (Figura 6). 

Figura 6 - Arquivos gerados após a criação do novo controle

 

Os controles padrões do CronApp não possuem um arquivo *.components.json para cada controle, ao invés disso, todos utilizam um único arquivo chamado components.json que fica em Código Fonte  Principal  Códigos Fonte Cliente  plugins  cronapp-framework-js  components. Já os templates dos controles podemos encontrá-los dentro do mesmo diretório, na subpasta templates.

Atenção:

Nunca apague ou modifique o arquivo components.json ou os templates padrões. A modificação ou exclusão dos controles padrões irá afetar o uso desses controles em outras partes do sistema. Utilize esses arquivos como base para a criação de novos componentes.

Se necessitar modificar algum controle padrão, crie um controle novo.

O badge.components.json nos permite adicionar informações padrões para o controle criado.  Na tabela 2 temos alguns exemplos das propriedades que podem ser usadas.

PropriedadesFunção
nameNome informado na diretiva data-component dentro do template.
text_pt_BR e text_en_USInternacionalização do nome que será exibido abaixo do ícone do controle.
Essa internacionalização é referente ao controle em si e é direcionada para o desenvolvedor do sistema, para informações sobre internacionalização do projeto, veja mais em (Internacionalização - suporte a múltiplos idiomas).
wrapperAdiciona uma tag <div> no template do controle.
templateURLLink para o template do controle.
propertiesPropriedades padrões do controle, onde podemos personalizar as configurações do controle, eventos e muito mais.
attributesForPreviewAlteração de temas para o controle.
groupedChildrenPossibilita a seleção dos elementos dentro do controle.

Tabela 2  - Exemplo de propriedades encontradas no components.json

 

Mais sobre

Para mais informações sobre as propriedades do components.json, acesse Entendendo o Components.json.

 

Para o nosso exemplo, vamos utilizar o "groupedChildren" para permitir a seleção e personalização tanto do rótulo quanto do campo que informa o valor do badge. O "groupedChildren" deve ser inserido após a chave que finaliza o "properties". Como vemos na Figura 7, estamos selecionando o primeiro tag <span> (utilizando o "span:nth-child(1)") do nosso componente e nomeando para "Rótulo" e a segunda para "Valor".

Figura 7  - Adicionando o groupedChildren no Badge.components.json

Seletor de elementos do controle
,
"groupedChildren": [
	{	"text_pt_BR": "Rótulo",
		"text_en_US": "Label",
		"selector": "span:nth-child(1)" 
	},
	
	{	"text_pt_BR": "Valor",
		"text_en_US": "Value",
		"selector": "span:nth-child(2)" 
	}
]

 

    1.3-Verificando o novo Componente Visual 

Após salvarmos o arquivo badge.components.json, vamos testar o nosso componente na página home.view.html que encontra-se em Código Fonte  Principal  Códigos Fonte Cliente  views  logged  home.view.html. Lembramos da necessidade de reabrir o editor HTML após alterações no template ou components.json, como informamos anteriormente.

Na aba Controle do editor HTML, arrastamos o componente Badge para o centro da tela (Figura 8).

Figura 8  - Arrastando o componente criado

Ao selecionar o item arrastado para o centro da tela, veremos agora que existem 3 subabas: Principal, para a seleção de todo o controle; Rótulo, para selecionar somente o texto com o link e o campo Valor, que selecionará a numeração do badge. A partir de agora, podemos adicionar propriedades e eventos a cada elemento do controle (Figura 9).

Figura 9  - Subabas para seleção dos componentes Rótulo e Valor 

Dica

Também é possível selecionar o campo valor selecionando o controle na tela, desativando o ícone do cadeado circulado e clicando no elemento desejado (Figura 9).

 

Nesse momento finalizamos a criação do controle Badge, ele já pode ser utilizado no desenvolvimento das telas do sistema, bastando arrastá-lo para a tela em nosso editor HTML.

A partir de agora, vamos utilizar o controle recém criado.

2-Utilizando componente

Nesse tutorial, o contador do Badge sempre iniciará com "0" e a cada novo clique do botão, o seu valor será incrementado. Essa inicialização do contador pode ser feita de várias formas, como por exemplo, a criação de um bloco de programação que passaria o valor "0" sempre que o componente fosse renderizado na tela. Mas uma forma mais simples será utilizar a diretiva AngularJS ng-init, passando o nome do componente e o valor a ser iniciado.

Precisamos descobrir primeiro o nome que foi gerado pelo AngularJS para o campo valor do Badge, pois, como já informamos acima, usamos o "${Random}" para gerar nomes únicos para cada controle. Para descobrirmos o nome, basta selecionar a subaba "valor" na aba "Propriedade" e teremos o nome em "Campo", na Figura 9 vemos o nome gerado nesse exemplo: vars.valorBadge5351.

Dica

O "vars" antes do nome é um padrão do CronApp, ele é utilizado para criar variáveis sem a necessidade de inicializá-la, evitando Variável não inicializada.

 

    2.1-Adicionando Evento de inicialização

Com o Badge selecionado, clicamos na aba "Eventos", na subaba "valor" e no primeiro campo "Novo Evento" selecionamos a opção "Ao iniciar" e informamos "vars.valorBadgeNUMERO_GERADO = 0", no nosso exemplo ficou: "vars.valorBadge5351 =0". Finalizamos clicando no check verde "Salvar novo evento", ao lado (Figura 10).

Figura 10  - Inicializando o valor do controle

    2.2-Adicionando o botão

O  próximo passo será a adição do botão que irá incrementar o valor do Badge. Na aba Controles, arrastamos o ícone do botão para o centro da tela.  

Vamos aproveitar para alterar o rótulo do botão e do badge. Selecionamos o controle, clique na aba Propriedades do editor HTML, na subaba Rótulo e alteramos o campo Conteúdo "Contador" para o badge e "Incrementador" no botão (Figura 10). 

Figura 10  - Alterando o rótulo do Badge

 

 

    2.3-Adicionando Evento no clique do botão

Precisamos agora adicionar o evento do botão para incrementar o valor do badge a cada clique. A única coisa que o botão irá fazer é incrementar o valor, então basta adicionar no evento "Ao Clicar", do botão, o "vars.valorBadge5351 =+", acrescentando + 1 no número do badge  (Figura 11).

Figura 11  - Adicionando Evento do botão


    2.4-Usando o badge 

Agora vamos rodar nossa aplicação (F9) e visualizar a nossa tela home.

Como exibido na Figura 12, o nosso novo controle é incrementado a cada clique do botão "incrementador".

Obs.:

O sistema irá solicitar login e senha, digite "admin" em ambos os campos e clique em Entrar.


Figura 12  - Teste


 

 

Nesta Página