Navegação da app

Os ecrãs são as páginas; a navegação é o que leva as pessoas até elas. No Keplin ela não vive dentro de nenhum ecrã: é um documento próprio da app, desenhado num editor visual e servido à volta de qualquer ecrã que esteja aberto.

E é desenhado por dispositivo: a barra de topo do computador, a gaveta do telemóvel e a barra de acções do tablet são três desenhos independentes, cada um com os seus menus.

#Abrir o editor

Na barra lateral da app, separador UI, o primeiro item chama-se Navegação. Clica e abre num separador do espaço de trabalho.

O que se vê ao centro não é um formulário: é a página da app, desenhada como vai ficar. A barra em cima, o conteúdo do ecrã em baixo (Conteúdo do ecrã), a marca à esquerda. Editas mexendo nela.

Por baixo do título estão os controlos que mandam no que estás a ver:

Controlo	O que faz
Web (1280px) / Tablet (768px) / Mobile (390px)	Escolhe o dispositivo que estás a desenhar.
Modo (só tablet e telemóvel)	A forma da navegação nesse dispositivo.
Menu inicial	Qual dos menus abre quando alguém entra na app.

#Os gestos

Gesto	O que acontece
Clique num menu	Selecciona-o (e, num contexto, mostra a barra lateral dele).
Duplo clique num menu	Abre o modal Item seleccionado, onde se edita tudo.
Arrastar um menu	Move-o de zona ou reordena-o. Só larga onde é válido.
+	Acrescenta um menu naquele sítio.
× no canto de um menu	Remove-o.
Clique na marca	Abre o modal Logo da app.

#Os tipos de menu

O botão + de cada zona mostra os tipos que aquele sítio aceita:

Tipo	O que é
Menu	Leva a um ecrã da app. É o item normal.
Submenu	Agrupa outros menus — na gaveta e nas barras laterais.
Contexto (sidebar)	Um menu que, quando escolhido, activa uma barra lateral própria com os seus filhos. É como se dividisse a app em áreas.
Separador	Uma linha divisória.
Menu do utilizador	O avatar de quem está a usar, com as suas entradas e o Sair.
Notificações	O sino, com a contagem automática de não lidas.
Idioma	O selector de idioma: as línguas da app, cada uma no seu próprio nome.
Área de widgets	Um ecrã de barra desenhado dentro da barra: uma lista para escolher a empresa, um resumo, uma pesquisa.

Nem todos os tipos servem em todos os sítios, e o editor só oferece os válidos: um contexto não pode conter outro contexto, um submenu só leva itens, o menu do utilizador só leva itens, separadores e o idioma, e a gaveta do telemóvel não tem contextos (usa submenus).

#As zonas da barra

Na barra de topo, os menus arrumam-se em três zonas, e a dica no editor diz o essencial: Arrasta os menus entre as zonas da barra (esquerda / centro / direita) para criares grupos.

Zona	Uso habitual
Grupo à esquerda	A navegação principal, a seguir à marca.
Grupo ao centro	Um grupo destacado. Se ficar vazia, não ocupa espaço.
Grupo à direita	O menu do utilizador, o sino, atalhos.

Dentro da barra lateral de um contexto — e na gaveta — as zonas são duas: Grupo do topo e Fundo (esta cola-se ao fundo, para "Definições" e "Ajuda" ficarem onde se espera).

#Criar um menu

1. Escolhe o dispositivo na barra de contexto.
2. Clica no + da zona onde o queres.
3. Escolhe o tipo.
4. O menu nasce com um nome genérico e fica seleccionado — faz-lhe duplo clique para abrir o modal Item seleccionado.
5. Preenche:

Campo	O que é
Ícone	Um ícone da biblioteca ou um SVG dos assets da app.
Nome do menu	O texto que aparece. É uma frase da app — entra nas traduções.
Ecrã…	O ecrã de destino (só em Menu).
(parâmetros)	Se o ecrã de destino tem parâmetros de rota, aparece um campo por parâmetro para lhe dares um valor fixo.
Só ícone (o nome fica em tooltip)	Deixa apenas o ícone na barra.

6. Fecha com Concluído e grava com Gravar.

O botão Eliminar item, no mesmo modal, apaga o menu.

#Contextos e barras laterais

Um Contexto (sidebar) é a forma de dar a uma área da app um menu próprio: escolhes "Vendas" na barra de topo e aparece à esquerda a barra lateral com os ecrãs de vendas. Os filhos do contexto são os itens dessa barra.

No modal do contexto, a secção Sidebar deste contexto afina-a:

Campo	Opções
Comportamento	Fixa (sempre aberta) · Retráctil (botão colapsa para ícones) · Mini (ícones; expande ao passar o rato) · Mini com painel (hover abre a árvore do menu)
Largura	Entre 180 e 400 píxeis.
Ao expandir (só no modo mini)	Sobrepõe o conteúdo ou Empurra o conteúdo.
Começa colapsada (só no modo retráctil)	Como abre da primeira vez.

A barra lateral fica aberta enquanto se navega na área, incluindo as páginas que não estão em nenhum menu (um detalhe aberto a partir de uma lista), e também depois de recarregar a página. Um ecrã de outro contexto troca-a, e um item da barra de topo sem contexto fecha-a. Para uma página de detalhe acender o menu certo mesmo num link directo, escolhe o Ecrã pai nas propriedades do ecrã, na categoria Navegação.

#O menu do utilizador

O Menu do utilizador é um item como os outros: pode estar na barra de topo, dentro de um contexto, na gaveta ou na barra compacta. Seleccioná-lo abre o seu popup, e é aí que se acrescentam entradas com o + (Menu, Separador ou Idioma).

No modal ficam as opções que não são visuais:

Opção	O que faz
Mostrar o nome	O nome de quem está a usar aparece no cabeçalho do menu.
Mostrar o utilizador (login)	Também o nome de utilizador.
Opção «Sair»	Inclui a saída no fim do menu.
Texto do «Sair»	Um texto próprio; vazio usa O do sistema (traduzido).

Sem ícone, o avatar mostra as iniciais do nome — e é isso que o selector de ícone chama Sem ícone (iniciais).

#Notificações

O item Notificações é o sino: só ícone, com a pill das não lidas a actualizar-se sozinha. O clique abre as últimas notificações e o Ver mais abre o painel com todas. No modal, Notificações na dropdown decide quantas aparecem de cada vez (entre 1 e 20).

#Idioma

O item Idioma é o selector de idioma. Mostra as línguas da app, definidas na secção Traduções das definições, cada uma no seu próprio nome («Português», «English»), para quem não percebe a língua actual encontrar a sua. Escolher uma língua troca os textos da app sem recarregar a página, e a escolha fica guardada no aparelho.

Pode estar na barra de topo, numa barra lateral, na gaveta, na barra compacta e na barra de acções. Dentro do Menu do utilizador, aparece como a entrada «Idioma · Português», que abre a lista ali mesmo. No modal, Mostrar a língua em uso decide o que o botão mostra: Nome (Português) ou Código (PT).

Numa app com uma só língua, o selector não aparece.

Na primeira visita, antes de alguém escolher, a app abre na língua do browser ou do telemóvel, se a app a tiver; senão, na língua base. Um ecrã sem menus, como o de login, pode oferecer a escolha com um botão que chame keplin.i18n.setLocale.

#Áreas de widgets

Uma Área de widgets põe widgets numa barra: uma lista para escolher a empresa na barra de topo, ou um resumo no fundo da barra lateral de um contexto. O conteúdo da área é um ecrã da app, desenhado no designer como qualquer outro, com a apresentação Barra (área de widgets).

Para criar uma área de widgets:

1. Na secção Ecrãs, cria um ecrã.
2. Nas propriedades do ecrã, na categoria Apresentação, escolhe Barra (área de widgets) em Modo.
3. Em Largura (px) e Altura (px), define o tamanho da área. Por omissão, tem 320 por 48 píxeis.
4. Desenha os widgets.
5. Na Navegação, clica no + da zona onde queres a área e escolhe Área de widgets.
6. Faz duplo clique no item e, em Ecrã da área, escolhe o ecrã de barra.
7. Clica em Gravar.

A zona do item decide onde a área aparece e com que tamanho:

Onde está o item	Onde aparece a área
Grupo à esquerda, Grupo ao centro ou Grupo à direita da barra de topo	Na barra de topo, com a largura e a altura do ecrã.
Grupo do topo ou Fundo da barra lateral de um contexto	Na barra lateral, com a largura da barra e a altura do ecrã.
Gaveta	Na gaveta, com a largura da gaveta e a altura do ecrã.
Header	Ao lado da marca, com a largura e a altura do ecrã.

A área não entra na barra de acções nem no menu do utilizador. Numa barra lateral recolhida em ícones, não aparece.

A área fica aberta enquanto se navega: os dados carregam uma vez e a escolha feita não se perde ao mudar de página. No KeplinGo, a área funciona da mesma forma no header e na gaveta.

#Ligar a área às páginas

A área e as páginas comunicam pelo estado da app: valores com nome, os mesmos em todos os ecrãs. Por exemplo, para uma lista na barra de topo filtrar as páginas pela empresa escolhida:

1. Na lista da área, em Ligação a dados, escolhe Estado e escreve a Chave empresa.
2. Nas páginas, num filtro do datastore, escolhe a origem Estado e escreve a mesma chave. A lista volta a ler os dados quando a escolha muda.
3. Para mostrar o valor, liga uma Etiqueta à mesma chave.

O código dos eventos lê e escreve os mesmos valores com keplin.state.

#Altura da barra

A barra de topo tem 48 píxeis por omissão. Para caber uma área mais alta, muda Altura da barra, nos controlos por baixo do título do editor, para um valor entre 40 e 96 píxeis. Cada dispositivo tem a sua altura, e nos modos compactos ela vale para o header.

#Pills de valor

Qualquer menu (excepto separadores e o sino) pode mostrar uma pill com um número vivo — as encomendas por processar ao lado de "Encomendas", os pedidos pendentes ao lado de "Aprovações".

1. No modal do item, liga Mostrar pill com valor.
2. Escolhe a API que traz os dados (Escolher API…).
3. Em Valor, escolhe Contagem (nº de registos) ou Campo do 1º registo — neste caso, indica também o Campo.
4. Esconder com valor vazio ou zero evita a pill a dizer "0".

A pill actualiza-se em tempo real: quando os dados mudam, o número muda — sem ninguém recarregar a página.

#O logo da app

Clica na marca, à esquerda da barra, para abrir o modal Logo da app:

Campo	O que faz
Ícone ou imagem	Escolhe um ícone da biblioteca ou um ficheiro dos assets da app.
Mostrar o nome da app	O nome ao lado da marca.
Enquadramento na barra	Para imagens dos assets (SVG, PNG, JPG, GIF ou WebP): Escala, Largura da caixa, Altura da caixa e o posicionamento arrastando a imagem.
Ajustar à caixa	Repõe escala e posição.
Sem enquadramento	Desliga o enquadramento.

O enquadramento é a resposta ao logo que "não cabe": arrastas e escalas até ficar bem na barra, e o próprio modal garante que o ficheiro fica intacto — o corte é só visual e reversível. A caixa tem 32 píxeis de altura por omissão, numa barra de 48: um logótipo horizontal só cresce se aumentares a Altura da caixa (até 44); a Largura da caixa sozinha deixa espaço vazio à volta de um logo pequeno. Sem enquadramento, a imagem fica numa caixa de 24 píxeis.

A faixa de pré-visualização do modal usa as cores reais da barra da app. Se a barra é escura, o ficheiro do logo tem de ser a versão clara (branca) da marca — o logo a cores da versão em fundo branco desaparece sobre a barra.

A zona do logo pode ter uma cor de fundo diferente do resto da barra de topo: é a cor Fundo da zona do logo, no grupo Navegação do Tema das definições da app. Entre a zona do logo e os menus não há separador; quando as duas cores são diferentes, a mudança de cor é a fronteira. Vale para a barra de topo da web e do tablet; na barra compacta e na gaveta o logo segue a cor da barra.

A zona do logo nunca fica mais estreita do que a marca: com uma barra lateral mini ou recolhida, os menus de topo começam depois da marca, e não por cima dela.

O separador do browser mostra «Nome do ecrã · Nome da app», e só «Nome da app» num ecrã sem nome; na página de entrada mostra «Entrar · Nome da app».

#Menu inicial

Menu inicial, no canto superior direito, decide por onde a app abre. Escolhe-se um dos menus (não um ecrã solto), e é escolhido por dispositivo — o telemóvel pode abrir num painel diferente do computador.

Se um dispositivo não tiver escolha própria, herda a do seguinte (telemóvel → tablet → web); e se não houver nenhuma, a app abre no primeiro menu que leve a um ecrã.

#Um desenho por dispositivo

O Web é sempre uma barra de topo. O tablet e o telemóvel têm um selector Modo:

Modo	Como fica
Barra de topo (só tablet)	Igual ao computador: marca, menus e contextos numa barra.
Menu hambúrguer	Uma barra compacta com o botão ☰, que abre a gaveta com a árvore de menus.
Barra de acções	Uma barra no fundo, estilo aplicação móvel, com até 5 entradas — e sem gaveta.

Nos modos compactos há ainda duas filas próprias:

• O Header — até 4 acções ao lado da marca (o menu do utilizador e o sino vivem bem aqui).
• A Barra de acções — até 5 entradas no fundo, cada uma um Botão ou um Menu de acções.

Quando o limite é atingido, a plataforma diz porquê: A barra de acções já tem 5 itens (máximo). / O header leva no máximo 4 acções.

#Quem vê o quê

O editor desenha; quem decide quem vê cada menu é Definições da app ▸ Permissões, no separador Menus — por papel e por dispositivo.

A regra vale a pena saber: ao contrário dos ecrãs, um menu é visível por omissão. A porta é o ecrã, e essa já está fechada; esconder o menu serve para tirar um grupo inteiro da vista, ou tirar o sino a quem não recebe nada. Esconder um grupo leva os filhos com ele, e um item que aponte para um ecrã inacessível desaparece sozinho.

#Porque não…?

• Porque é que as minhas alterações desapareceram? Não foram gravadas. A navegação tem botão Gravar — e avisa antes de fechares um separador com alterações por gravar.
• Porque não consigo largar o menu onde quero? Aquele sítio não aceita aquele tipo. Os alvos inválidos nem acendem: um contexto dentro de um contexto, um submenu dentro de um menu de utilizador, um separador na barra de topo.
• Porque não vejo os menus no telemóvel? O telemóvel tem árvore própria e pode estar vazia. Escolhe Mobile (390px) e desenha-a.
• Porque desapareceu um menu na app publicada? Ou foi escondido em Definições ▸ Permissões ▸ Menus para aquele papel, ou aponta para um ecrã a que essa pessoa não tem acesso.
• Porque é que o logo aparece cortado? Está com enquadramento. Abre o modal e usa Ajustar à caixa, ou Sem enquadramento.
• Porque é que o logo aparece pequeno, com espaço à volta? A caixa tem 32 píxeis de altura por omissão e um logo horizontal cabe nela com pouca largura. Sobe a Altura da caixa (até 44) em vez da largura.
• Porque não vejo o logo na barra? Se a barra é escura e o ficheiro é a versão a cores para fundo branco, carrega nos Assets a versão branca da marca e escolhe-a no modal.
• Porque é que não consigo mudar o tipo de um menu? Não se muda. Apaga e cria com o tipo certo — é a única operação que a plataforma não te deixa fazer a meio.
• Porque é que a pill mostra sempre 0? Liga Esconder com valor vazio ou zero, ou confirma que a API escolhida devolve mesmo registos.
• Porque é que o meu ecrã não aparece em Ecrã da área? Só aparecem os ecrãs com a apresentação Barra (área de widgets). Muda o Modo na categoria Apresentação das propriedades do ecrã.
• Porque é que a área de widgets não aparece na barra lateral? A barra está recolhida em ícones, e aí a área não cabe. Expande a barra.