Skip to end of metadata
Go to start of metadata

 

O components.json é um arquivo que possui uma estrutura do tipo JSON, é usado pelo editor HTML (Figura 1) para exibir informações e configurações de suas propriedades, eventos e responsividades de cada controle (Figura 2). É através dele que conseguimos adicionar mais recursos a um controle, permitindo sua customização sem a necessidade de configurá-lo via código.

Dentre alguns exemplos da necessidade do components.json no CronApp, estão: Alteração do nome e ícone exibido do controle no Editor HTML, personalização de elementos e atributos no template de forma visual, internacionalização do controle, inclusão de eventos a elementos do controle e outros.


Figura 1 - Editor HTML no CronApp

 


Figura 2 - Abas propriedades, eventos e responsividade também são influenciadas pelo components.json


Estrutura

A estrutura do components.json é baseada em JSON (JavaScript Object Notation - Notação de Objetos JavaScript) que possui uma formatação simples e de fácil leitura e escrita, tanto para computadores quando para humanos. Foi criado para facilitar a comunicação entre sistemas, independente da linguagem usada.

Os controles padrões do CronApp utilizam o mesmo arquivo "components.json", que fica em diretórios diferentes dependendo do tipo do projeto:

  • Projetos web: Código Fonte  Principal  Códigos Fonte Cliente  plugins  cronapp-framework-js  components
  • Projetos mobile: Código Fonte  Principal  mobileapp  www  plugins  cronapp-framework-mobile-js  components

O CronApp ainda nos permite criar novos controles personalizados e para cada novo controle, além do arquivo *.template.html também é criado o arquivo *.components.json que é exclusivo. Ambos arquivos devem ficar no mesmo diretório (Figura 3).

Figura 3 - Arquivos do novo controle criado pelo usuário


Em sua estrutura, o components.json possui um lista chamada "components" que possui vários objetos representando cada um dos controle padrões do editor HTML, diferente do arquivo gerado na criação do componente customizado (*.components.json) que só possui apenas um elemento nesta lista. Além disso, os documentos possuem o elemento "name" em sua estrutura principal que varia da seguinte forma (Figuras 4 e 5): 

  • Projeto web: crono-components;
  • Projeto mobile: cronos-components-mobile-phonegap e
  • Projeto web ou mobile criado pelo usuário: custom-cronos-components

 

Figura 4 e 5 - Diferença entre a estrutura do components.json gerada na criação do novo componente (esquerda) e o padrão para um projeto web (direita)


Uma JSON normalmente é constituído de três estruturas:

  • Valor: elemento mais simples, considerado a folha da árvore. Possui apenas uma chave e um valor. Ex: "name: Nome da propriedade", onde "nome" é a chave e "Nome da propriedade" é o seu valor.
  • Objeto: Um objeto pode possuir valores e também outros objetos em seu interior.
  • Lista: Possui uma lista de objetos em seu interior. 

Em uma lista existem 1 ou mais objetos que possuem a mesma estrutura, enquanto que um objeto pode possuir valores e outros objetos e essa estrutura não se repete.

 

Elementos do components.json

 

Elemento: (raiz)

Tipo: objeto
Descrição: Objeto que engloba todo o documento components.json.

ItemTipoObjetivoPossíveis valores / exemplo
namevalorDefine se é um arquivo responsável pelo controles padrões do CronApp ou um controle customizado pelo usuário.
  • cronos-components: Nome do arquivo responsável por todos os controles do CronApp web.
  • cronos-components-mobile-phonegap: Nome do arquivo responsável por todos os controles do CronApp mobile.
  • custom-cronos-components: Nome do arquivo responsável pelo novo controle criado pelo usuário no CronApp.
versionvalorValor com a versão do arquivo.Ex.: 1.0.0
componentslistaLista dos objetos responsável por definir os controles e suas propriedades.-

 

 

Elemento: components

Tipolista
DescriçãoLista dos objetos responsável por definir as cada componente e suas propriedades.

ItemTipoObjetivoPossíveis valores / exemplo
attributesForPreview listaLista de propriedades customizadas nos atributos CSS dos componentes -
autoWrappervalorAdiciona uma tag <div> em torno do template do componente, facilitando a modificação da diagramação.
  • true: Permite tratamento diferenciado entre o componente e a <div>.
  • false: Não permite tratamento diferenciado entre o componente e a <div>. Valor default quando não informada essa propriedade.
childrenPropertieslistaLista as diretivas Angular, elementos HTML ou exclusivas do CronApp para permitir sua edição nas propriedades dos subcomponentes (filhos) do controle do Editor HTML.Ex.: O controle "Caixa de checagem" possuem 2 subcomponentes: rótulo e caixa. O childrenProperties é responsável por possibilitar a criação de propriedades distintas para cada um desses subcomponentes.
classvalor

Define o ícone do controle que aparecerá no editor HTML.

Obs.: Diferente da aplicação que permite o uso dos ícones Glyphicons, font awesome icon e Material Design Icons; os botões dos componentes no editor HTML permite apenas o Material Design Icons.

Ex.: "adjust-icon mdi mdi-star"
classForPreviewobjetoAdiciona uma classe para ser visualizada somente no editor HTML, no modo de edição. Não irá aparecer na execução do projeto.-
dependencesobjetoPossui uma lista (editor) com os endereços de arquivos CSS específica para esse controle.-
forcedGroupvalorForça o agrupamento dos componentes HTML no template, permitindo a seleção de todos os subcomponente de uma só vez.
  • true: Agrupa todos os subcomponentes, necessário realizar o desbloqueio para poder selecionar cada subcomponente.
  • false: Permite a seleção de cada subcomponente sem a necessidade do desbloqueio. Valor default quando não informada essa propriedade.
groupedChildrenlistaLista os elementos HTML que compõem o template, possibilitando selecioná-los e personaliza-los no editor HTML. Essa seleção pode ser feita utilizando as subabas dentro das abas “Propriedades” e “Eventos” no Editor HTML ou selecionando o componente na tela, abrindo o ícone do cadeado e selecionando novamente os elementos internos do componente.

Para cada elemento do array, temos:

  • text_pt_BR: Internacionalização em português do Brasil para o rótulo da subaba que aparecerá em “Propriedades” e “Eventos” no Editor HTML referente ao elemento HTML selecionado.

  • text_en_US: Internacionalização em inglês do EUA para o rótulo da subaba que aparecerá em “Propriedades” e “Eventos” no Editor HTML referente ao elemento HTML selecionado.

  • selector: Informa qual elemento HTML será selecionado. Se o template possuir dois elementos HTML iguais, é possível utilizar o “selector” do CSS para referenciá-lo. Por exemplo, para selecionar o segundo elemento span do template: “span:nth-child(2)”.

handleRulesobjetoDefine características para algumas propriedades e regras para elementos do componente.

-

mask-placeholderobjeto

Informa qual componente HTML receberá o texto do campo Sugestão no editor HTML.

Possui em seu interior o valor "selector" onde será informado o componente HTML.

Ex.: { "selector": "input" }

namevalorAtributo id do componente HTML.-
palletevalorOculta ou exibe o controle no editor HTML.
  • true: exibe o controle no editor HTML. Valor default quando não informada essa propriedade.
  • false: oculta o controle no editor HTML.
propertiesobjetoLista as diretivas Angular, elementos HTML ou exclusivas do CronApp para permitir sua edição nas propriedades do componente no Editor HTML.Ex.: O controle "Caixa de checagem" possuem 2 subcomponentes: rótulo e caixa. O Properties é responsável por criar propriedades que afetam todo o controle, diferentemente do childrenProperties.
rowsvalorDefine o tamanho do campo em número de linhas.Ex.: 5
templatevalorTemplate HTML do componente. Por este ser um arquivo json, será necessário utilizar caracteres de escape para utilizar alguns caracteres. Exemplo: “\n”e “\””Ex.: "<i class=\"fa fa-star\"/>"
templateURLvalorEndereço do template do componente.-
textvalorNome do componente que aparecerá no editor HTML quando não houver internacionalização (propriedades: text_en_US e text_pt_BR).Ex.: "Button"
text_en_USvalorInternacionalização (inglês EUA) do nome do componente que aparecerá no editor HTML.Ex.: "Button"
text_pt_BRvalorInternacionalização (português Brasil) do nome do componente que aparecerá no editor HTML.Ex.: "Botão"
wrappervalorAdiciona uma tag <div> em torno do template do componente.
  • true: Adiciona uma tag <div>. Valor default quando não informada essa propriedade.
  • false: Não adiciona uma tag <div>.

 

 

Elemento: attributesForPreview

Tipolista
DescriçãoLista de propriedades customizadas para os atributos CSS dos componentes.

ItemTipoObjetivoPossíveis valores / exemplo
namevalorNome da propriedade que terá suas características alteradas neste objeto do attributesForPreview.Ex.: "xattr-size"
typevalorDefine a forma que será exibida as opções da propriedade. Normalmente são utilizados o grupo de botões ou seletor de itens.
  • btngroup: Para exibir as propriedades em um grupo de botões alinhados. Permite a utilização de ícones nos botões.
  • options: Para exibir as propriedades em um seletor de itens (dropdown). Permite a utilização de ícones, cores ou ambos.
targetvalorInforma o atributo ou elemento que será customizado. Normalmente utilizado para adicionar “class” ou “style”.Ex.: "class"
valueslistaLista das opções da propriedade. 
-

 

 

Elemento: values do attributesForPreview

Tipolista
Descrição: Lista das opções da propriedade attributesForPreview

ItemTipoObjetivoPossíveis valores / exemplo
keyvalorClasse CSS que será adicionado no template após o usuário escolher o value.
Ex.: "display:block;"
valuevalorNome da opção que será exibida para o usuário.Ex.: "Block"
iconvalorExibe um ícone ao lado do nome da opção.Ex.: "mdi mdi-ray-start"
colorvalorExibe um quadrado com a cor especificada ao lado do nome da opção. Só é possível utilizar com o type “options”.Ex.: "#fff"

 

 

Elemento: childrenProperties

Tipolista
Descrição

ItemTipoObjetivoPossíveis valores / exemplo
displayName_en_USvalorInternacionalização (inglês EUA) do nome do campo que aparecerá no editor HTML.Ex.: "Field"
displayName_pt_BRvalor

Internacionalização (português Brasil) do nome do campo que aparecerá no editor HTML.

Ex.: "Campo"
editExpressionvalorExibe o ícone "Editar expressão" ao lado do nome do campo. Ao clicar é aberta uma caixa de texto para a edição da expressão ou inserção de Fonte de dados.
  • true: Ativa a opção.
  • false: Desativa a opção. Valor default quando não informada essa propriedade.
namevalor

Informa o atributo do elemento HTML que será manipulado em um campo do editor HTML.

Ex.: "ng-model"
onDisplayvalorExecuta comando em JavaScript para atualizar o componente na tela sempre que uma alteração for feita.Ex.: "javascript:function() { /* função JavaScript */ }"
onSavevalorExecuta comando em JavaScript para salvar sempre que uma opção for selecionada ou ação tomada no componente.Ex.: "javascript:function() { /* função JavaScript */ }"
selectorvalorInforma qual atributo do elemento HTML será selecionado para manipulação.Ex.: "ui-select"
typevalorDefine a forma de como o subcomponente irá se comportar. Como permitir apenas texto, seletor ou importação de fonte de dados.Ex.: "datasourceFieldList"

 

 

Elemento: handleRules

TipoObjeto
DescriçãoDefine características para algumas propriedades e regras para elementos do componente.

ItemTipoObjetivoPossíveis valores / exemplo
canActivatevalorAtiva ou desativa as regras.
  • true: Ativa o handleRules do componente.
  • false: Desativa o handleRules do componente.
canIncrementvalorExibe o ícone "Adicionar" ao lado do nome do campo. Ao clicar é inserido outro item na lista. Exemplo: outra coluna em uma tabela ou outro item em uma lista de opções.
  • true: Insere o ícone "Adicionar".
  • false: Oculta o ícone "Adicionar". Valor default quando não informada essa propriedade.
canOrdervalorDefine a possibilidade de ordenação dos itens.
  • true: Possibilita ordenação dos itens. Valor default quando não informada essa propriedade.
  • false: Impede ordenação dos itens.
canTogglevalorMostra o ícone "Exibir" ao lado do nome do campo. Esse ícone recolhe ou expande os itens ou submenus desse controle no editor HTML, permitindo visualizar e selecionar seu conteúdo para personalização. Exemplo caixa de seleção ou menu.
  • true: Insere o ícone "Exibir".
  • false: Oculta o ícone "Exibir". Valor default quando não informada essa propriedade.
ruleslistaDefine algumas regras para alteração do template do componente a partir de determinadas ações.-

 

 

Elemento: rules do handleRules

Tipolista
Descrição: Lista de regras do controle.

ItemTipoObjetivoPossíveis valores / exemplo
accordionTabClickedvalorEspecífico do controle Acordeão, usado para acionar a ação de expandir ou recolher seus itens no editor HTML.-
activeClassvalorAtiva classe específica especificada.Ex.: "in"
activeSelectorvalorSeleciona o atributo que sofrerá a alteração.Ex.: "ul.nav-tabs li.active"
sourceHTMLvalorDefine trecho do HTML que será acrecido ou retirado do template, caso a regra seja atendida.Ex.: "<li></li>"
targetSelectorvalor

Seleciona um elemento HTML ou classe CSS para sofrer a alteração,

Ex.: "div.panel-collapse.content"
toggleClassvalorAdicionar ou retirar uma classe CSS.Ex.: "invisible"
toggleSelectorvalorAdicionar ou retirar um elemento seletor.Ex.: "ui-select-choices"

 

 

Elemento: properties

TipoObjeto
Descrição: Define as propriedades e evento do controle.

ItemTipoObjetivoCampo
crn-datasourceobjetoDefine a fonte de dados do componente.Fonte de dados
cronapp-filter-autopostobjetoRealiza consulta ou ação a cada letra digitada no campo.Postagem Automática
cronapp-filter-caseinsensitiveobjetoDefine se o campo diferenciará letras minúsculas e maiúsculas.Case Insensitive
cronapp-filter-operatorobjetoDefine operadores relacionais e de igualdade. (=, <, >, <= e >=)Operador
dependent-byobjetoCria uma dependência do componente para a exibição de conteúdo. Exemplo: As informações sobre um usuário só irá aparecer na tela quando um dos usuários forem selecionados.Depende de
dependent-lazy-postobjetoCria uma dependência do componente com a fonte de dados informada para a inserção de conteúdo. Nesse campo deve ser informado o objeto independente em relação ao campo "Dependente de postagem de campo sob demanda". Exemplo: As regras para um usuário só será submetida se existir um usuário.Dependente de postagem sob demanda
dependent-lazy-post-fieldobjetoCria uma dependência do componente com a fonte de dados informada para a inserção de conteúdo. Nesse campo deve ser informado o objeto ou id que ficará dependente. Exemplo: As regras para um usuário só será submetida se existir um usuário.Dependente de postagem de campo sob demanda
entityobjetoDefine qual a fonte de dados que irá alimentar o componente.Origem de dados
hrefobjetoDefine uma URL para gerar um link.Referência
keysobjetoDefine quais parâmetros serão usados como chave na fonte de dados.Chaves
maskobjetoLista pré definida de mascarás. Exemplo: CEP, CPF, data, telefone entre outros.Máscara
mask-placeholderobjetoPossibilita adição de novas mascarás customizadas.Sugestão de Máscara
ng-clickobjetoExecuta evento ao clicar (AngularJS).Ao clicar
on-after-createobjetoExecuta um evento após a criação algo.Após criar
on-after-deleteobjetoExecuta evento após ação de deletar algo.on-after-delete
on-after-fillobjetoExecuta evento após preenchimento de um campo.Após preencher
on-after-updateobjetoExecuta evento após atualização de algo.Após atualizar
on-before-createobjetoExecuta evento antes de criar algo.Antes de criar
on-before-deleteobjetoExecuta evento antes de deletar algo.Antes de deletar
on-before-updateobjeto

Executa evento antes de atualizar algo.

Antes de atualizar
onclickobjetoExecuta evento ao clicar no componente (JavaScript).Ao clicar
on-errorobjetoExecuta um evento quando ocorrer um erro no carregamento de algum arquivo ou mídia.Ao errar
onmouseoverobjeto

Executa evento no precionar do clique do botão (JavaScript).

Ao clicar
qrobjetoExclusivo para o controle QR Code.QR Code
srcobjetoDefine campo para carregamento de imagem.Origem
targetobjetoSeleciona em qual janela será aberta o link.Alvo
xattr-fullsizeobjetoDetermina se o componente ocupará a linha inteira ou não. Suas opções padrões são "inline" ou "block"; definidas no attributesForPreview.Largura
xattr-positionobjetoDetermina em qual posição o componente ficará alinhado. Suas opções padrões são à esquerda (Standard), centro (Middle) ou direita (Right); definidas no attributesForPreview.Posição
xattr-sizeobjetoDetermina o tamanho do componente na tela. Suas opções padrões são Standard, Larger (btn-lg) e Small (btn-sm); definidas no attributesForPreview.Tamanho
xattr-themeobjetoDetermina o tema do componente. Suas opções padrões são Default, Primary, Success, Info, Warning, Danger e Link; definidas no attributesForPreview.Tema
xattr-typeobjetoDetermina o o estilo do botão. Suas opções padrões são Default, Clear (button-clear) e Outline (button-outline); definidas no attributesForPreview.Style Type

 

 

Elemento: características do properties

TipoObjeto
Descrição: Define as características das propriedades e evento do controle.

Obs: O último nível "propriedades" está entre aspas pois representa qualquer uma das properties citadas acima.

ItemTipoObjetivoPossíveis valores / exemplo
displayName_en_USvalorInternacionalização em inglês do EUA para o rótulo do campo no Editor HTML.Ex.: "Datasource"
displayName_pt_BRvalorInternacionalização em português do Brasil para o rótulo do campo no Editor HTML.Ex.: "Fonte de dados"
onDisplayvalorExecuta comando em JavaScript para atualizar o componente na tela sempre que essa propriedade for alterada.Ex.: "javascript:function() { /* função JavaScript */ }"
onSavevalorExecuta comando em JavaScript para salvar sempre que uma opção for selecionada ou ação tomada no componente.Ex.: "javascript:function() { /* função JavaScript */ }"
optionslistaDefine quais chaves/valores serão exibidas quando a propriedade for do tipo lista.-
options: keyvalorChave da opção para propriedades do tipo lista.Ex.: "true"
options: valuevalorValor da opção para propriedades do tipo lista.Ex.: "Sim"
removablevalorExibe o ícone "Remover propriedade" ao lado do nome do campo. Ao clicar, o campo será removido dentre as propriedades ou eventos. É possível chamar novamente a propriedade através do campo "Nova propriedade".
  • true: Insere o ícone.
  • false: Oculta o ícone. Valor default quando não informada essa propriedade.
resourceTypevalorDefine o tipo do recurso usado na propriedade. Exemplo: "image/jpeg,image/gif,image/png" (permite imagens do tipo jpeg, gif ou png)Ex.: "image/jpeg, image/gif, image/png"
typevalorDefine em qual aba o campo aparecerá (Propriedades ou Eventos), além da forma de como o campo irá se comportar: permitir apenas texto, seletor, abrirá uma janela para segurança, importação de fonte de dados ou eventos.Ex.: "event"