KEPLIN Docs

Navegação da app

O editor de navegação — menus, grupos e contextos, o logo, o menu do utilizador, as pills de valor, e um desenho próprio para web, tablet e telemóvel.

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 editor de Navegação em Web: a barra de topo desenhada tal como aparece na app, com as zonas esquerda, centro e direita.
O editor de Navegação em Web: a barra de topo desenhada tal como aparece na app, com as zonas esquerda, centro e direita.

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.

Atenção

Ao contrário do designer de ecrãs, a navegação não grava sozinha. O botão Gravar, no canto superior direito, fica activo quando há alterações — e a plataforma confirma com Navegação gravada. O separador marca-se como "por gravar" enquanto não carregares.

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:

O + de uma zona: os tipos de menu que a barra de topo aceita — item, contexto com barra lateral, menu do utilizador e notificações.
O + de uma zona: os tipos de menu que a barra de topo aceita — item, contexto com barra lateral, menu do utilizador e notificações.

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.

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).

Nota

Um menu aponta sempre para um ecrã da app — não existe item de "link externo". Para levar alguém para fora, faz um ecrã com o widget Página externa, ou um Link dentro de um ecrã.

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.

As zonas da barra: arrastar um menu entre Grupo à esquerda, Grupo ao centro e Grupo à direita muda onde ele aparece.
As zonas da barra: arrastar um menu entre Grupo à esquerda, Grupo ao centro e Grupo à direita muda onde ele aparece.

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.
  1. 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).

O chip do menu do utilizador seleccionado: o popup mostra o menu tal como sai na app, e o + acrescenta entradas.
O chip do menu do utilizador seleccionado: o popup mostra o menu tal como sai na app, e o + acrescenta entradas.

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.

O desenho de cada zona

Cada zona da navegação pode ser desenhada pelo Keplin, como até aqui, ou por um widget de navegação: um widget programado por ti que desenha a barra à tua maneira. Nas duas formas, os menus são os que configuras neste editor, com a mesma ordem, os mesmos grupos e as mesmas permissões. Só muda quem desenha.

Zona Onde está
Barra de topo No computador, e no tablet com o modo Barra de topo.
Barra lateral A barra lateral de cada contexto.
Header O cabeçalho do tablet e do telemóvel, nos modos Menu hambúrguer e Barra de acções.
Menu hambúrguer A gaveta que o ☰ abre.
Barra de acções A barra no fundo do ecrã, no modo Barra de acções.

Para desenhar uma zona com um widget:

  1. No código do widget, declara as zonas que ele desenha, numa linha própria no topo:

    navigationZones("topbar", "sidebar");
    

    Os nomes das zonas são topbar, sidebar, header, drawer e footer.

  2. Grava o widget.

  3. Na Navegação, escolhe o dispositivo. Nos controlos por baixo do título, escolhe o widget na lista da zona. Para a barra lateral, faz duplo clique no contexto e escolhe o widget em Desenho.

  4. Clica em Gravar.

O widget recebe os menus em ctx.nav, com o nome traduzido, o destino, o que está aceso e as pills, e pede à plataforma as acções, como abrir um menu ou trocar a língua. O menu do utilizador, o idioma e as notificações podem ser desenhados pelo widget, ou ficar com a peça do Keplin, com ctx.nav.mount. A altura da barra, a largura da barra lateral e as cores do tema continuam a ser as da app.

Se o widget falhar ou deixar de declarar a zona, a app desenha essa zona com o Keplin, e nunca fica sem menus.

Altura da barra

A barra de topo tem 48 píxeis por omissão. Para a mudar, escolhe Altura da barra, nos controlos por baixo do título do editor, com 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:

O modal Logo da app: o ícone ou imagem, mostrar o nome e o enquadramento na barra.
O modal Logo da app: o ícone ou imagem, mostrar o nome e o enquadramento na barra.

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».

Dica

O selector escolhe, não faz upload. Carrega primeiro o ficheiro na secção Assets da árvore da app; depois aparece aqui, no separador Assets da app (SVG).

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.

Menu inicial — qual dos menus abre quando alguém entra na app, escolhido por dispositivo.
Menu inicial — qual dos menus abre quando alguém entra na app, escolhido por dispositivo.

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.

A navegação do telemóvel: outro desenho e outro Modo — aqui o menu hambúrguer, com os menus na gaveta.
A navegação do telemóvel: outro desenho e outro Modo — aqui o menu hambúrguer, com os menus na 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.

Nota

Na app publicada, o dispositivo é decidido pela largura da janela: abaixo de 640 px é telemóvel, abaixo de 1024 px é tablet, acima é web. Um telemóvel sem menus desenhados fica sem navegação — desenha os três, ou pelo menos aqueles onde a app vai ser usada.

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 widget não aparece na lista de uma zona? Só aparecem os widgets que declaram essa zona no código, com navigationZones(...). Acrescenta a linha e grava o widget.