Hansel: A Dynamic Breadcrumb Generator for VueJS

In the popular Brother's Grimm fable 'Hansel and Gretel', Hansel had the following advice for his sister upon leaving their grandmother's house,

"Let us drop these bread crumbs, so that together we find our way home, because losing our way would be the most cruel of things."

Losing your way on a journey is indeed unfortunate. But, while traversing the web's digital landscape, there are times when navigation can truly feel like 'the most cruel of things'. This project was designed with one goal in mind - to ensure that visitors to your website do not lose their way. Like Hansel and Gretel, we are laying down a trail of digital breadcrumbs, allowing website visitors to know where they are at all times. And, like Hansel and Gretel, we are taking care to lay breadcrumbs that reflect decisions made along the way.

APPROACH

At its core, the breadcrumb navigation component is broken down into two main features: static routes and dynamic routes.

THE VUE ROUTER

The Vue Router is the fundamental library that allows developers to navigate users through the application. In the Hansel project, we define it in the root path's /router folder as such:

const Router = new VueRouter({
        routes
});

The **routes** parameter defines the *relationship* between components within the application as a JSON structure. The word *relationship* is important here. For example, consider the following routing structure:

{
        path: '/student/:studentKey',
        name: 'Student',
        props: true,
        component: Student,
        meta: {
            requiresAuth: true,
        },
        children: [
            {
                path: '',
                alias: 'details',
                name: 'StudentDetails',
                component: StudentDetails,
                meta: {
                    requiresAuth: true,
                },
            }
        ]
}

In the above example, we are being told that, in order to get information contained in the StudentDetails component, we need to first visit the Student component. In this manner, we can infer the path a visitor took when navigating the website.

STATIC ROUTES

Hansel uses the above observation to determine how breadcrumb navigation is constructed within the app. By nesting a **breadcrumb** array inside of the route's meta object, as illustrated below, we are defining the navigation trail used to get to the active component.

{
        path: '/student',
        name: 'Student',
        props: true,
        component: Student,
        meta: {
            requiresAuth: true,
              breadcrumb: [
                {
                    name: Home,
                    link: { name: Home },
                },
                {
                    name: Student
                    link: { name: Student },
                },
           ],
        },
        children: [
            {
                path: '',
                alias: 'details',
                name: 'StudentDetails',
                component: StudentDetails,
                meta: {
                   requiresAuth: true,
            breadcrumb: [
                {
                    name: Home,
                    link: { name: Home },
                },
                {
                    name: Student
                    link: { name: Student },
                },
                {
                    name: StudentDetails
                    link: { name: StudentDetails},
                },

            ],
                },
            }
        ]
}

Accordingly, the above path would look like this on the UI:

home > student > details

THE BREADCRUMB COMPONENT

In order to pick up the route names and render them as shown above, we are placing the below breadcrumb sub-component in the main layout of the application.

<template>
    <q-card class="no-margin no-padding" flat style="border-radius:0px">
        <q-breadcrumbs :data-cy="datacy" class="q-px-lg q-py-md">
            <template v-slot:separator>
                <q-icon size="1.5em" name="chevron_right" color="primary" />
            </template>
            <q-breadcrumbs-el
                v-for="(crumb, idx) in crumbs"
                :key="idx"
                :label="crumb.name"
                :icon="crumb.icon"
                :to="crumb.link"
                @click="routeTo(idx)"
            />
        </q-breadcrumbs>
    </q-card>
</template>
<script>
export default {
  name: 'breadcrumbs',
  props: {
        datacy: String,
  },
  data () {
    return {
       crumbs: []
    }
  },
  watch: {
    $route: {
            handler() {
                this.updateList();
            },
    },
  },
  methods: {
    routeTo (route) {
      if (this.crumbs[route].link) this.$router.push(this.crumbs[route].link)
    },
    updateList () { this.crumbs = this.$route.meta.breadcrumb }
  },
  mounted() {
    this.updateList()
  },
};
</script>

When the component mounts, it looks at the meta object of the current route and stores a copy of the associated breadcrumb array in memory. Additionally, a route handler is used to update the in-memory crumbs should the user move from the current page.

DYNAMIC ROUTES

The above approach seems straight forward enough. But how do we determine the navigation path when we need to display a breadcrumb that is unknown? For example, it is a common scenario in Vue applications to persist entity names using VueX actions and then access the current entity name from subscribing components elsewhere in the application. Accordingly, continuing with the "students" example, the breadcrumb trail could be any one of the following:

• home > student1245 > details
• home > student5534 > details
• home > student344 > details

In order to support dynamic routes, we need to make a number of changes in our application.

1. Add dynamic keys in the vue router
2. Create a global crumb manager
3. Map the dynamically generated name to the placeholder name ($dynamicKey)
4. Pull the updated $dynamicKey into the breadcrumb component

1. Dynamic Keys

Because the dynamically generated route name, or generally the **key**, is unknown ahead of time, we need to tell the Vue Router to expect 'something' in the future. However, since that 'something' is not known in advance, we will set a placeholder for it called $dynamicKey.

  meta: {
            requiresAuth: true,
            breadcrumb: [
                {
                    name: Home,
                    link: { name: Home },
                },
                {
                    name: Students,
                    link: { name: Students },
                },
                {
                    name: '$dynamicKey',
                },
                {
                    name: details,
                    link: { name: Details },
                },
            ],
        },

We now need to assign the **$dynamicKey** placeholder.

2. The Crumb Manager

Multiple resources are now accessing the in-memory copy of our breadcrumbs. We have potentially many components that are updating the $dynamicKey. And, we have a Breadcrumb.vue component that is building the list that appears on the UI. Accordingly, we need a way to guarantee that a single copy of any given route's breadcrumb list is being modified. To do this, we have created a singleton class to manage our breadcrumbs.

The crumb manager exposes some important operations. The first sets the active route's breadcrumb list to a local crumb instance.

 setCrumb(crumb) {
    this.crumb = JSON.parse(JSON.stringify(crumb));
    this.addVariable(this.varValue, this.varKey);
}

After the local crumb array is assigned, setCrumb invokes the below addVariable method to search for the existence of a locally assigned $dynamicKey key/value pair. If found, it replaces the placeholder.

 addVariable(value, key) {
        this.varValue = value;
        this.varKey = key;
        for (let item of this.crumb) {
            if (item.name === '$' + key) {
                item.name = value;
            }
        }
  }

3. Mapping The Dynamic Key

But where is the **$dynamicKey** key/value pair coming from? The job of the key assignment is the bailiwick of component developers. In most cases, it will be injected during VueX store actions. For example, rendering the student details page, the student name is selected in the container component and state is passed to the rendering view.

 const actions = {
    getCurrentStudent({ commit }, key) {
        return StudentService.fetchSingleStudent(key)
            .then(response => {
                crumbManager.addVariable(
                    response.data.student_name,
                    'dynamicKey'
                );
                commit(SetSingleStudent, response.data);
            })
            .catch(error => {
                throw error;
            });
    },

Before we commit the mutation, we are telling the crumb manager that the current in-memory breadcrumb list will have a mapping between a student name and **$dynamicKey**.

4. The New Breadcrumb Component

Finally, we need to update our Breadcrumb.vue component to import the crumbManager into our existing Breadcrumb.vue component and implement the methods discussed above.

 <template>
    <q-card class="no-margin no-padding" flat style="border-radius:0px">
        <q-breadcrumbs :data-cy="datacy" class="q-px-lg q-py-md">
            <template v-slot:separator>
                <q-icon size="1.5em" name="chevron_right" color="primary" />
            </template>
            <q-breadcrumbs-el
                v-for="(crumb, idx) in crumbs"
                :key="idx"
                :label="crumb.name === '$dynamicKey' ? '' : crumb.name"
                :icon="crumb.icon"
                :to="crumb.link"
                @click="routeTo(idx)"
            />
        </q-breadcrumbs>
    </q-card>
</template>
<script>
import crumbManager from '@/components/CrumbManager';
export default {
    name: 'Breadcrumbs',
    props: {
        datacy: String,
    },
    data() {
        return {
            crumbs: crumbManager.crumb,
        };
    },
    watch: {
        $route: {
            handler() {
                this.updateList();
            },
        },
    },
    methods: {
        routeTo(route) {
            if (
                this.crumbs[route].link &&
                this.$route.name !== this.crumbs[route].link.name
            )
                this.$router.push(this.crumbs[route].link);
        },
        updateList() {
            crumbManager.setCrumb(this.$route.meta.breadcrumb);
            this.crumbs = crumbManager.getCrumb();
        },
    },
    mounted() {
        this.updateList();
    },
};
</script>

The key changes here is to have the crumbManager manage the component's crumbs array and have it set and get the updated list whenever a new route is visited or changed. As discussed above, we are invoking the setCrumb method prior to updating to the local this.crumbs instance in the event of a new $dynamicKey assignment.