# Documentação I9 Framework
### O que é o I9 framework?
O `I9 framework` é um low code capaz de `acelerar o processo de criação de telas` e CRUD's seguindo um modelo base já pré-definido.
### Base de funcionamento
Seu funcionamento se dá primordialmente através de um `dicionário`, que é uma estrutura de dados utilizada para configurar e descrever as `entidades` dentro do framework, que serão refletidas pelas tabelas e suas respectivas colunas criadas no `banco de dados`.
---
## Dicionário
A seguir vamos passo a passo revisar cada campo presente no dicionário e sua funcionalidade baseado em uma tela de cadastro de `Clientes`.
### Nome
- O campo `nome` define o nome do dicionário criado, que `segue o nome da tabela criada no banco de dados`, no exemplo abaixo foi criada uma tabela no banco com nome de ‘CLIENTES’, então definimos o campo nome com a mesma nomenclatura.
-
```bash=
"nome": "CLIENTES", # o nome da tabela do banco de dados
```
- Apesar de seguir sempre o nome da tabela no banco, este campo também aceita a separação de alguns campos da tabela para uma `aba separada` a fim de melhor organização. Por exemplo, além de criar o dicionário para CLIENTES, também é possível criar um novo dicionário para uma `tela filha` lidar com os campos de dados residenciais dos clientes, por ex:
```bash=
"nome": "CLIENTES|DADOS_RESIDENCIAIS",
```
- No exemplo acima, a regra é utilizar o nome da tabela (CLIENTES), `utilizar o ‘|’` e a seguir o `nome de preferência`, `sem precisar criar uma tabela no banco de dados` para os dados residenciais.
### Resource
```bash=
"resource": "CADASTRO", # o resource qual a tela pertence
```
### Descricao
```bash=
"descricao": "Cadastro de Clientes", # a descrição da funcionalidade da tela
```
### Caption
- O campo `caption` define o `texto que será exibido como título da tela` e do popup de cadastro, ele aceita uma string simples que deixa o mesmo texto em todos os lugares, como por ex:
```bash=
"caption": "Cadastro de Contratos",
```
- Mas também aceita um `objeto` para `personalizar` o texto em cada lugar específico, por ex:
```bash=
“caption”: {
"title_search": "Clientes",
"title_cad": "Cadastro de Cliente",
"title_tab": "Dados Pessoais"
},
```
### Modulo
```bash=
"modulo": "CADASTRO", # o módulo qual a tela pertence
```
### Cached
```bash=
"cached": false,
```
### Disable Multiple Records
```bash=
"disableMultipleRecords": false,
```
### Controle Acesso Loja Regional
```bash=
"controleAcessoLojaRegional": "",
```
### Is Grid
```bash=
"isGrid": false,
```
### Card Component
- O campo `cardComponent` permite utilizar um `componente personalizado` dentro do card, por exemplo um componente de avatar que dentro de “params” o “field_icon” recebe a referência de um campo, como URL por exemplo:
```bash=
"cardComponent": {
"component": "card-with-avatar",
"params": {
"field_icon": "URL"
}
},
```
- Caso o campo não receba nenhum componente, seu comportamento normal fica assim:
```bash=
"cardComponent": {},
```
### Fields View
- Este campo recebe um array de objetos que é responsável por organizar os campos na tela durante a exibição do conteúdo cadastrado, a seguir um exemplo prático de um display com 4 campos:
```bash=
"fieldsView": [
{
"fieldName": "NOME", # nome do campo baseado na coluna do banco de dados
"fieldDisplay": "Nome", # texto que será exibido na tela
"displayLine": 1, # posição da linha em que o conteúdo será exibido
"displaySize": 50 # o tamanho que o conteúdo irá ocupar na linha (máx de 100 por linha)
},
{
"fieldName": "CPF",
"fieldDisplay": "CPF",
"displayLine": 1,
"displaySize": 50
},
{
"fieldName": "RG",
"fieldDisplay": "RG",
"displayLine": 2,
"displaySize": 50
},
{
"fieldName": "TELEFONE",
"fieldDisplay": "Telefone",
"displayLine": 2,
"displaySize": 25
}
],
```
### View Name / View Detail
- Uma versão simplificada do Fields View, que aceita apenas uma string com o nome do campo de escolha, por exemplo:
```bash=
"viewName": "NOME",
"viewDetail1": "TELEFONE",
"viewDetail2": "EMAIL",
"viewDetail3": "COMISSAO",
"viewDetail4": "",
```
- Neste caso, a organização dos campos na tela foi feita pelas definições feitas dentro de cada campo cadastrado.
### Read Only
- Este campo recebe um booleano que define se a tela poderá ser editada ou não:
```bash=
"readonly": false,
```
```bash=
"readonly": true,
```
### Is Closed
- Este campo recebe um `booleano` que define se a `listagem do conteúdo` acontecerá imediatamente que o usuário abrir a tela, ou se o usuário terá que acionar o botão de busca para o conteúdo ser listado, ex:
```bash=
"isClosed": false,
```
```bash=
"isClosed": true,
```
### Before Post
```bash=
"beforePost": "",
```
### After Post
```bash=
"afterPost": "",
```
### Order By
- O campo de `orderBy ordena` a listagem de acordo com um campo específico de preferência, abaixo segue um exemplo da listagem sendo ordenada pelo campo NOME seguindo a ordem alfabética:
```bash=
"orderBy": "NOME",
```
- Também é possível utilizar o ‘DESC’ para indicar que a listagem deve seguir ordem descendente, por ex:
```bash=
"orderBy": "NOME DESC",
```
### Field For Filter
- Este campo recebe um `array de objetos` que permite o usuário realizar a `busca` utilizando um `filtro específico`, por ex:
```bash=
"fieldsForFilter": [
{
"fieldName": "NOME", # este campo recebe o nome do campo desejado
"fieldDisplay": "Nome" # este será o texto que será exibido no display
},
{
"fieldName": "CPF",
"fieldDisplay": "CPF"
},
{
"fieldName": "RG",
"fieldDisplay": "RG"
},
{
"fieldName": "TELEFONE",
"fieldDisplay": "Telefone"
}
],
```
### Rel Orientation Landscape
```bash=
"relOrientationLandscape": false,
```
### Rel Columns
```bash=
"relColumns": "",
```
### Rel In List
```bash=
"relInList": false,
```
### Children Tables
- Este campo recebe um `array de objetos` que `definirá as abas` presentes no popup de cadastro, o “tableName” receberá o nome de outros dicionários cadastrados no sistema.
```bash=
"childrenTables": [
{
"tableName": "CLIENTES|DADOS_RESIDENCIAIS"
},
{
"tableName": "CLIENTES_VEICULOSDESEJADOS"
},
{
"tableName": "CLIENTES_IMAGEM"
}
],
```
### Primary Key
- Este campo deve receber a `chave primária` da tabela cujo a tela está sendo referenciada, é aconselhável criar a chave primária com o prefixo `‘GUID_’` para melhor funcionamento do framework, por ex:
```bash=
"primaryKey": "GUID_CLIENTES",
```
### Custom Fields
- O campo de Custom Fields recebe uma `consulta SQL` para caso seja preciso em casos excepcionais, por ex:
```bash=
"customFields": "(select URL from veiculos_imagem where GUID_VEICULOS = veiculos.GUID_VEICULOS order by ORDEM limit 1) as LOOOKUP_IMAGEM",
```
- Neste exemplo, é feita uma busca de um valor em outra tabela e a renomeação da coluna resultante da consulta para “LOOOKUP_IMAGEM” para este valor ser usado em outra ocasião de preferência.
### Projection
```bash=
"projection": "",
```
### Bookmark
```bash=
"bookmark": [],
```
### Join
```bash=
"join": "",
```
---
### Campos
- Este campo é de extrema importância na criação de dicionários com o framework, pois é ele quem `recebe as colunas da tabela` cujo está sendo referenciada através de um `array de objetos`, cada objeto possui `diversos atributos` e logo abaixo vamos passar por cada um deles e explicar suas responsabilidades.
```bash=
"campos": [
{
```
#### Tabela
- O campo `Tabela` receberá o `nome da tabela no banco de dados` cujo a coluna pertence:
```bash=
"tabela": "CLIENTES",
```
#### Nome
- O campo `Nome` receberá o próprio `nome da coluna`.
```bash=
"nome": "NOME",
```
#### Ordem
- O campo `Ordem` funciona como uma espécie de `identificador para o campo` (o recomendado é seguir uma sequência 0, 5, 10, 15…) necessário para melhor funcionamento do framework.
```bash=
"ordem": "5",
```
#### Caption e Hint
- O campo `Caption` define o `título` que o `input` receberá, enquanto o campo `Hint` recebe o `placeholder` que o input terá, por ex:
```bash=
"caption": "Nome",
"hint": "Nome"
```
#### Tipo
- O campo `Tipo` recebe o `tipo da coluna no banco de dados`, os tipos podem ser: `varchar, char, integer, text, date, textarea e numeric`. Vale a observação que o tipo numeric é usado como tipo decimal no banco de dados.
```bash=
"tipo": "varchar",
```
#### Tamanho
- O `Tamanho` receberá apenas o tamanho que a `coluna` foi definida no `banco de dados`, no exemplo, o campo Nome recebeu o tipo varchar com tamanho de 40, logo o campo de Tamanho receberá 40.
```bash=
"tamanho": "40",
```
#### Decimal
- O campo `Decimal` é apenas um campo para definir o tamanho caso a coluna seja do tipo `numeric`, por exemplo, um campo definido como numeric(10,2) no banco de dados receberá "tamanho": "10", "decimal": "2".
```bash=
"decimal": "2",
```
#### Obrigatorio
- O campo de `Obrigatorio` recebe um `booleano` para definir se o campo deve ser obrigatório ou não, caso o campo seja definido como `“true”` e o usuário não preenchê-lo, no momento de salvar será exibido um `toast` informando que o campo é obrigatório.
```bash=
"obrigatorio": true,
```
#### Auto Incremental
```bash=
"autoIncremental": false,
```
#### Unico
```bash=
"unico": false,
```
#### Valor Default
- O campo `ValorDefault` define um valor já pré determinado ao abrir o `popup de cadastro`, por ex:
```bash=
"valorDefault": "Teste",
```
#### Visivel
- O campo `Visivel` receberá um `booleano` que vai definir se o campo ficará visível na tela ou não.
```bash=
"visivel": true,
```
#### Relacionamento
- O campo de `Relacionamento` recebe um `objeto` que faz a `relação` do input com a coluna de uma outra tabela diferente no banco de dados.
- Imagine que estamos criando um dicionário de cadastro de veículos, e temos uma coluna para selecionar a cor do veículo, porém as cores disponíveis para selecionar vem da coluna ‘COR’ da tabela de ‘CORES’, sendo assim o campo de Relacionamento ficaria assim:
```bash=
"relacionamento": {
"tabelaPai": "CORES", # nome da tabela de busca
"campoPai": "GUID_CORES", # primary key da tabela de busca
"displayCaption": "COR" # nome da coluna
},
```
#### Component
- O campo `Component` recebe um objeto com um atributo de `“nome”` para definir qual componente o input será, existem `3 tipos` de componentes:
- **TComboBox**: É um componente simples de `dropdown` dos itens definidos, por ex:
```bash=
"component": {
"nome": "TComboBox", # nome do componente
"items": [
{
"key": "V", # valor que será inserido no banco de dados
"displayValue": "Veículo comprado" # texto exibido como opção
},
{
"key": "E",
"displayValue": "Em busca de veículo"
},
{
"key": "S",
"displayValue": "Sem interesse no momento"
}
]
},
```
- **TLookupComboBox**: Também é um `dropdown`, mas o conteúdo a ser listado vem diretamente do `banco de dados`, por ex:
```bash=
"component": {
"nome": "TLookupComboBox", # nome do componente
"dataSource": "CORES", # nome da tabela de busca
"valueFieldName": "GUID_CORES", # primary key da tabela de busca
"displayFieldName": "COR" # coluna do banco de dados que deseja buscar o dados
},
```
- **TPopupComboBox**: Este componente abre um `popup` na tela para o usuário fazer uma `busca mais precisa`, por ex:
```bash=
"component": {
"nome": "TPopupComboBox", # nome do componente
"dataSource": "ESTADO", # nome da tabela de busca
"valueFieldName": "GUID_ESTADO", # primary key da tabela de busca
"displayFieldName": "UF" # coluna do banco de dados que deseja buscar o dados
},
```
#### Display Format
```bash=
"displayFormat": "",
```
#### Mask
- O campo `Mask` funciona como uma `máscara para o input`, por exemplo, em um campo para o usuário preencher o seu CPF, podemos utilizar o campo Mask assim:
```bash=
"mask": "999.999.999-99",
```
#### DisplayLine e DisplaySize
- Os campo de `DisplayLine` e `DisplaySize` definem o `posicionamento` e o `tamanho do campo` na tela de `popup`, com o nome já autoexplicativo, o DisplayLine define qual linha o campo estará, e o DisplaySize qual será o tamanho em %, no exemplo abaixo, o campo 'Nome' pertencerá a primeira linha e ocupará 50% do espaço:
```bash=
"displayLine": "1",
"displaySize": "50",
```
#### Codigo Sequencial Emp
```bash=
"codigoSequencialEmp": false,
```
#### Relatorio Visible
```bash=
"relatorioVisible": false,
```
#### Relation Syze
```bash=
"relatorioSyze": "",
```
#### Required For Cad
- O campo `RequiredForCad` recebe um `booleano` que define se o input terá as `bordas vermelhas` para indicar que o campo é obrigatório ou não, ex:
```bash=
"requiredForCad": true,
```
```bash=
"requiredForCad": false,
```
- Caso o campo `'Obrigatorio'` seja definido como `“true”`, o input receberá as bordas vermelhas independentemente do valor atribuído ao campo de RequiredForCad.
#### Cad Params
```bash=
"cadParams": [],
```
#### Validacao
```bash=
"validacao": "",
```
#### Ignore Case Sensitive
- Campo para `manipular` se o valor recebido será `sensível a maiúsculas e minúsculas`.
```bash=
"ignoreCaseSensitive": false,
```
#### Read Only
- O campo `ReadOnly` recebe um `booleano` que define se o campo poderá ser `preenchido` ou não, por ex:
```bash=
"readonly": true
```
## Menu Itens
O `Menu Itens` é um `arquivo` que `organiza` a maneira como os `itens do menu` serão `exibidos`, ele fica no seguinte caminho:
- 📂 public
- 📂 app
- 📄 menu-itens.js
Por padrão, o menu itens recebe uma variável chamada `'CONST_MENU'` que recebe um array de objetos, por ex:
```bash=
var CONST_MENU = [
{
caption: "Pessoas", # nome do item da aba
icon: "fas fa-users", # icone da aba
subitens: [ # recebe um array de objetos que defines os subitens
{
caption: "Clientes", # nome do subitem
onClick: `openSearchForTable('CLIENTES')`, # função que recebe o nome do dicionario desejado
},
{
caption: "Vendedores",
onClick: `openSearchForTable('VENDEDORES')`,
},
],
},
{
caption: "Veículos",
icon: "fas fa-car",
onClick: `openSearchForTable('VEICULOS')`,
},
]
```
___
## Pop-Ups
### Organização do pop-up
Existe uma `organização padrão` para a distribuição de `scripts auxiliares` no framework, e os arquivos que guardam os pop-ups são acessados através do seguinte caminho:
- 📂 public
- 📂 app
- 📂 dialogs
- 📄 moduloX-TituloY.js
- 📄 moduloY-TituloX.js
Por padrão também esses arquivos são nomeados da seguinte forma:
O módulo do qual o seu contexto pertence. O título que melhor se encaixa em seu contexto.
- Em um único arquivo, é possível incluir vários pop-ups.
- Para disponibilizar um pop-up é necessário anexar seu o caminho do seu arquivo na lista de scripts do sistema no arquivo **index.html**
- Além disso, também é necessário associar o identificador da função do pop-up no arquivo **menu.itens.js**
### Escopo do pop-up
Para criar o `pop-up`, é necessário atribuí-lo a uma `função específica`. E dentro dessa função é chamado o componente `InputDialogMessage` com o método `Message` que espera receber os seguintes parâmetros(respectivamente):
- Título;
- Subtítulo ou mensagem;
- Lista dos campos (array);
- Função callback que retorna o resultado do pop-up, isto é se ele foi cancelado ou confirmado, no caso de confirmado ele também retorna os dados capturados pelos campos.
- Função callback que retorna os dados capturados pelos campos no caso de uma confirmação.
### Campos do pop-up
Cada campo do pop-up é composto de um objeto que possui os seguintes atributos:
- **nome**: Identificador daquele campo;
- **caption**: Texto que será visível ao usuário como título do campo;
- **tipo**: Serve para dar a forma ao campo podendo assumir as formas: string, numeric e date;
- **hint**: Texto que fica visível dentro do campo como uma forma de dica para o usuário;
- **mask**: Modo pelo qual o conteúdo a ser inserido no campo se comportará;
- **obrigatorio**: Define se é obrigatório que o usuário entre com algum dado;
- **component**: Atributo especial que recebe um objeto com os seguintes atributos:
- **nome**: Defina qual o tipo de component ele vai assumir a forma, podendo ser:
- **TComboBox**: Drop Down comum;
- **TLookupComboBox**: Drop Down que busca dados do banco;
- **TPopupComboBox**: Abre um novo pop-up para que seja feito uma busca minuciosa sobre algum dado;
- **items**(somente no caso da nome ser TComboBox): lista (array) das opções que devem ser visíveis ao usuário;
- **dataSource**: Nome da tabela do banco de dados que se deseja buscar os dados;
- **valueFieldName**: Nome do atributo na tabela do banco de dados que se deseja buscar os dados;
- **displayFieldName**: Nome do atributo na tabela do banco de dados que se deseja representar os dados buscados.
### Exemplos de pop-up
- Exemplo de texto simples
- Exemplo de texto com máscara
- Exemplo de campo númerico
- Exemplo de campo com **TComboBox**
- Exemplo de campo com **TPopupComboBox**
- Exemplo de campo com **TLookupComboBox**
Google Drive
Gist
Clipboard
Sign in with Wallet
