DEV Community: Lilo

Creating a themeable Vue component with readonly mode and keyboard support

Lilo — Mon, 16 Dec 2019 10:27:29 +0000

I have this project I'm working on that needed a checkbox.
I didn't use any 3rd party library as I wanted this component to be styled and created from scratch.

Requirements

So, here are the requirements I've drafted for this component:

Created from scratch - no 3rd party
Have a readonly mode where clicks are ignored
Can be color themed - with different look for readonly mode.
Keyboard support - the user must be able to tab to this component (unless it's in readonly mode) and use space to toggle it (again, unless in readonly mode)
Simple usage - replace the native checkbox with minimal adaptations
Support a label element pointing to this component. When the label is clicked, the checkbox should be toggled (this is the behavior of the native checkbox)

Design

Let's look at the requirements and figure out a solution.

Our component's template will be constructed of a span that contains an svg element.
We use svg for two reasons:

It is color-neutral, so we can adapt it to any theme easily.
It is embedded in our source, no need for an extra png file.

This covers requirements #1 and #3.

Native checkboxes actually don't have a readonly state. So here we're free to define any API we want. I've decided to go with this:

If a v-model attribute is defined - the checkbox will behave normally
If a checked attribute is used instead - the checkbox will be readonly.

This also goes hand in hand with the Vue philosophy of not changing component props from the inside (as checked is provided as prop).

This covers requirements #2 and #5.

For keyboard support we'll need two things:

Specify a tabindex=0 attribute on the template, but only if we're not in readonly mode.
Handle spacebar keypress to toggle our state

This covers requirement #4

The last requirement is a bit more tricky, but doable.

When mounted, we'll look for a label targeting our component's id and add an onclick handler on it.

Of course we'll also need to remove the handler before destroy is called.

And that takes care of requirement #6 and we're done with the design.

Implementation

First, let's take a look at the usage of such a component.

Read/write usage

 <label for="test1">click this text to activate the checkbox </label>
 <CheckBox v-model="cb1" id="test1"/>

Read-only usage

<CheckBox :checked="cb2"/>

Styling/Theming

.check-box {
  border: 1px solid darkgray;
  &.readonly {
    border: none;
  }
  .check-mark {
    fill: $primary;
  }
  &:focus {
    outline: black auto 2px;
  }
}

Now let's look at the different parts of our component:

Template

We'll look at important parts of the template.
First up is the root element:
Here we handle the interaction, add keyboard support and add theme support for the readonly state.

<span
    class="check-box"
    @click="notifyToggle()"
    :tabindex="isReadOnly ? '': 0"
    @keypress.space="notifyToggle()"
    :class="{readonly: isReadOnly}"
  >
...

Inside this span, we'll have two v-if'd spans, the first displays the checkmark and contains the checkmark svg, the second is a placeholder with an empty svg, to maintain the size of the outer span:

    <span v-if="value || checked">
      <svg
        class="check-mark" xmlns="http://www.w3.org/2000/svg"
        preserveAspectRatio="xMidYMid meet" viewBox="0 0 40 40"
        :width="size" :height="size"
      >
        <!--created with vectr.com (it's their built-in check-mark shape)-->
        <path
          d="M21.15 31.19L21.15 31.19L13.74 40L0 23.69L7.42 14.88L13.73 22.39L32.58 0L40 8.81L21.15 31.19Z"
        ></path>
      </svg>
    </span>
    <span v-else>
      <svg xmlns="http://www.w3.org/2000/svg" :width="size" :height="size">
        <!--an empty placeholder for theming purposes -->
      </svg>
    </span>

Toggle and read-only support

props: {
    checked: {
      // for readonly access
      type: Boolean,
      default: undefined // so that we can check if this property was provided
    },
    value: Boolean, // for v-model usage
...
  methods: {
    notifyToggle() {
      this.$emit("input", !this.value);
    }
  },
  computed: {
    isReadOnly() {
      return this.checked !== undefined;
    }
  },
...

External label support

props: {
...
    id: String, // for tracking down the label that activates this checkbox
...
},
...
  mounted() {
    if (this.id) {
      this.label = document.querySelector(`label[for="${this.id}"]`);
      if (this.label && this.label.onclick === null) {
        this.label.onclick = () => this.notifyToggle();
      } else {
        this.label = null;
      }
    }
  },
  beforeDestroy() {
    if (this.label) {
      this.label.onclick = null;
    }
  }

Summary

That's it. We've got a fully functional, theme-able checkbox with readonly option and keyboard support.

The full code, alongside a demo, can be found here:
https://codesandbox.io/s/vue-checkbox-vkssq

Code with love,
Lilo

Vue CLI Configuration

Lilo — Mon, 02 Dec 2019 08:37:15 +0000

Did you know you can actually configure the Vue CLI?

Although not immediately apparent, the Vue CLI does have its own configuration file.

The configuration changes the way the build and serve commands work.

Name & location

The file, named vue.config.js, is not created by default and should be added to the root folder of your project.

Structure

The general structure is of a regular JS Module:

module.exports = {
 /* configuration goes in here */
}

Some interesting options

So... What are the options?

Well, there are many options, there's a very long list of them in the official guide

I've listed some of the more interesting ones below.

assetsDir

Where the static assets are placed relative to the output folder, default is ''

pages

Build the app in multi-page mode (mainly for creating a browser extension project)

lintOnSave

Use this to disable the lint on save or to produce just warnings instead of failing the compilation. Only relevant when eslint plugin is used. Default is true

configureWebpack

Specify a configuration option for webpack, can be object or a function.

css.extract

Whether to extract the css of the components into separate files. Defaults to true on production and false on development.

css.loaderOptions

Pass options to one of the configured css loaders.

devServer.proxy

Specify the URL for a development API server, this will send any unknown requests to the specified URL.

pwa

Pass options to the progressive web app plugin.

pluginOptions

Pass options to any other 3rd party plugin.

Code with love,
Lilo

4 different ways to create Vue Components

Lilo — Sun, 01 Dec 2019 16:13:28 +0000

Did you know that there are several ways to create Vue Components?
Here we'll discuss 4 of them.

TL;DR

I've created a CodeSandbox project to demonstrate those 4 ways.
If you'd like to self-explore, go ahead and click here.
If you want the full picture, keep reading.

The full story

For demonstration purposes, I came up with this simple task that is required from each component that we'll create:

Component Requirements

Get a list of string items (in the props).
Display a button for each item.
- Each button should have lightsteelblue background.
- The text of each button should be the string of that item.
- upon clicking a button, the related item is considered selected.
Display a status string inside a <p> element.
- at first the status should be Please select your favorite.
- when an item is selected the status will change to reflect that selection. For example: if Picard is selected, the status should be: You selected Picard (yeah, I'm a Trekkie)

I then went ahead and created 4 components:

The 4 types of stateful* components

SFC (Single File Component)
Component with a template
Component with a render function
Component with a render function and JSX syntax

*There's one more type, a functional component, but it is stateless and therefore cannot help us in this imaginary task

So, let's check out the implementations...

Implementations

1. SFC (Single File Component)

This is the most common one and should be used as default.
The .vue file is actually an html file that is being pre-processed by the Vue CLI to allow for special features in the template and in the style tag (e.g. scss and scoped styles)

<template>
    <div>
        <button v-for="(item, index) in items" :key="index" @click="onItemSelected(item)">{{item}}</button>
        <p v-if="selectedItem">You selected {{selectedItem}}</p>
        <p v-else >Please select your favorite</p>
    </div>
</template>

<script>
    export default {
        name: "ListItemsSfc",
        props: ['items'],
        data() {
            return {
                selectedItem: null
            }
        },
        methods: {
            onItemSelected(item) {
                this.selectedItem = item;
            }
        }
    }
</script>

<style scoped>
    button {
        background: lightsteelblue;
    }
</style>

2. Component with a template

This is pretty similar to SFC only you don't get the scoped styling and the syntax highlighting (since the template is actually a string)

import Vue from 'vue/dist/vue.js'; // <-- important for template components to work

Vue.component('ListItemsTemplate', {
    props: ['items'],
    data() {
        return {
            selectedItem: null
        }
    },
    methods: {
        onItemSelected(item) {
            this.selectedItem = item;
        }
    },
    template: `
                <div>
                    <button style="background: lightsteelblue" v-for="(item, index) in items" :key="index" @click="onItemSelected(item)">{{item}}</button>
                    <p v-if="selectedItem">You selected {{selectedItem}}</p>
                    <p v-else >Please select your favorite</p>
                </div>

                `
});

3. Component with a render function

Allows for a more dynamic creation of the component's template.
The render function accepts a createElement function that is used for rendering a single html element (here shortened as ce).
The createElement function receives a tag name, an optional data object and an optional content that can be text or additional html child elements, also created with this function.

import Vue from 'vue/dist/vue.js'; // <-- important for template components to work

Vue.component('ListItemsRender', {
    props: ['items'],
    data() {
        return {
            selectedItem: null
        }
    },
    methods: {
        onItemSelected(item) {
            this.selectedItem = item;
        }
    },
    render(ce) {
        let getButtonData = (item) => {
            return {
                style: { background: 'lightsteelblue' },
                on: { click: () => this.onItemSelected(item) }
            }
        };
        let buttons = this.items.map(item => ce('button', getButtonData(item), item));
        let statusText = this.selectedItem ? `You selected ${this.selectedItem}` :
            'Please select your favorite';

        return ce('div', [...buttons, ce('p',statusText)]);
    }
});

4. Component with a render function and JSX syntax

It makes writing complex templates easier.

import Vue from 'vue/dist/vue.js'; // <-- important for template components to work

Vue.component('ListItemsJsx', {
    props: ['items'],
    data() {
        return {
            selectedItem: null
        }
    },
    methods: {
        onItemSelected(item) {
            this.selectedItem = item;
        }
    },
    render(h){

        let buttons = this.items.map(item => <button onClick={() => this.onItemSelected(item)} style="background:lightsteelblue">{item}</button>);
        let statusText = this.selectedItem ? `You selected ${this.selectedItem}` :
            'Please select your favorite';

        return (
            <div>
                {buttons}
                <p>{statusText}</p>
            </div>
        );
    }
});

And here's the final result, hosted on CodeSandbox. You can open the project and play with the components to test them out.

The final result

Let me know in the comments in case you have any general questions or any questions related specifically to one of the alternatives presented here.

Coded with love,
Lilo

Things you didn't know about Vue CLI

Lilo — Sat, 30 Nov 2019 15:53:15 +0000

If you've just used vue create to create your projects, this post is for you!

Important note for windows users: Do not include the $ sign in your commands, it is not a part of the command, it is just the prompt sign in linux/unix/bash shells.

Creating projects

There are actually several commands you can use to create a Vue project using the CLI.

The most known option

This is the default and recommended one.

# creating a project using the command line
$ vue create my-project

The CLI with the UI

Did you know that Vue CLI actually has a web UI?
It allows for a more interactive use of the CLI.

# run this command and it will open a browser window with the UI
$ vue ui

The web UI also has some cool utils that you can use to monitor your build, your development server and other processes.

If you're interested, let me know in the comments and I'll do a separate post on the web UI and its many options.

Legacy templates

In version 2 of Vue CLI, there was a concept of "templates" that allowed you to specify a template (built-in or community provided) that will be the basis for your new project.

This is still supported in Vue CLI 3 but it requires an extra step.

# run this once for enabling support of legacy templates
# you can run this anywhere as it installs a global plugin
$ npm install -g @vue/cli-init

# create a new project using a legacy template
$ vue init webpack my-project

And here's a list of the built-in templates.
There are many other community provided templates out there.

Fast Prototyping

Sometimes you just want to view a single Vue component for fast prototyping without the hassle of creating an entire project.

This is possible by globally installing another part of the CLI system:

# run this once for enabling support of legacy templates
# you can run this anywhere as it installs a global plugin
$ npm install -g @vue/cli-service-global

# serve your component by running this command 
# (the --o is optional and opens a new browser window)
$ vue serve my-component.vue --o

Plugins

The Vue CLI is all about plugins. Plugins add content and/or abilities to your project.
There are two types of plugins:

Internal plugins, these are prefixed @vue/cli-plugin-
Community plugins, these are prefixed vue-cli-plugin-

Important: Plugins usually modify your project sources, so it is a good idea to git commit all your changes before adding a plugin.

To add a plugin, use the following command inside your project's folder:

$ vue add plugin-name

You can find a searchable list of plugins inside the Vue CLI UI:

Run the UI using vue ui command
Select a project of yours in the dropdown menu on the top left corner.
Click the "Plugins" in the menu on the left.
Click "Add plugin" button and browse the list of plugins.
When you're ready to add a plugin, select it and click the "Install" button on the bottom right.