The Tour Module - Crie seu próprio tour para um tema personalizado no Drupal 9

Publicados: 2021-09-28

O que pode ser melhor do que uma visita guiada quando você está em um lugar desconhecido?

A experiência do usuário está lentamente se transformando no ponto focal de todos os negócios. Oferecer uma experiência que ajude a direcionar seu usuário para a direção certa por meio de interações na interface do usuário pode ser um divisor de águas para qualquer negócio. Neste artigo, vamos explorar o módulo Tour para o Drupal 9. Com o módulo Tour, você pode não apenas fazer um tour guiado pré-construído de uma visualização existente, mas também integrar o módulo Tour em seu tema personalizado (que será explicado em detalhes mais tarde).

Módulo de passeio

O módulo de turismo Drupal 9

Você gostaria de implementar o módulo Drupal 9 Tour quando quiser que seu usuário se concentre mais em determinados componentes do seu site que passam despercebidos facilmente. Também é ótimo quando você deseja levar seu usuário por um fluxo de trabalho guiado. O módulo Tour está incluído no núcleo do Drupal desde o Drupal 8.

Ao ativar o módulo, ele oferece visitas guiadas à interface do site com a ajuda de dicas de ferramentas. Para fazer um Tour, você pode editar uma Visualização existente em

 /admin/structure/views

e clique no link "? Tour" no canto superior direito da barra de ferramentas do administrador. Você também pode visitar

 /admin/structure/views/view/frontpage?tour=1

para iniciar automaticamente o tour de Visualizações.

Visualizar configuração

No Drupal 8, o módulo Tour é construído no plugin Joyride jQuery, que está obsoleto no Drupal 9.2 com Shepherd.js.

Temos outro método para adicionar um tour por módulos e interface de administração por meio do arquivo YML. Aqui, estou adicionando um tour em um tema personalizado.

O que é Shepherd.js?

Shepherd é uma biblioteca JavaScript que permite criar facilmente visitas guiadas ao seu aplicativo ou site. Ele aproveita o Popper.js, outra biblioteca de código aberto, para renderizar diálogos para cada "etapa" do passeio.

Integrando o módulo Tour em um tema personalizado

No Drupal 9, temos vários tipos de páginas de conteúdo para integrar:

  1. Visita à página
  2. Tour do nó
  3. Veja o passeio etc.

Vamos supor que temos uma página de painel com vários cartões para mostrar todos os gráficos e valores, como na imagem mostrada abaixo. Aqui, o tour facilitará a orientação dos usuários pelos cartões e mostrará alguns detalhes.

Design do painel

Créditos da imagem: Design do painel

Criando uma biblioteca de tour do painel

Requisitos do passeio:

Uma visita guiada necessária para os itens/cartões abaixo

  1. Atividade física
  2. Novos cursos
  3. Crie um novo
  4. Hoje Ganho
  5. Membro ativo
  6. Revisão mensal
  7. Pontos
  8. Pague agora (botão de ação)

Agora, temos um total de 8 etapas. Neste exemplo, criarei algumas etapas para começar e o mesmo padrão será continuado para o restante dos cartões.

Vamos começar.

Etapa 1: crie uma biblioteca de tours em THEME.libraries.yml

Estou criando uma biblioteca personalizada para um tour do painel, para que possamos incluir isso na página/modelo do painel. ou seja, painel.html.twig

Bibliotecas temáticas

TEMA.bibliotecas.yml

Etapa 2: incluir a biblioteca de tour do painel na página de painel personalizada ou no modelo de nó

 {# In a Twig template we attach the library. #}
 {{ attach_library('THEME/dashboard-tour') }}​

Agora, incluímos as dependências do tour em nosso tema.

Etapa 3: primeiros passos com Shepherd.js

Para um início rápido, você pode obter um código de exemplo aqui https://shepherdjs.dev/

Inicializando Pastor

No dashboard.js, adicione o código de inicialização conforme abaixo

 const tour = new Shepherd.Tour({ defaultStepOptions: { cancelIcon: { enabled: true }, classes: 'shadow-md bg-purple-dark', scrollTo: { behavior: 'smooth', block: 'center' } }, useModalOverlay: true, });

painel.js

A opção defaultStepOptions permite especificar qualquer opção que deve ser aplicada a todas as etapas deste tour por padrão.

useModalOverlay é outra opção que você pode adicionar. Você pode conferir mais opções de passeios aqui.

Criando etapas de introdução

 tour.addStep({ id: 'introduction', text: 'Welcome to Our Dashboard', classes: 'example-step-extra-class', buttons: [ { classes: 'btn btn-primary', text: 'Next', action: tour.next } ] });​

painel.js

Este é um pop-up de tour de boas-vindas, portanto, não estamos atribuindo nenhum destino de elemento (como uma classe ou id). Isso aparecerá como um pop-up de mensagem de boas-vindas no centro da página.

Temos mais métodos de tour que se aprofundarão na próxima etapa.

Criando a segunda etapa - atividade de condicionamento físico

 tour.addStep( { id: 'activity', text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse potenti.', attachTo: { element: '.class-activity', on: 'bottom' }, classes: 'example-step-extra-class', buttons: [ { action() { return this.back(); }, classes: 'btn btn-primary', text: 'Back' }, { action() { return this.next(); }, classes: 'btn btn-primary', text: 'Next' } ] });

Tour Fornece muitos métodos. Vamos um pouco mais longe em algumas OPÇÕES DE PASSOS básicas

  • id: A string a ser usada como id para a etapa. Se um id não for passado, um será gerado.
  • text: O texto no corpo da etapa. Pode ser um dos três tipos:

◦ Cadeia HTML
◦ Objeto HTMLElement
◦ Função a ser executada quando a etapa for construída. Ele deve retornar uma das duas opções acima.

  • title: o título da etapa. Torna-se um h3 no topo da etapa.
  • attachTo: O elemento ao qual a etapa deve ser anexada na página. Um objeto com elemento de propriedades e ligado.

◦ elemento: Uma string seletora de elemento ou um elemento DOM.
◦ ligado: A direção opcional para colocar a dica de ferramenta Popper em relação ao elemento.

  • Valores de string possíveis: 'auto', 'auto-start', 'auto-end', 'top', 'top-start', 'top-end', 'bottom', 'bottom-start', 'bottom-end ', 'direita', 'começo direito', 'extremo direito', 'esquerdo', 'início esquerdo', 'extremo esquerdo'
Anexar a

Se você não especificar um attachTo , o elemento aparecerá no meio da tela.

  • cancelIcon Opções para o ícone de cancelamento

◦ ativado Deve ser mostrado um “✕” de cancelamento no cabeçalho da etapa?
◦ label O rótulo a ser adicionado para aria-label

  • classes: Uma sequência de classes extras para adicionar ao elemento de conteúdo da etapa.
  • botões: uma matriz de botões para adicionar à etapa. Eles serão renderizados em um rodapé abaixo do corpo do texto principal. Cada botão no array é um objeto do formato:

◦ texto: O texto HTML do botão
◦ classes: aulas extras para aplicar no <a>
◦ ação: Uma função executada quando o botão é clicado. Ele é automaticamente vinculado ao passeio ao qual a etapa está associada, portanto, coisas como this.next funcionarão dentro da ação.

Este Próximo

Criando a Terceira Etapa: Novos Cursos

Para manter este artigo curto, não estou adicionando as etapas adicionais aqui. Podemos seguir as etapas acima, para criar quantas etapas forem necessárias aqui. Depois de criar todas as etapas, finalmente iniciaremos o passeio.

Para iniciar o tour, basta chamar start na sua instância do Tour:

 tour.start();

Felicidades!! Agora adicionamos um tour para o painel.

Nota: Percorra e siga todos os métodos, eventos e opções disponíveis para obter um Shepherd Tour mais interativo.