Documentação — Implementação de Tutoriais no Core

Introdução

O sistema permite a criação de tutoriais interativos que guiam o usuário pelas telas do Core.
Esses tutoriais são registrados em banco de dados e exibidos automaticamente quando o usuário acessa uma página que possui um tutorial disponível.

Estrutura de Dados

Para criar um novo tutorial, deve ser inserido um registro na tabela nfs_tours com as seguintes colunas:

Campo	Descrição
`DESCRIPTION`	Breve descrição do tutorial.
`TITLE`	Nome do tutorial exibido ao usuário.
`URL`	Caminho relativo da rota onde o tutorial será executado (exemplo: `/transport/diario`).
`STEPS`	Array contendo os passos (steps) do tutorial, em formato JSON.
`ACTIVE`	Define se o tutorial está ativo (`true` ou `false`).

Estrutura dos STEPS

O campo STEPS deve conter um array de objetos JSON, onde cada objeto representa um passo do tutorial.

Exemplo

[
  {
    "element": "#corporate > div > div > div:nth-child(3) > div:nth-child(1) > div:nth-child(1)",
    "popover": {
      "title": "Lista de recentes",
      "description": "Aqui você pode ver a lista de salas que você entrou recentemente.",
      "side": "left",
      "align": "start"
    }
  },
  {
    "element": "#corporate > div > div > div.btn-logout > button:nth-child(1)",
    "popover": {
      "title": "Logout",
      "description": "Aqui você pode sair do sistema.",
      "side": "left",
      "align": "start"
    }
  },
  {
    "popover": {
      "title": "Fim do tutorial",
      "description": "E isso é tudo, agora você pode começar a adicionar tours ao seu aplicativo."
    }
  }
]

Propriedades de cada Step

Cada objeto dentro do array STEPS pode conter as seguintes propriedades:

Propriedade	Tipo	Obrigatório	Descrição
`element`	String	Não	Seletor CSS do elemento a ser destacado.
`popover`	Object	Sim	Objeto contendo as informações do popover.
`popover.title`	String	Sim	Título exibido no popover.
`popover.description`	String	Sim	Texto explicativo do passo.
`popover.side`	String	Não	Posição do popover (`top`, `bottom`, `left`, `right`).
`popover.align`	String	Não	Alinhamento do popover (`start`, `center`, `end`).

Nota: Steps sem a propriedade element são exibidos no centro da tela, úteis para mensagens introdutórias ou finais.

Exemplo de Step

Obtendo o `element` (Seletor CSS)

O campo element indica o componente HTML que será destacado em cada etapa do tutorial.
Para identificar corretamente o seletor de um elemento, siga os passos abaixo:

Abra a página desejada no navegador.
Clique com o botão direito sobre o elemento que deseja destacar.
Escolha a opção “Inspecionar” (Inspect).
No painel do DevTools, clique com o botão direito sobre a tag correspondente ao elemento.
Selecione “Copiar → Copiar seletor” (Copy → Copy selector).
Cole o seletor copiado no campo "element" dentro do passo do tutorial.

Dica: prefira seletores estáveis (como id ou classes fixas) em vez de seletores muito longos com nth-child, que podem mudar com alterações na interface.

Cada popover define o conteúdo textual e o posicionamento da explicação que será exibida durante o tutorial.

Campo	Descrição
`title`	Define o título do passo exibido ao usuário.
`description`	Texto explicativo sobre o elemento destacado.
`side`	Posição do popover em relação ao elemento.
`align`	Alinhamento do popover dentro da posição definida.

Opções de `side`

top → Exibe o popover acima do elemento.
bottom → Exibe o popover abaixo do elemento.
left → Exibe o popover à esquerda do elemento.
right → Exibe o popover à direita do elemento.

Opções de `align`

start → Alinha o popover ao início do elemento.
center → Centraliza o popover em relação ao elemento.
end → Alinha o popover ao final do elemento.

Indicador de Tutoriais Pendentes

Quando há tutoriais disponíveis para uma página, um ícone de interrogação (?) é exibido no header do Core.

Se o usuário ainda não executou o tutorial da página, o ícone aparecerá amarelo.
Após a conclusão do tutorial, o ícone retorna à cor padrão, indicando que não há pendências.

✅ Resumo do Processo

Criar um registro na tabela nfs_tours.
Preencher os campos DESCRIPTION, TITLE, URL, ACTIVE e STEPS.
Obter os seletores dos elementos via DevTools e inseri-los em element.
Definir corretamente side e align no popover.
Verificar o ícone de interrogação no header para identificar tutoriais pendentes.

Simova Docs