Usando o shepherdjs para fazer tours em uma aplicação nuxt (vue.js) (Parte 1)

#shepherdjs #tours #nuxt #portuguese

Como não vi nenhum conteúdo em pt-BR ensinando o básico de shepherdjs, decidi fazer este pequeno tutorial. Neste exemplo irei fazer referência em como usar o shepherdjs junto ao vue.js com nuxt.

Aqui você encontra o repositório do projeto.

Primeiro e antes de mais nada vamos baixar a biblioteca destinada ao vue:
npm install vue-shepherd --save

Você pode usar várias abordagens, aqui irei mostrar como usar o shepherdjs como plugin:

Crie um arquivo chamado shepherd.js na pasta plugins com o seguinte conteúdo:

import Vue from 'vue';
import VueShepherd from 'vue-shepherd';
import 'shepherd.js/dist/css/shepherd.css';
Vue.use(VueShepherd);

E no arquivo nuxt.config.js você deve declarar o plugin da seguinte forma:

  plugins: [
    '@/plugins/shepherd'
  ],

Dentro do componente desejado você pode inicializar um tour e adicionar steps utilizando o ciclo de vida mounted(conforme exemplo que existe no github oficial):

mounted() {
      this.$nextTick(() => {
        const tour = this.$shepherd({
          useModalOverlay: true
        });

        tour.addStep({
          attachTo: { element: this.$el, on: 'top' },
          text: 'Test'
        });

        tour.start();
      });
    }

OK, até aqui tudo certo, tudo legal. Mas caso você esteja tentando usar o shepherdjs, já percebeu que a documentação oficial é bem genérica em relação a customização do comportamento. Então vamos abordar algumas questões chave.

Para fins didáticos, criei um componente simples com um id chamado shepherd-teste, e iremos usar o mesmo para os exemplos abaixo.

O primeiro ponto a ser abordado é o defaultStepOptions, pois nele conseguimos colocar customizações em todos os steps do tour.

Dentro do defaultStepOptionspodemos colocar a opção popperOptions(sim, o shepherdjs usa o popper por debaixo dos panos), que nos permite usar opções do popper. Sendo assim podemos utilizar a opção offsetpara controlar o quanto a seta/arrow fica dentro ou distante do elemento a ser referenciado.

O nosso tour começa a tomar a seguinte cara:

mounted() {
      this.$nextTick(() => {
        const tour = this.$shepherd({
          useModalOverlay: true,
          defaultStepOptions: {
            popperOptions: {
              modifiers: [{ name: 'offset', options: { offset: [0, 50] } }]
            }
          }
        });

        tour.addStep({
          attachTo: { element: '#shepherd-teste', on: 'top' },
          text: 'Test'
        });

        tour.start();
      });
    }

Onde [0, 50], escolhe se a nossa seta (e consequentemente o elemento criado pelo shepherd) estará mais longe ou mais perto do elemento em destaque (referenciado no attachTo). Quanto maior o segundo número, mais distante a seta/elemento estará.

Exemplo com [0, 50]: