Upgrade Your Drupal Skills

We trained 1,000+ Drupal Developers over the last decade.

See Advanced Courses NAH, I know Enough
Sep 28 2021
Sep 28

What can be better than a guided tour when you are at an unfamiliar place?

User experience is slowly turning into the focal point of every business. Offering an experience that helps point your user to the right direction through user interface interactions can be a game-changer for any business. In this article we are going to explore the Tour module for Drupal 9. With the Tour module, you can not only take a guided pre-built tour of an existing view, you can also integrate the Tour module in your custom theme (which we will be explaining in detail later).

Tour Module

The Drupal 9 Tour Module

You would want to implement the Drupal 9 Tour module when you want your user to focus more on certain components on your site that go unnoticed easily. It is also great when you want to take your user through a guided workflow. The Tour module is included in Drupal core since Drupal 8

When you enable the module it offers guided tours of the website interface with the help of tooltips. To take a Tour, you can edit an existing View at 

/admin/structure/views 

and click the "? Tour"-link in the upper right-hand corner in the admin toolbar. You can also visit

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

to auto-start the Views tour.

View Setting

In Drupal 8, the Tour module is built on the Joyride jQuery plugin, which is deprecated in Drupal 9.2 with Shepherd.js.

We have another method to add a tour for modules and admin interface through YML file. Here, I am adding a tour in a custom theme.

What is Shepherd.js?

Shepherd is a JavaScript library that allows you to easily create guided tours of your app or website. It leverages Popper.js, another open source library, to render dialogs for each tour "step".

Integrating Tour module in a Custom Theme

In Drupal 9, we have multiple types of content pages to integrate:

  1. Page Tour
  2. Node Tour
  3. View tour etc.

Let’s take an assumption of having a dashboard page which has multiple cards to show with all graphs and values in it like in the image shown below. Here, the tour will make it easy to guide users through the cards and show some details.

Dashboard Design

Image credits : Dashboard design

Creating a Dashboard Tour Library

Tour requirements:

A guided tour required for below items/cards

  1. Fitness Activity
  2. New Courses
  3. Create New
  4. Today Gain
  5. Active member
  6. Monthly review
  7. Points
  8. Pay Now (Action Button)

Now, we have a total of 8 Steps. In this example, I will create some steps to start with, and the same pattern will be continued for the rest of the cards.

Let’s Start.

Step 1: Create a tour library on THEME.libraries.yml

I am creating a custom library for a dashboard tour, so that we can include this in the dashboard page/template. i.e. dashboard.html.twig

Theme Libraries

THEME.libraries.yml

Step 2: Include dashboard tour library in custom dashboard page or node template

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

Now, we have included the tour dependencies in our theme.

Step 3: Getting started with Shepherd.js

For a quick start, you can get an example code here https://shepherdjs.dev/

Initializing Shepherd

In dashboard.js, add the initializing code as below


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

dashboard.js

The defaultStepOptions option allows you to specify any option which should be applied to all this tour's steps by default.

useModalOverlay is another option you can add. You can check more Tour options here.

Creating Introduction Steps


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

dashboard.js

This is a welcome tour popup, so we are not assigning any element target (like a class or id). This will appear as a welcome message popup in the centre of the page.

We have more tour methods which will delve deeper in the next step.

Creating the second Step - Fitness Activity


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 Provides many methods. Let’s go a little further in some basic STEP OPTIONS

  • id: The string to use as the id for the step. If an id is not passed one will be generated.
  • text: The text in the body of the step. It can be one of three types:

        ◦ HTML string
        ◦ HTMLElement object
        ◦ Function to be executed when the step is built. It must return one of the two options above.

  • title: The step's title. It becomes an h3 at the top of the step.
  • attachTo: The element the step should be attached to on the page. An object with properties element and on.

        ◦ element: An element selector string or a DOM element.
        ◦ on: The optional direction to place the Popper tooltip relative to the element.

  • Possible string values: 'auto', 'auto-start', 'auto-end', 'top', 'top-start', 'top-end', 'bottom', 'bottom-start', 'bottom-end', 'right', 'right-start', 'right-end', 'left', 'left-start', 'left-end'
AttachTo

If you don’t specify an attachTo the element will appear in the middle of the screen. 

  • cancelIcon Options for the cancel icon

        ◦ enabled Should a cancel “✕” be shown in the header of the step?
        ◦ label The label to add for aria-label

  • classes: A string of extra classes to add to the step's content element.
  • buttons: An array of buttons to add to the step. These will be rendered in a footer below the main body text. Each button in the array is an object of the format:

        ◦ text: The HTML text of the button
        ◦ classes: Extra classes to apply to the
        ◦ action: A function executed when the button is clicked on. It is automatically bound to the tour the step is associated with, so things like this.next will work inside the action.

This Next

 

Creating the Third Step : New Courses

To keep this article short, I am not adding the further steps here. We can follow the above steps, to create as many steps required here. After creating all the steps, we will finally start the tour.

To start the tour, just call start on your Tour instance:

 tour.start(); 

Cheers!! We have now added a tour for the dashboard.

Note: Go through and follow all available methods, events and options to get a more interactive Shepherd Tour.

Apr 27 2021
Apr 27

Component-driven theming is becoming widely popular today because of various reasons. The most significant being reusability and portability of components. Pattern lab is a front-end framework that uses an atomic design architecture to implement a component-based design. In this article, we will discuss more about Pattern Lab and how you can enhance your Drupal frontend performance with it.

Pattern Lab

What is Pattern Lab?

Think of Pattern Lab as an application that can help you organize your UI components in a pattern-driven approach. It is basically a static site generator that binds together all the UI components together. Pattern lab uses atomic design to accelerate the process of creating modular designs. It starts out really basic and gets more complex as you move up the ladder.

Pattern Driven Approach

Credit: Pattern Lab

Let’s breakdown these visual building blocks:

Atoms: They are the most basic building blocks of your design. For example, UI elements like buttons, search fields, form elements, labels.

Molecules: They are groups of atoms that work together to perform a particular action. For example, a search navigation that involves a combination of atoms like a search button, a search field and a label.

Organisms: Organisms are molecules and atoms grouped together to define sections of the application. They’re more complex and have more interactions. For example, a header, a footer or a related blog post section.

Templates: Groups of Organisms form Templates. They are placeholders for organisms. For example, a blog page template, login page template or a shopping cart page template.

Pages: When you combine a template with real content, you get a page.

Page Template

Credit: Pattern Lab

Why should you use Pattern Lab?

Patten Lab makes frontend developers work an absolute pleasure. This is because it allows rapid design prototyping with demonstrable interface and interactivity.

It allows developers to maintain code consistency, implement and leverage reusable components and allows multiple developers to work at the same time. All of these benefits help in easy maintenance of the code.

In terms of Drupal, frontend developers can start their work independently without the dependency on Drupal development. We can work faster and with more consistency than ever before.

Patten Lab with Drupal

Integrating Pattern Lab with Drupal has many benefits and can improve and fasten frontend development. Thanks to the Drupal community, we now have a contributed theme Emulsify Drupal that comes with inbuilt the Pattern Lab architecture. This reduces the extra development effort of achieving a Pattern Lab integration.

Creating a Heading atom in Pattern Lab

For a better understanding of implementing Pattern Lab in Drupal, let’s take an example of creating a Heading atom and integrating it in Drupal Twig template.

Heading atom directory

Heading atom directory

In the atom directory we will have 3 required files.

_heading.twig : The heading markup will go in this file
_hading.scss : This is for heading style
heading.yml : This is for static data to be passed in twig

Heading atom Twig

Heading Twig

_heading.twig

In Heading twig, we can add the element markup with all the required attributes as variable. We can pass data from yml file or drupal field data with these variables.

Heading.yml / Heading.json

Heading json

heading.json

This is an example of a json file containing static data for the variable available in the _heading.twig file.

Integrating Heading atom in Drupal template with field values

Here, we will be overriding the page template and integrating it with the heading atom.

Barkit Page

Default bartik page-title.html.twig

Heading atom integrated with Page Title

Pattern Lab Heading atom integrated in page-title.html.twig

Here, in page-title.html.twig, instead of the default H1 element we are importing the heading atom as reusable element and adding Drupal field value to the defined variable in the heading atom - heading_level and heading.

Using the same pattern, we can create engaging Drupal websites using Pattern Lab.

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web