DEV Community: Duy Anh Ngac

Adding pagination to Nuxt Blog

Duy Anh Ngac — Thu, 22 Jul 2021 04:16:26 +0000

TL;DR:

Github: https://github.com/duy-a/corner-of-progress
Live: https://cornerofprogress.com/

As I add more posts to a blog, the list is getting longer, and the amount of scrolling is also getting longer. A better solution would be to introduce pagination, displaying a limited number of posts.

Keeping track of page number

There are 2 options available for solving this problem:

Using url query: url/?page=1
Using url params: url/page/${pageNumber}

On the surface they will achieve the desired effect, however, if one digs deeper, an issue will surface. A thing to keep in mind is that the whole blog will be statically generated, which means the first method of using URL queries won't play nicely.

To create a second route a simple folder can be created as below:

-pages
--pages
---_page.vue // or anything else like _pageNumber.vue

With the following structure, a page number can be easily extracted from the URL.

<script>
export default {
  async asyncData({ $content, params }) {
    console.log(params.page) // a page number
  }
}
</script>

Retrieving posts using `limit()` & `skip()`

The second step is to display a limited amount of posts per page. With a nuxt-content it can be achieved simply with limit() & skip()

[pages/pages/_page.vue]

<script>
export default {
  async asyncData({ $content }) {
    const posts = await $content('posts')
      .only(['title', 'description', 'createdAt', 'slug'])
      .sortBy('createdAt', 'desc')
      .skip(5) // number of posts to skip
      .limit(5) // limit the number of posts to display
      .fetch()

    return { posts }
  },
}
</script>

The above will skip the first five posts and will limit to the nuxt five posts, which is great. However, right now, it is hardcoded and nothing will change if we were to navigate to a different page. A very simple logic to update the navigation between pages and return a correct list of posts.

[pages/pages/_page.vue]

<script>
export default {
  async asyncData({ $content, params, $config }) {
    const totalPosts = (await $content('posts').fetch()).length
    const currentPage = params.page ? +params.page : 1 // it is a string, convert to number
    const perPage = $config.perPage
    const lastPage = Math.ceil(totalPosts / perPage)
    const lastPageCount =
      totalPosts % perPage !== 0 ? totalPosts % perPage : totalPosts - perPage

    const skipNumber = () => {
      if (currentPage === 1) {
        return 0
      }
      if (currentPage === lastPage) {
        return totalPosts - lastPageCount
      }

      return (currentPage - 1) * perPage
    }

    const posts = await $content('posts')
      .only(['title', 'description', 'createdAt', 'slug'])
      .sortBy('createdAt', 'desc')
      .skip(skipNumber())
      .limit(perPage)
      .fetch()

    return { posts, totalPosts, currentPage, lastPage }
  },
}
</script>

Displaying a post list

Once the correct posts are retrieved they have to be displayed. A pages/index.vue already have what we want. So I just copied the template. While it can be extracted into a separate component, in this particular case, I don't see myself updating it any time soon.

[pages/pages/_page.vue]

<template>
  <ul class="divide-y divide-gray-300 -mt-10 dark:divide-gray-400">
    <li v-for="post in posts" :key="post.title" class="py-14">
      <AppPostCard :post="post" />
    </li>
  </ul>
</template>

Awesome, now if the URL is updated manually to /pages/1 or /pages/2, the list of posts will change accordingly. Simple navigation between pages can be added.

[pages/pages/_page.vue]

<template>
  <ul class="divide-y divide-gray-300 -mt-10 dark:divide-gray-400">
    <li v-for="post in posts" :key="post.title" class="py-14">
      <AppPostCard :post="post" />
    </li>
    <div class="flex justify-between py-5 text-yellow-500">
      <button
        class="flex space-x-4"
        :class="{ 'text-gray-200': currentPage === 1 }"
        @click="newer()"
      >
        &larr; Newer
      </button>
      <button
        class="flex space-x-4 float-right"
        :class="{ 'text-gray-200': currentPage === lastPage }"
        @click="older()"
      >
        Older &rarr;
      </button>
    </div>
  </ul>
</template>

<script>
export default {
  // retrieving posts
  methods: {
    newer() {
      if (this.currentPage > 1) {
        this.currentPage = this.currentPage - 1
      }

      if (this.currentPage > 1) {
        this.$router.push({ path: `/pages/${this.currentPage}` })
      } else {
        this.$router.push({ path: '/' })
      }
    },
    older() {
      if (this.currentPage < this.lastPage) {
        this.currentPage = this.currentPage + 1
      }

      this.$router.push({ path: `/pages/${this.currentPage}` })
    },
  },
}
</script>

A small note here, is when the page reaches 1 it will navigate to a pages/index.vue view instead of /pages/1 to keep consistency when moving back and forth.

Redirecting from `/pages` route

Right now, if the user where enter a URL /pages it will throw a "Not Found" error. It would be a much better experience if a user is redirected to a home page where the latest posts are..

[pages/pages/index.vue]

<script>
export default {
  middleware({ redirect }) {
    return redirect('301', '/')
  },
}
</script>

Update Home view

While the main purpose of the update, pagination, has been achieved, the blog as a whole is not yet ready from a user experience. Currently, a home page is still displaying all the posts and there is no way for a user to navigate to a different page number from here.

[pages/index.vue]

<template>
  <ul class="divide-y divide-gray-300 -mt-10 dark:divide-gray-400">
    <li v-for="post in posts" :key="post.title" class="py-14">
      <AppPostCard :post="post" />
    </li>
    <div class="flex justify-between py-5 text-yellow-500">
      <button class="flex space-x-4 text-gray-200">&larr; Newer</button>
      <NuxtLink to="/pages/2">
        <button class="flex space-x-4 float-right">Older &rarr;</button>
      </NuxtLink>
    </div>
  </ul>
</template>

<script>
export default {
  async asyncData({ $content }) {
    const posts = await $content('posts')
      .only(['title', 'description', 'createdAt', 'slug'])
      .sortBy('createdAt', 'desc')
      .limit(process.env.PER_PAGE)
      .fetch()

    return { posts }
  },
}
</script>

I am using limit() to retrieve only the latest posts. Another thing to point out is that I have hardcoded the next page, as it will always be page number 2, so nothing fancy is required.

Generating routes

If a nuxt generate command is run now, there will be a few small problems:

Not all posts are being generated
No views for the pages are generated

While an automatic nuxt crawler is amazing for dynamic routes, sometimes there is still a need to provide a list of routes.

[nuxt.config.js]

const createSitemapRoutes = async () => {
  const routes = []
  const { $content } = require('@nuxt/content')
  const posts = await $content('posts').fetch()

  for (const post of posts) {
    routes.push(`/${post.slug}`)
  }

  const totalPosts = posts.length
  const lastPage = Math.ceil(totalPosts / process.env.PER_PAGE)

  for (let i = lastPage; i > 1; i--) {
    routes.push(`/pages/${i}`)
  }

  return routes
}

export default {
  // other configs
  generate: {
    async routes() {
      return await createSitemapRoutes()
    },
  },
}

I already have a method to generate all routes for the posts, so I can simply update it to include the page number routes as well.

Global variable

Throughout the whole blog post, there is a .PER_PAGE variable. It is a simple global variable that will control the number of posts per page.

Like this? Buy me a coffee

Log[4] - Giary - Vuex getter with a parameter

Duy Anh Ngac — Tue, 06 Jul 2021 03:09:54 +0000

TL;DR:

Live demo: https://giary.netlify.app/
Source code: https://github.com/duy-a/giary

Note: a dummy state is provided for visualisation purposes

Despite a busy past week, I had very little time to work on the Giary project, yet I was still determined that at least one feature must be implemented, even if it's the simplest one.

Weekly task structure

I decided the simple feature will be retrieving and displaying weekly tasks of a current week. Like with most data, I start with defining some structure.

src/types/Task.interface.ts

export enum TaskStatus {
  InProgress = "In Progress",
  Completed = "Completed",
  Deleted = "Deleted",
  Rescheduled = "Rescheduled",
}

export default interface Task {
  id?: string;
  title: string;
  status: TaskStatus;
  dueDate: string;
  rescheduledFrom: string;
  rescheduledTo: string;
}

Besides the basic information, I have also included fields rescheduledFrom and rescheduledFrom which will be utilized when a task is, you guessed it, rescheduled. I am also using an enum to make sure all of the tasks will have consistent status values.

Weekly Task state

Before moving on any further, it is a good idea to create some dummy data for better visualization.

src/store/index.ts

export const store = createStore<State>({
  state: {
    goalList: [
      {
        id: "fdde9397-337c-4a75-9641-968c37374a32",
        title: "Hello world",
        dueDate: "31/12/2021",
      },
    ],
    weeklyTasks: [
      {
        goalId: "fdde9397-337c-4a75-9641-968c37374a32",
        tasks: [
          {
            id: "fdde9397-667c-4a75-9641-9685jg373ff3",
            title: "In progress weekly Task 1",
            status: TaskStatus.InProgress,
            dueDate: moment().format("DD/MM/YYYY").toString(),
            rescheduledFrom: "",
            rescheduledTo: "",
          },
        ],
      },
    ],
  },
});

I could have nested weekly tasks inside a goal object, but I don't like a deeply nested object, they make everything harder to keep track of.

Getter with a parameter

As it stands now, the component will have to retrieve a whole weeklyTask array and then retrieve it. This might cause duplication of code, but more importantly, there is no guarantee that the data will be consistent.

And that is exactly what Vuex was designed, and getters in particular. They are what is needed to compute derived state based on store state, for example filtering through a list of items and counting them.

computed: {
  doneTodosCount () {
    return this.$store.state.todos.filter(todo => todo.done).length
  }
}

Based on, the documentation, a getter only receive state as a 1st argument and getters as a 2nd argument. Based on the requirements, I would like to filter a weeklyTask array based on the goalId. In order to do so, a Method-Style Access must be used, which means passing arguments to getters by returning a function

src/store/index.ts

export const store = createStore<State>({
  // ..state
  getters: {
    getWeeklyTasksByGoalId(state: State) {
      return (goalId: string) =>
        state.weeklyTasks.filter((week) => week.goalId == goalId)[0];
    },
  },
  // ... mutations
});

Based on the structure, there can only be one object for one goalId so I can safely return data from the first index of a filtered array.

Using getters in components

In composition api, in order to access getters, a computed variable must be created references to retain reactivity.

src/views/WeeklyPlan.vue

<script lang="ts">
// imports

export default defineComponent({
  setup() {
    const route = useRoute();
    const store = useStore();

    const isPast = ref(false);

    const goalWeeklyTasks = computed(() => store.getters.getWeeklyTasksByGoalId(
      route.params.goalId
    ));

    const weeklyTasksByDueDate = computed(() =>
      goalWeeklyTasks.tasks.filter(
        (task: Task) =>
          task.dueDate === moment().format("DD/MM/YYYY").toString()
      )
    );

    return {
      weeklyTasksByDueDate,
      isPast,
    };
  },
});
</script>

Goal's weekly tasks are retrieved, it can be further filtered down based on the current date with another computed property. Nothing too fancy here.

Displaying weekly tasks

Firsly, a simple update to the AppTaskListItem.vue component, where it will recieve a task object as a prop.

src/components/AppTaskListItem.vue

<template>
  <li class="p-10 border border-gray-200 rounded-md text-left">
    <div
      v-if="state === 'active' || state === 'underReview'"
      class="flex items-center justify-end mb-5"
    >
      <!-- rest of the component -->

      <p class="text-lg font-light">
        {{ task.title }}
      </p>
    </div>
  </li>
</template>

<script lang="ts">
import Task from "@/types/Task.interface";
import { defineComponent, PropType } from "vue";

export default defineComponent({
  props: {
    task: {
      type: Object as PropType<Task>,
      required: true,
    },
  },
});
</script>

And, secondly, clean up a WeeklyPlan.vue template and pass a task data via newly added props.

src/views/WeeklyPlan.vue

<template>
  <BaseLayout>
    <!-- rest of the component -->

    <ul class="mt-5 space-y-8">
      <AppTaskListItem
        v-for="task in weeklyTasksByDueDate"
        :key="task.id"
        :task="task"
      />
    </ul>

    <!-- rest of the component -->
  </BaseLayout>
</template>

Conclusion

There wasn't much done during the past week and I would like to change a few things here and there. However, a little bit of progress is always better than no progress. Also, a lesson learned on how to create a Vuex getter with parameters.

Like this? Buy me a coffee

Log[3] - Giary - CRUD operations with a Vuex state management

Duy Anh Ngac — Mon, 28 Jun 2021 07:02:15 +0000

TLDR:

Live demo: https://giary.netlify.app/
Source code: https://github.com/duy-a/giary

In the previous post, I broke a design into various reusable components. It is time to start the implementation of actual features. Before even starting, I can see that some of the components will be changed a bit in a structure.

Like many Single Page Application, one of the concerns would be data communication between different components. The way the data can go between the components in various ways:

Passing data from Parent to Child via props
Passing data from Child to Parent via a custom event

For a very simple appplication the above solutions should be sufficient, just use props and custom event to do the communication:

Child.vue

<template>
  <div>
    <h1>{{ title }}</h1> // 'Hello World'
    <button @click="$emit('pass', 'foobar')">Pass to parent</button>
  </div>
</template>

<script>
export default {
  props: ['title']
}
</script>

Parent.vue

<tempalte>
  <div>
    <h1>{{ childData }}</h1> // 'foobar' when btn clicked
    <Child title="Hello world" @pass="childData = event"/>
  </div>
</template>

<script>
export default {
  data() {
    return {
      childData: ''
    }
  }
}
</script>

However, this can quickly transform into a maintenance hell if there is a need to pass data in the scenario of Parent -> Child -> Child -> and so on. On top of that, there is no way to share the data between the siblings, it always has to be done via a parent component.

Setting up Vuex

There are two ways to solve the issue of passing the data sibling components:

Event bus
Vuex is a state management pattern + library for Vue.js applications

For a simple app like Giary, both are very much suitable solution, but I will be using Vuex. The reason is very simple.

Vuex serves as a centralized store for all the components in an application, with rules ensuring that the state can only be mutated in a predictable fashion.

During the setup process, I have already installed Vuex, so there is nothing else to do. The main state is configured and located at the src/store/index.ts file. I am using typescript with composition api, so an additional setup is required to utilize the autocompletion and intellisense.

When writing the Vue component in composition API, useStore is used to return the typed store. For useStore to correctly return the typed store, additional configuration is required:

Define the typed InjectionKey.
Provide the typed InjectionKey when installing a store to the Vue app.
Pass the typed InjectionKey to the useStore method.

src/store/index.ts

import { InjectionKey } from 'vue'
import { createStore, useStore as baseUseStore, Store } from 'vuex'

export interface State {
  count: number
}

export const key: InjectionKey<Store<State>> = Symbol()

export const store = createStore<State>({
  state: {
    count: 0
  }
})

// define your own `useStore` composition function
export function useStore () {
  return baseUseStore(key)
}

Above is just a sample example to test if everything is configured correctly. If everything is correctly configure, an autocompletion will be available within a setup() method.

Example.vue

<script>
import { useStore } from "@/store/index";
import { defineComponent } from "vue";

export default defineComponent({
  setup () {
    const store = useStore()

    store.state.count // typed as number
  }
})
</script>

And load the key during the creation of the Vue app.

src/main.ts

import router from "./router";
import { store, key } from "./store";

const app = createApp(App);

app.use(store, key).use(router).mount("#app");

Goal State

Now that the setup for Vuex & Typescript is working properly, it is time to think about the actual state of the application.

The very core of the application is a "Goal" itself, as everything else revolve around it. So it is a very good idea to start with that. It is always a good idea to define a structure or interface for an object to utilize the full potential of the typescript. For all of my interfaces, I usually create a new directory called types.

src/types/Goal.interface.ts

export default interface Goal {
  id?: string;
  title: string;
  dueDate: string;
}

While everything revolves around the "Goal", the structure of the "Goal" itself is very simple, there is nothing much to it.

I like to think of a state in a form of "What do I need for my application right now?" and progress from there. Based on our design, the very first thing is a user should see is a list of goals.

src/store/index.ts

import { InjectionKey } from "vue";
import { createStore, useStore as baseUseStore, Store } from "vuex";
import Goal from "@/types/Goal.interface";

export interface State {
  goalList: Goal[];
}

export const key: InjectionKey<Store<State>> = Symbol();

export const store = createStore<State>({
  state: {
    goalList: [
      {
        id: "e356583f-40fd-4827-96dd-21f556691921",
        title: "Hello World",
        dueDate: "31/12/2021",
      },
    ],
  },
});

export function useStore(): Store<State> {
  return baseUseStore(key);
}

Replacing all the dummy state with our goalList state with sample data, which can be pulled in the component.

Displaying goals

As I mentioned previously, getting a state in a setup() is very simple with useStore. I have removed a dummy variable to toggle a visibility of the AppGoalListItem.vue component.

src/views/Home.vue

<script lang="ts">
import AppGoalForm from "@/components/AppGoalForm.vue";
import AppGoalListItem from "@/components/AppGoalListItem.vue";
import { defineComponent, ref } from "vue";

export default defineComponent({
  components: {
    AppGoalListItem,
    AppGoalForm,
  },
  setup() {
    const store = useStore();
    const { goalList } = store.state;

    return {
      goalList,
    };
  },
});
</script>

While the data has been pulled from a state, in order to display it, an update to a AppGoalListItem.vue must be made.

src/components/AppGoalListItem.vue

<template>
  <li class="p-10 border border-gray-200 rounded-md text-left">
    <div class="flex items-center justify-between mb-5">
      <p class="text-gray-400 text-sm">{{ formatDate(goal.dueDate, "DD/MM/YYYY") }}</p>
      <div class="space-x-2 text-gray-400 -mt-5">
        <button @click.stop="$emit('update')">
          <PencilIcon class="h-5 w-5 hover:text-gray-700" />
        </button>
        <button @click.stop="$emit('delete')">
          <TrashIcon class="h-5 w-5 hover:text-gray-700" />
        </button>
      </div>
    </div>

    <div class="flex items-center">
      <p class="text-lg font-light">
        {{ goal.title }}
      </p>
    </div>
  </li>
</template>

<script lang="ts">
import { defineComponent, PropType } from "vue";
import { PencilIcon, TrashIcon } from "@heroicons/vue/outline";
import Goal from "@/types/Goal.interface";

export default defineComponent({
  components: {
    PencilIcon,
    TrashIcon,
  },
  props: {
    goal: {
      type: Object as PropType<Goal>,
      required: true,
    },
  },`
  emits: ["update", "delete"],
  setup() {
    function formatDate(date: string, format: string): string {
      return moment(date, format, true).format(format);
    }

    return {
      formatDate,
    }
  }
});
</script>

This is simple Parent to Child communication, so props will be sufficient to do the job. I have also added a simple method to format a date with a help of moment.js. Since I am already at AppGoalListItem.vue component, I have also added a few simple "emit" methods as I would like view components to do the communication with Vuex. This way a component can be relatively independent.

With an AppGoalListItem.vue component updated, it is just a matter of passing a data from Home.vue with props.

src/views/Home.vue

<template>
  <BaseLayout>
    <template #header>
      <h1 class="h-title">My Goals</h1>
    </template>

    <p class="text-sm italic text-gray-500">You can have up to 2 goals</p>

    <ul class="mt-5 space-y-8">
      <RouterLink v-slot="{ navigate }" to="/weekly-plan" custom>
        <AppGoalListItem
          v-for="goal in goalList"
          :key="goal.id"
          :goal="goal"
          class="hover:bg-gray-50 cursor-pointer"
          @click="navigate"
        />
      </RouterLink>
    </ul>

  </BaseLayout>
</template>

With the above change, now the list of goals should be displayed properly once again.

Creating a Goal

Creating a goal equals adding a new object to the goalList state. A Vuex state should be changed via mutations. They are rules ensuring that the state can only be mutated predictably.

For a id generation I am using a uuid library.

src/store/index.ts

export const store = createStore<State>({
  state: {
    goalList: [
      {
        id: "e356583f-40fd-4827-96dd-21f556691921",
        title: "Hello World",
        dueDate: "31/12/2021",
      },
    ],
  },
  mutations: {
    addGoal(state: State, goal: Goal): void {
      goal.id = uuidv4();
      state.goalList.push(goal);
    },
  },
});

A mutations itself is very simple, but it is time to update an AppGoalForm.vue component. Similiar to AppGoalListItem.vue, a component will not interact with a state, only a view, so additional events must be emiited.

src/components/AppGoalForm.vue

<template>
  <div>
    <button
      v-if="!isVisibleGoalForm"
      class="py-10 border border-gray-200 rounded-md hover:bg-gray-50 w-full"
      @click="showGoalInput()"
    >
      + Add Goal
    </button>

    <form v-else class="space-y-2" @submit.prevent="submit()">
      <ul>
        <li
          v-for="error in errors"
          :key="error"
          class="list-disc list-inside text-red-500 text-sm"
        >
          {{ error }}
        </li>
      </ul>

      <textarea
        ref="goalTextArea"
        class="px-5 py-2 w-full border border-gray-200 rounded-md resize-none"
        rows="3"
        placeholder="Write down your S.M.A.R.T goal here ..."
        :value="title"
        @input="$emit('update:title', $event.target.value)"
      ></textarea>

      <input
        class="px-5 py-2 w-full border border-gray-200 rounded-md resize-none"
        type="text"
        placeholder="Achieve your goal by dd/mm/yyyy"
        :value="dueDate"
        @input="$emit('update:dueDate', $event.target.value)"
      />

      <div class="flex justify-end space-x-3">
        <button
          type="button"
          class="action-btn border border-gray-200 hover:bg-gray-100"
          @click.stop="hideGoalInput()"
        >
          Cancel
        </button>

        <button
          type="submit"
          class="action-btn bg-green-400 text-white hover:bg-green-500"
        >
          <CubeTransparentIcon
            v-if="isSubmitting"
            class="h-5 w-5 animate-spin"
          />
          <span v-else>Add Goal</span>
        </button>
      </div>
    </form>
  </div>
</template>

<script lang="ts">
import { CubeTransparentIcon } from "@heroicons/vue/outline";
import moment from "moment";
import { defineComponent, nextTick, ref } from "vue";

export default defineComponent({
  components: {
    CubeTransparentIcon,
  },
  props: {
    title: {
      type: String,
      required: true,
    },
    dueDate: {
      type: String,
      required: true,
    },
    isSubmitting: {
      type: Boolean,
      default: false,
    },
  },
  emits: ["update:title", "update:dueDate", "cancel", "submitting"],
  setup(props, { emit }) {
    const goalTextArea = ref(null as unknown as HTMLTextAreaElement);
    const isVisibleGoalForm = ref(false);

    const errors = ref([] as Array<string>);

    function showGoalInput() {
      isVisibleGoalForm.value = !isVisibleGoalForm.value;

      nextTick(() => {
        goalTextArea.value.focus();
      });
    }

    function hideGoalInput() {
      isVisibleGoalForm.value = false;
      emit("cancel");
    }

    function submit(): void {
      errors.value = [];

      if (props.title === "" || props.dueDate === "") {
        errors.value.push("Title & due date canot be empty");
        return;
      }

      if (
        moment(props.dueDate, "DD/MM/YYYY").format("DD/MM/YYYY") !==
        props.dueDate
      ) {
        errors.value.push("Due date must have a dd/mm/yyyy format");
        return;
      }

      emit("submitting");
      isVisibleGoalForm.value = false;
    }

    return {
      goalTextArea,
      isVisibleGoalForm,
      errors,
      showGoalInput,
      hideGoalInput,
      submit,
    };
  },
});
</script>

A simple validation is done here to make a form cannot be empty and a date has a correct format. A big update with a AppGoalForm.vue component is a props can be bind with a v-model from a parent. In layment terms, v-model is a combintation of binding a :value attribute and emit events.

ParentExample.vue

<template>
  <AppGoalForm
      v-model:title="title"
      v-model:dueDate="dueDate"
      class="mt-8"
      @submitting="submit()"
    />
</template>

With AppGoalForm.vue component now requiring a few additional props, it's time to make updates inside a Home.vue, which will provide data to a child component as well as listen to emitted events.

src/views/Home.vue

<template>
  <BaseLayout>
    <!-- the rest of template -->

    <AppGoalForm
      v-if="goalList.length < 2"
      v-model:title="newGoal.title"
      v-model:dueDate="newGoal.dueDate"
      class="mt-8"
      @submitting="addGoal()"
    />
  </BaseLayout>
</template>

<script lang="ts">
// imports

export default defineComponent({
  // components
  setup() {
    const store = useStore();
    const { goalList } = store.state;
    const newGoal = ref({
      title: "",
      dueDate: "",
    } as Goal);

    function addGoal() {
      if (goalList.length < 2) {
        store.commit("addGoal", newGoal.value);
        newGoal.value = {
          title: "",
          dueDate: "",
        } as Goal;
      }
    }

    return {
      // previously added
      addGoal,
    };
  },
});
</script>

Based on the design decision, I have a simple validation to check the number of goals. If there are already 2 goals present, no more goals can be added.

Deleting a Goal

I want to start with a deletion of a goal, since most of the components have already been updated to handle that, and all is left is to add a mutation to the deletion.

src/store/index.ts

export const store = createStore<State>({
  // state
  mutations: {
    // addGoal()
    deleteGoal(state: State, goalId: string): void {
      const index = state.goalList.findIndex((goal) => goal.id === goalId);
      state.goalList.splice(index, 1);
    },
  },
});

With a mutation, it is simple to listen to an emitted delete event and act upon it.

src/views/Home.vue

<template>
  <BaseLayout>
    <template #header>
      <h1 class="h-title">My Goals</h1>
    </template>

    <p class="text-sm italic text-gray-500">You can have up to 2 goals</p>

    <ul class="mt-5 space-y-8">
      <RouterLink v-slot="{ navigate }" to="/weekly-plan" custom>
        <AppGoalListItem
          v-for="goal in goalList"
          :key="goal.id"
          :goal="goal"
          class="hover:bg-gray-50 cursor-pointer"
          @click="navigate"
          @delete="deleteGoal(goal.id)"
        />
      </RouterLink>
    </ul>

  </BaseLayout>
</template>

<script lang="ts">
export default defineComponent({
  components: {
    AppGoalListItem,
  },
  setup() {
    const store = useStore();

    function deleteGoal(goalId: string): void {
      store.commit("deleteGoal", goalId);
    }

    return {
      deleteGoal,
    };
  },
});
</script>

Editing a Goal

I left an editing operation for the last, as this is where I faced a problem. In my initial design, when a user clicks a pencil icon, a form should be displayed. However, based on the current structure of the components a form will be wrapped around a link and a form itself is hidden behind a big trigger button.

I am starting with a state mutations, so keep it out of the way first and make it ready for a later use once a components restucture is completed.

src/store/index.ts

export const store = createStore<State>({
  // state 
  mutations: {
    // add & delete operations
    updateGoal(state: State, goalData: Goal): void {
      const index = state.goalList.findIndex((goal) => goal.id === goalData.id);
      state.goalList.splice(index, 1, goalData);
    },
  },
});

I started with a AppGoalForm.vue components as it is the easiest one to update.

src/components/AppGoalForm.vue

<template>
  <div>
    <button
      v-if="!isVisibleGoalForm && haveTriggerFormBtn"
      class="py-10 border border-gray-200 rounded-md hover:bg-gray-50 w-full"
      @click="showGoalInput()"
    >
      + Add Goal
    </button>

    <form v-else class="space-y-2" @submit.prevent="submit()"
      // form inputs

      <div class="flex justify-end space-x-3">
        // cancel button

        <button
          type="submit"
          class="action-btn bg-green-400 text-white hover:bg-green-500"
        >
          <CubeTransparentIcon
            v-if="isSubmitting"
            class="h-5 w-5 animate-spin"
          />
          <span v-else>{{ submitBtnText }}</span>
        </button>
      </div>
    </form>
  </div>
</template>

<script lang="ts">
// imports

export default defineComponent({
  components: {
    CubeTransparentIcon,
  },
  props: {
    haveTriggerFormBtn: {
      type: Boolean,
      default: true,
    },
    submitBtnText: {
      type: String,
      default: "Add Goal",
    },
  },
  emits: ["update:title", "update:dueDate", "cancel", "submitting"],
});
</script>

I have added additional props to control the state of the form. With a form out of the ways, it is time to update a AppGoalListItem.vue component, to handle a trigger for an edit form.

src/components/AppGoalListItem.vue

<template>
  <div>
    <RouterLink
      v-if="!isEditMode"
      v-slot="{ navigate }"
      :to="navigateTo"
      custom
    >
      <li
        class="p-10 border border-gray-200 rounded-md text-left"
        :class="{ 'hover:bg-gray-50 cursor-pointer': isHoverable }"
        @click="navigate()"
      >
        <div class="flex items-center justify-between mb-5">
          // date
          <div class="space-x-2 text-gray-400 -mt-5">
            <button @click.stop="isEditMode = true">
              <PencilIcon class="h-5 w-5 hover:text-gray-700" />
            </button>
            // delet button
          </div>
        </div>

        // goal title
      </li>
    </RouterLink>

    <AppGoalForm
      v-else
      v-model:title="toUpdateGoal.title"
      v-model:dueDate="toUpdateGoal.dueDate"
      submit-btn-text="Update"
      class="mt-8 p-5 border border-gray-200 rounded-md text-left"
      :have-trigger-form-btn="false"
      @submitting="update()"
      @cancel="cancel()"
    />
  </div>
</template>

<script lang="ts">
// imports

export default defineComponent({
  components: {
    // icon components
    AppGoalForm,
  },
  props: {
    goal: {
      type: Object as PropType<Goal>,
      required: true,
    },
    navigateTo: {
      type: String,
      required: true,
      default: "/",
    },
    isHoverable: {
      type: Boolean,
      default: false,
    },
  },
  emits: ["update", "delete"],
  setup(props, { emit }) {
    function formatDate(date: string, format: string): string {
      return moment(date, format, true).format(format);
    }

    const isEditMode = ref(false);
    const toUpdateGoal = ref({ ...props.goal });
    function update() {
      emit("update", toUpdateGoal.value);
      isEditMode.value = false;
    }

    function cancel() {
      isEditMode.value = false;
      toUpdateGoal.value = { ...props.goal };
    }

    return {
      formatDate,
      isEditMode,
      toUpdateGoal,
      update,
      cancel,
    };
  },
});
</script>

Now the link lives within an AppGoalListItem.vue component, so Home.vue must be updated as well, otherwise, there will be a link wrapped around a link

src/views/Home.vue

<template>
  <BaseLayout>
    // header and title

    <ul class="mt-5 space-y-8">
      <AppGoalListItem
        v-for="goal in goalList"
        :key="goal.id"
        :goal="goal"
        :navigate-to="`/${goal.id}/weekly-plan`"
        :is-hoverable="true"
        @update="updateGoal($event)"
        @delete="deleteGoal(goal.id)"
      />
    </ul>

    // Add goal form
  </BaseLayout>
</template>

<script lang="ts">
// imports

export default defineComponent({
  components: {
    AppGoalListItem,
    AppGoalForm,
  },
  setup() {
    const store = useStore();

    // add & delete operations

    function updateGoal(goal: Goal): void {
      store.commit("updateGoal", goal);
    }

    return {
      updateGoal,
    };
  },
});
</script>

And with this update, every planned operation for a goal is completed.

Conclusion

As I mentioned, Vuex is built to ensure that the state can only be mutated predictably. A very great tool to visualize is a Vue dev tool, which shows how the state changed. On top of that, it is a great tool to visualize & debug a Vue app in general.

From creating simple CRUD operations, it can be seen that there is no 'one size fits all` when talking about component communication. It can be a huge disadvantage if I were to stick to one way only. Just imagine how many states I would need to pass a simple data from Parent to a Child.

A good way of thinking about the state: "Do I need this data everywhere?" If yes, that put it in a state, otherwise, stick to props and events.

Like this? Buy me a coffee

Log[2] - Giary - Breaking down a design into components with Vue & Tailwind CSS

Duy Anh Ngac — Fri, 18 Jun 2021 02:57:25 +0000

Disclaimer: I have omitted a lot of code for some components to keep it short. Where the code is not documented, a link to a repo is provided instead.

TL;DR:

Source code: https://github.com/duy-a/giary
Live demo: https://giary.netlify.app/
As of this moment, the app is just a shell without any features implemented*

With a rough design for the Giary app is completed, it is finally time to open a code editor and start the implementation.

Vue project setup

As I previously decided, I will be using a Vue3 as my front-end framework. A quick and easy way to scaffold a base project is to use Vue CLI, which will help a lot with generating a properly configured template.

Once the Vue CLI is installed globally on the machine, a project can be created with a command:

vue create giary

A list of presets will be prompt for a selection. I went with Manually select features and below is the actual selection and the motivation behind it:

 ◉ Choose Vue version
 ◉ Babel
 ◉ TypeScript
 ◯ Progressive Web App (PWA) Support
 ◉ Router
 ◉ Vuex
 ◯ CSS Pre-processors
 ◉ Linter / Formatter
 ◯ Unit Testing
 ◯ E2E Testing

Vue 3 has first-class citizen support for typescript

? Choose a version of Vue.js that you want to start the project with 
  2.x 
❯ 3.x

Typescript is a static type system that can help prevent many potential runtime errors as applications grow

? Use class-style component syntax? No
? Use Babel alongside TypeScript (required for modern mode, auto-detected polyfills, transpiling JSX)? Yes

A Router is a navigation between pages with a history mode

? Use history mode for a router? (Requires proper server setup for index fallback in production) (Y/n) Y

Vuex is for state management and communication between the components
Linter / Formatter for consistent formatting and to avoid unwanted patterns

? Pick a linter / formatter config: 
  ESLint with error prevention only 
  ESLint + Airbnb config 
  ESLint + Standard config 
❯ ESLint + Prettier 
  TSLint (deprecated) 

? Pick additional lint features: (Press <space> to select, <a> to toggle all, <i> to invert selection)
 ◉ Lint on save

In the future, if requirements for other features occurs (i.e. Progressive Web App (PWA) Support), they all can be easily added with a help of a rich plugin ecosystem.

Like with every project I start, I like to have a 100% clean project, which means removing all of the example code & files:

remove all the routes from src/router/index.ts
remove all the files from src/components
remove all the files from src/views

Installing tailwind CSS & Icon pack

Installing Tailwind CSS came with a small caveat. Following official documentation for installation and compiling a project will result in the following error:

Error: PostCSS plugin tailwindcss requires PostCSS 8.

The error is self-explanatory and Vue 3 does support PostCSS 8 as well. The problem comes from the Vue CLI that doesn’t support PostCSS 8 just yet, so a workaround installation is required:

yarn add -D tailwindcss@npm:@tailwindcss/postcss7-compat postcss@^7 autoprefixer@^9

The compatibility build is identical to the main build in every way, so you aren’t missing out on any features or anything like that.

/Note: A support for PostCSS8 will be available in version 5 which is currently in the beta stage./

After that, setting up Tailwind CSS is identical to the documentation.

For the icons, I use the Heroicons pack, which is from the creators of Tailwind CSS and they are greatly customizable with the same classes as Tailwind CSS.

yard add @heroicons/vue #npm install @heroicons/vue

Now each icon can be imported individually as a Vue component:

<template>
  <div>
    <BeakerIcon class="h-5 w-5 text-blue-500"/>
    <p>...</p>
  </div>
</template>

<script>
import { BeakerIcon } from '@heroicons/vue/solid'

export default {
  components: { BeakerIcon }
}
</script>

/Note: Heroicons currently only supports Vue 3./

Navigation to pages

All the pages will be located in the src/views directory. The very first page a user will see is “My Goals” which will be the home page as well. I usually create a file with simple text to make sure that the page is accessible.

[src/views/Home.vue]

<tempalte>
    <h1>My Goals page</h1>
</template>

To make this page accessible, a vue-router must be mapped with our view which can be added as below:

[src/router/index.ts]

const routes: Array<RouteRecordRaw> = [
  {
    path: "/",
    name: "homeView",
    component: Home,
  },
];

The next step is to tell a vue-router where to display with <RouterView />

[src/App.vue]

<template>
  <RouterView />
</template>

Now the Home.vue page should be accessible via http://localhost:8080/.

Repeatable elements

A very big benefit about prototyping before actually coding a design is all the repeatable elements can be identified and can be extracted straight away.

A principle in extracting components to keep in mind. A component design must be from edge to edge, the spacing of the component, where the component is and how a component is displayed will be controlled by the parent’s components. With this principle, it will be much easier to update the design or swap the components.

[Button.vue]

<template>
    <button class="px-2 py-1 border border-gray-200">Click me</button>
</template>

[Parent.vue]

<template>
    <div class="flex" >
        <Button class="mt-10" />
        <Button class="mr-10" />
    </div>
</template>

Extracting the “Base Layout” component

All of the pages based on the design have one thing in common. That is a Header where the title of the page, navigation & other secondary information lives. And the main part where the dynamic content is displayed. Straight away this can be extracted to a separate component, which can be reused through the application.

[src/components/BaseLayout.vue]

<template>
  <div>
    <header class="h-56 bg-green-400 px-5">
      <div class="relative h-full container mx-auto max-w-screen-md">
        <div class="absolute top-0 w-full flex justify-between pt-3 text-sm">
          <p></p>
          <p>01.01.2021</p>
        </div>

        <div class="flex flex-col h-full items-center justify-center">
          <slot name="header"></slot>
        </div>
      </div>
    </header>

    <main class="mx-auto container max-w-screen-md pt-5 px-5 pb-10">
      <slot></slot>
    </main>
  </div>
</template>

In this component, I am utilizing the named slots, where the actual content will be placed and that content will always stay at the correct place without messing up a whole page layout.

Extracting the “Goal List Item” component

While this element does not appear anywhere except “My Goals” page it is still a great idea to extract it in the event the amount of information displayed grows an can be changed in isolation.

[src/components/AppGoalListItem.vue]

<template>
  <li class="p-10 border border-gray-200 rounded-md text-left">
    <div class="flex items-center justify-between mb-5">
      <p class="text-gray-400 text-sm">31/12/2021</p>
      <div class="space-x-2 text-gray-400 -mt-5">
        <button>
          <PencilIcon class="h-5 w-5 hover:text-gray-700" />
        </button>
        <button>
          <TrashIcon class="h-5 w-5 hover:text-gray-700" />
        </button>
      </div>
    </div>

    <div class="flex items-center">
      <p class="text-lg font-light">
        Lorem ipsum dolor sit amet consectetur adipisicing elit. Porro debitis
        quo nam hic a cupiditate ex illum id. Enim voluptates, est vero possimus
        sunt accusamus corporis recusandae pariatur delectus ipsa?
      </p>
    </div>
  </li>
</template>

<script lang="ts">
import { defineComponent } from "vue";
import { PencilIcon, TrashIcon } from "@heroicons/vue/outline";

export default defineComponent({
  components: { PencilIcon, TrashIcon },
});
</script>

Extracting the “Goal Form” component

Right now both “Goal” & “Task” forms are almost the same having a simple text input. A small difference is a goal has a due date. Technically the same component can be used to display a due date input conditionally. However, I think, a much better approach would be to separate these two forms for few reasons:

The form can be styled differently if required
Add or delete additional fields (if required) to the form without affecting one another
Removing conditional logic to control an input visibility
Simplify the code

[src/components/AppGoalForm.vue]

<template>
  <div>
    <button
      v-if="!isVisibleGoalForm"
      class="py-10 border border-gray-200 rounded-md hover:bg-gray-50 w-full"
      @click="showGoalInput()"
    >
      + Add Goal
    </button>

    <form v-else class="space-y-2" @submit.prevent="submit()">
      <textarea
        ref="goalTextArea"
        class="px-5 py-2 w-full border border-gray-200 rounded-md resize-none"
        rows="3"
        placeholder="Write down your S.M.A.R.T goal here ..."
      ></textarea>

      <input
        class="px-5 py-2 w-full border border-gray-200 rounded-md resize-none"
        type="text"
        placeholder="Achieve my goal by dd/mm/yyyy ..."
      />

      <div class="flex justify-end space-x-3">
        <button
          type="button"
          class="px-4 py-2 rounded-md border border-gray-200 hover:bg-gray-100"
          @click="isVisibleGoalForm = false"
        >
          Cancel
        </button>

        <button
          type="submit"
          class="px-4 py-2 rounded-md bg-green-400 text-white hover:bg-green-500"
        >
          <CubeTransparentIcon
            v-if="isSubmitting"
            class="h-5 w-5 animate-spin"
          />
          <span v-else>Add Goal</span>
        </button>
      </div>
    </form>
  </div>
</template>

<script lang="ts">
import { defineComponent, nextTick, ref } from "vue";
import { CubeTransparentIcon } from "@heroicons/vue/outline";

export default defineComponent({
  components: {
    CubeTransparentIcon,
  },
  emits: ["submitted"],
  setup(_props, { emit }) {
    const goalTextArea = ref(null as unknown as HTMLTextAreaElement);
    const isVisibleGoalForm = ref(false);

    function showGoalInput() {
      isVisibleGoalForm.value = !isVisibleGoalForm.value;

      nextTick(() => {
        goalTextArea.value.focus();
      });
    }

    const isSubmitting = ref(false);

    function submit() {
      isSubmitting.value = true;

      setTimeout(() => {
        emit("submitted");
        isVisibleGoalForm.value = false;
        isSubmitting.value = false;
      }, 500);
    }

    return {
      goalTextArea,
      isVisibleGoalForm,
      showGoalInput,
      isSubmitting,
      submit,
    };
  },
});
</script>

The form is hidden behind a big Add Goal button, and that’s why I added a very simple interaction functionality for better visualization with simple events.

As I am using vue composition-api, the way events are emitted are slightly different from options api. The difference is that you have to indicate what events will be emitted by a component. The emit action itself must be done via context provided to setup()

<script>
export default {
  // Vue 2.x
  methods: {
    click() {
      this.$emit("clicked");
    },
  },

  // Vue 3.x
  emits: ["clicked"],
  setup(_, { emit }) {
    function click() {
      emit("clicked");
    }

    return {
      click,
    };
  },
};
</script>

Assembling “My Goals” page

Most of the components for the “Home” page have been extracted, it becomes very easy to assemble a whole page.

[src/views/Home.vue]

<template>
  <BaseLayout>
    <template #header>
      <h1 class="h-title">My Goals</h1>
    </template>

    <p class="text-sm italic text-gray-500">You can have up to 2 goals</p>

    <ul class="mt-5 space-y-8">
      <RouterLink v-slot="{ navigate }" to="/weekly-plan" custom>
        <AppGoalListItem
          class="hover:bg-gray-50 cursor-pointer"
          @click="navigate"
        />
        <AppGoalListItem
          v-if="isGoalVisible"
          class="hover:bg-gray-50 cursor-pointer"
          @click="navigate"
        />
      </RouterLink>
    </ul>

    <AppGoalForm
      v-if="!isGoalVisible"
      class="mt-8"
      @submitted="isGoalVisible = true"
    />
  </BaseLayout>
</template>

<script lang="ts">
import { defineComponent, ref } from "vue";
import AppGoalListItem from "@/components/AppGoalListItem.vue";
import AppGoalForm from "@/components/AppGoalForm.vue";

export default defineComponent({
  components: { AppGoalListItem, AppGoalForm },
  setup() {
    const isGoalVisible = ref(false);

    return {
      isGoalVisible,
    };
  },
});
</script>

There is a very interesting component <RouterLink>, which wraps an AppTaskListItem component. By default a <RouterLink> component will always renders as <a> Html tag. I want to change this behaviour so a link will render as a root element of the AppTaskListItem component. In Vue Router 3.x version, it was just a matter of adding a tag prop, but it has been changed sin Vue Router 4.x version through a scoped slot.

<template>
  <!-- Vue Router 3.x -->
  <RouterLink to='/' tag='li'>Go to home</RouterLink>


  <!-- Vue Router 4.x -->
  <!-- pass the custom option to <router-link> to prevent it from wrapping its content inside of an <a> element. -->
  <RouterLink
      to="/about"
      custom
      v-slot="{ href, route, navigate, isActive, isExactActive }"
  >
      <NavLink :active="isActive" :href="href" @click="navigate">
        {{ route.fullPath }}
      </NavLink>
  </RouterLink>
</template>

For more details on the <RouterLink>’s v-slot check out the official documentation

Extracting the “Task List Item” component

Another element to be extracted is “Task List Item” which is will be shared on “Weekly” & “Daily” pages. Based on the design a list item can have 4 states.

the active state is when a task can be edited or deleted
the underReview state is when a task can be completed, deleted or rescheduled
the reviewed state is when a task can be reverted to its original state
the past state is when a task only indicates the status

[src/components/AppTaskListItem.vue]

<template>
  <li class="p-10 border border-gray-200 rounded-md text-left">
    <div
      v-if="state === 'active' || state === 'underReview'"
      class="flex items-center justify-end mb-5"
    >
      <div class="space-x-2 text-gray-400 -mt-5">
        <template v-if="state === 'active'">
          <button @click="actionClicked()">
            <PencilIcon class="h-5 w-5 hover:text-gray-700" />
          </button>
          <button @click="actionClicked()">
            <TrashIcon class="h-5 w-5 hover:text-gray-700" />
          </button>
        </template>

        <template v-if="state === 'underReview'">
          <button @click="actionClicked()">
            <CheckIcon class="h-5 w-5 hover:text-gray-700" />
          </button>
          <button @click="actionClicked()">
            <LogoutIcon class="h-5 w-5 hover:text-gray-700" />
          </button>
          <button @click="actionClicked()">
            <TrashIcon class="h-5 w-5 hover:text-gray-700" />
          </button>
        </template>
      </div>
    </div>

    <div class="flex items-center">
      <LogoutIcon v-if="state === 'past'" class="h-14 w-14 mr-10" />

      <template v-if="state === 'reviewed'">
        <div class="flex space-x-2 mr-9">
          <LogoutIcon class="h-5 w-5" />
          <button @click="actionClicked()">
            <RefreshIcon class="h-5 w-5 text-gray-400 hover:text-gray-700" />
          </button>
        </div>
      </template>

      <p class="text-lg font-light">
        Lorem ipsum dolor sit amet consectetur adipisicing elit. Porro debitis
        quo nam hic a cupiditate ex illum id. Enim voluptates, est vero possimus
        sunt accusamus corporis recusandae pariatur delectus ipsa?
      </p>
    </div>
  </li>
</template>

<script lang="ts">
import { defineComponent } from "vue";
import { PencilIcon, TrashIcon, CheckIcon, LogoutIcon, RefreshIcon } from "@heroicons/vue/outline";

export default defineComponent({
  components: { PencilIcon, TrashIcon, CheckIcon, LogoutIcon, RefreshIcon },
  props: {
    state: {
      type: String,
      default: "active",
      validator: (value: string): boolean => {
        return ["active", "underReview", "reviewed", "past"].includes(value);
      },
    },
  },
  emits: ["actionClicked"],
  setup(_props, { emit }) {
    function actionClicked() {
      emit("actionClicked");
    }

    return {
      actionClicked,
    };
  },
});
</script>

The state of the component is controller by the props passed from a parent component. In composition api the way props used is also different. The setup() option is executed before the component is created, once the props are resolved, and serves as the entry point for composition APIs, which means that this inside setup() won’t refer to the component instance. That’s why props are passed to setup() as a first argument

<script>
export default {
  // Vue 2.x
    props: {
        title: String,
    }
  methods: {
    click() {
      console.log(this.title);
    },
  },

  // Vue 3.x
    props: {
        title: String,
    },
  setup(props) {
    function click() {
      console.log(props.title);
    }

    return {
      click,
    };
  },
};
</script>

Now the component can be reused everywhere and a design will change based on the required state. For the past state, I have hardcoded an icon, but it will be updated to have a dynamic icon based on the actual status of the task. A lot of dummy functions just to simulate the actions.

<template>
    <div>
         <AppTaskListItem />
         <AppTaskListItem state="underReview" />
         <AppTaskListItem state="reviewed" />
         <AppTaskListItem state="past" />
    </div>
</template>

It is not necessary to indicate an active state as it is a default option for the component.

Extracting the “Task Form”

It is the same as the Goal form with a small difference of not having an input for the due date. I won’t document the code here.