In part 3 of our GraphQL series, its time to put our API into action - this tutorial will guide you through creating a simple GraphQL client web app, all through the use of the Vue.js framework. Contains all the relevant code you need for the project!
Recently, we’ve been introducing you to GraphQL and how it fits into the new wave style of designing APIs. It’s a clever alternative to REST architectures, and works very well for particular projects and use cases. Part one of our series was a run down of GraphQL, how it differs from other technologies, and where to use it, and part two outlined creating an API in Node.js using GraphQL.
In this third part of our series we will focus on building a simple web application using GraphQL for communication - with the API we built in part two.
We will use vue-apollo (powered by apollo-client internally) for integrating the GraphQL library into our Vue.js application.
Our interface will allow us to list projects requiring specific tech skills and show the best candidates for each project based on their knowledge and experience.
This tutorial assumes you already have Node.js and NPM installed and that the API that we built in part two is up and running on port 3200.
Here is a link to our repo with finished project - https://github.com/iRonins/GraphQL-client-with-Vue.js
Creating a new project
We will use the vue-cli tool to bootstrap our project. `vue-cli` allows us to easily create a structure and the necessary configuration for the project using one of the available templates.
1
2
3
4
npm install -g vue-cli
vue init webpack-simple talent-matcher
cd talent-matcher
npm installTo keep this tutorial simple, we will use the webpack-simple template. For real-world applications we would recommend that you use the full-featured webpack template.
The above commands will create an initial file structure and Webpack configuration for our app.
Before we start writing our app, we need to install `vue-apollo` and `apollo-client` (for connecting to the GraphQL API), `bootstrap-vue` (for some nice UI), and some css loaders (for importing Bootstrap styles):
1
npm install -D vue-apollo bootstrap-vue apollo-client@1.0.1 style-loader css-loaderWe also recommend that you install Apollo DevTools to improve your debugging and development experience. It will provide you information about the available queries and mutations within your API, execute them, and preview the current state of the application’s store.
Writing the actual app
We need to start by making our app aware of all the add-ons that we just installed:
src/main.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
// src/main.js
import Vue from 'vue'
import { ApolloClient, createNetworkInterface } from 'apollo-client'
import BootstrapVue from 'bootstrap-vue'
import VueApollo from 'vue-apollo'
import 'bootstrap-vue/dist/bootstrap-vue.css'
import 'bootstrap/dist/css/bootstrap.css'
import App from './App.vue'
const apolloClient = new ApolloClient({
networkInterface: createNetworkInterface({
uri: 'http://localhost:3200/graphql'
}),
connectToDevTools: true
})
const apolloProvider = new VueApollo({
defaultClient: apolloClient
})
Vue.use(VueApollo)
// Fix for compatibility issue with Vue 2.5.1
// https://github.com/bootstrap-vue/bootstrap-vue/issues/1201
let originalVueComponent = Vue.component
Vue.component = function(name, definition) {
if (name === 'bFormCheckboxGroup' || name === 'bCheckboxGroup' ||
name === 'bCheckGroup' || name === 'bFormRadioGroup') {
definition.components = {bFormCheckbox: definition.components[0]}
}
originalVueComponent.apply(this, [name, definition])
}
Vue.use(BootstrapVue)
Vue.component = originalVueComponent
new Vue({
el: '#app',
apolloProvider,
render: h => h(App)
})We basically import `vue-apollo`, `apollo-client`, `bootstrap-vue` and some Bootstrap styles.
Unfortunately, we also need to override the `Vue.component` function while we are importing `BoostrapVue`, because there is an incompatibly bug that causes an error (`Invalid value for option "components": expected an Object, but got Array`) on the `2.5.x` version of `Vue`.
We also need to import `style-loader` and `css-loader` modules to our Webpack configuration so we can import the Bootstrap styles in our `main.js` script:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// webpack.conf.js
...
module.exports = {
...
module: {
rules: [
...,
{
test: /\.css$/,
use: [
{ loader: "style-loader" },
{ loader: "css-loader" }
]
}
]
}
}Now let’s modify our application’s template:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
// src/App.vue
<template>
<div id="app">
<header class="header">
<b-navbar toggleable="md" type="light" variant="light">
<b-container>
<b-navbar-brand href="#">Talent Matcher</b-navbar-brand>
</b-container>
</b-navbar>
</header>
<main>
<b-container>
<projects />
</b-container>
</main>
</div>
</template>
<script>
import projects from './components/Projects.vue'
export default {
name: 'app',
components: {
projects
}
}
</script>
<style>
.header {
margin-bottom: 2rem;
}
</style>This basically creates a “shell” of our app (navbar, container, etc.). Our projects will be displayed by the `Projects` component, which will be responsible for 2 things:
- listing all projects
- showing the best candidates for the currently selected project
Let’s start by building the skeleton of our `Projects` component:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
// src/components/Projects.vue
<template>
<b-row>
<b-col cols="4">
<b-list-group>
<b-list-group-item v-for="project in projects"
:key="project.id"
href="#"
:active="selectedProjectId == project.id" @click="selectProject(project)">
{{ project.name }}
</b-list-group-item>
</b-list-group>
</b-col>
<b-col>
<p v-if="!selectedProjectId">Select project on the sidebar to see its best candidates</p>
</b-col>
</b-row>
</template>
<script>
import gql from 'graphql-tag'
const query = gql`
query projects {
projects {
id,
name
}
}
`
export default {
apollo: {
projects: query
},
data() {
return {
projects: [],
selectedProjectId: null
}
},
methods: {
selectProject(project) {
this.selectedProjectId = project.id
}
}
}
</script>As you can see, we are importing `gql` from `graphql-tag` in order to create the `projects` query responsible for fetching our projects with their `id` and `name` attributes. Then we provide that query to the `apollo` property. The component will automatically send the query to the GraphQL API and place the results inside its `projects` data so we can iterate over them using `v-for` directive and display each of them using the list-group-item component.
We have also added some nice tweaks from `vue-bootstrap` like highlighting the currently selected projects on the list, etc. to make our app more visually appealing.
When you run the app it should look similar to the screenshot below:
Let’s add to it so that we can display the candidates for selected project. To do that we will need to create a new `Candidates` component which we will use in the `Projects` component.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
// src/components/Candidates.vue
<template>
<b-table bordered hover :items="candidates" :fields="fields">
<template slot="skills" slot-scope="data">
{{data.item.matchedSkills}} ({{data.item.matchedSkillsNo}})
</template>
</b-table>
</template>
<script>
import gql from 'graphql-tag'
const query = gql`
query projectCandidates($projectId: Int!) {
candidates(projectId: $projectId) {
id,
fullName,
matchedSkillsNo,
matchedSkills,
experience
}
}
`
export default {
props: ['projectId'],
apollo: {
candidates: {
query,
variables() {
return {
projectId: this.projectId
}
}
}
},
data() {
return {
candidates: [],
fields: [
{
key: 'id',
label: 'Id',
sortable: false
},
{
key: 'fullName',
label: 'Full name'
},
{
key: 'skills',
label: 'Matched skills'
},
{
key: 'experience',
label: 'Matched skills experience',
sortable: true
}
]
}
}
}
</script>As you can see above, we are defining our query to fetch candidates who match the project requirements based on their skills and experience. Our query is a little bit more complicated than the previous one because the `projectId` parameter must be bound to the component’s property.
The `bootstrap-vue` library also provides a nice table component which allows us to customize the columns and add simple sorting based on the candidate’s experience.
You can check all available options in the documentation for `bootstrap-vue`.
We also need to include our nearly created component in the `Projects.vue` component:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// src/components/Projects.vue
<template>
...
<p v-if="!selectedProjectId">Select project on the sidebar to see its best candidates</p>
<candidates v-else :projectId="selectedProjectId" />
...
</template>
<script>
import candidates from './Candidates.vue'
...
export default {
components: {
candidates
}
...
}
</script>When you run the app it should look similar to the screenshot below:
So far so good but when we refresh the page we are losing the previously selected project - it basically always goes back to its initial state.
Let’s fix that by adding proper routing. We will use vue-router for that, the official routing library for `Vue`.
Let’s install the dependency first:
1
npm install -D vue-routerand make our application aware of it:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// src/main.js
import VueRouter from 'vue-router'
...
import Projects from './components/Projects.vue'
...
const router = new VueRouter({
routes: [
{
name: 'projects',
path: '/:projectId?',
component: Projects
}
]
});
Vue.use(VueRouter)
...
new Vue({
el: '#app',
apolloProvider,
router,
render: h => h(App)
})We also created our single `projects` route which supports the optional `projectId` parameter to persist our application’s state between page refreshes.
Now we need to modify our `Projects` component to take the `projectId` parameter from the `$route` and assign it to the `selectedProjectId` property which will highlight the correct link on the sidebar and pass the correct `selectedProjectId` to the `Candidates` component which will fetch the correct data.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
// src/components/Projects.vue
<template>
...
<b-list-group-item v-for="project in projects"
:key="project.id"
:to="{ name: 'projects', params: { projectId: project.id } }">
{{ project.name }}
</b-list-group-item>
...
</template>
<script>
...
export default {
components: {
candidates
},
apollo: {
projects: query
},
data() {
return {
projects: [],
}
},
computed: {
selectedProjectId() {
return this.$route.params.projectId
}
}
}
</script>We added a computed property that returns `selectedProjectId` based on the `projectId` param in the `$route`.
We also bind `selectedProjectId` to `projectId` when loading, so when a user refreshes the page, our application fetches candidates correctly after refresh. Also the back / forward buttons now work thanks to `vue-router`.
Let’s also connect the navbar logo (actually `navbar-brand`) with our main page trough the router:
1
2
3
4
5
6
7
8
9
10
11
12
// src/App.vue
<template>
<div id="app">
<header class="header">
<b-navbar toggleable="md" type="light" variant="light">
<b-container>
<b-navbar-brand :to="{ name: 'projects' }">Talent Matcher</b-navbar-brand>
</b-container>
</b-navbar>
</header>
...
</template>We are linking `b-navbar-brand` to our main route (`projects`) - but without the optional `projectId` parameter - this way we can “reset” the application’s state.
We are almost done but we forgot about one missing bit - we do not yet display the skills required by the selected project. Let’s display them above the candidates table.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// src/components/Projects.vue
<template>
...
<p v-if="!selectedProjectId">Select project on the sidebar to see its best candidates</p>
<div v-else>
<p>
<strong>Required skills:</strong>
{{ selectedProject.skills }}
</p>
<candidates :projectId="selectedProjectId" />
</div>
</template>
<script>
...
const query = gql`
query projects {
projects {
id,
name,
skills
}
}
`
export default {
...
computed: {
selectedProject() {
return this.projects.find(({ id }) => id === this.selectedProjectId) || {}
},
...
},
...
}
</script>We’ve added `selectedProject` as computed property which will return `project` data or an empty object, based on the `selectedProjectId` value.
We have also modified our query to ask the API to include the `skills` attribute for each project.
Now our complete app should look like on the screenshot below:
Here is the link to the repository containing full code of the application.
GraphQL is just one of the tools that we have at our disposal to help build web apps that are easier to comprehend, more flexible, and are fully featured. If you are interested in learning how this new technology could benefit your next web application, or are interested in changing over your current infrastructure, then email us at iRonin to have a chat!
Comments