Continue reading, or jump ahead using these links:<\/p>\n
- \n
- Overview of the Vue SPA in WordPress<\/a><\/li>\n
- Anatomy of the Vue Single Page Search App<\/a><\/li>\n
- Using Vue-CLI to Set Up a Local Development Workflow<\/a><\/li>\n
- Scaffolding a Vue app with Vue-CLI<\/a><\/li>\n
- Integrating the Vue SPA with WordPress<\/a><\/li>\n
- Building the Single Page Search App in WordPress<\/a><\/li>\n
- Building the Search App with Vue Single-File Components<\/a><\/li>\n<\/ul>\n
If you’ve never worked with Vue or other modern JavaScript frameworks\/libraries, it’s a great time to jump in. While the sheer number of frameworks urging you to up your JavaScript game can be quite overwhelming, Vue makes the journey nothing less than enjoyable.<\/p>\n
Note: This article is intended for intermediate-advanced WordPress developers and assumes that you have a working knowledge of PHP, JavaScript, Vue.js and the WordPress REST API<\/a>. If you\u2019d like a refresher, I recommend that you read through the following:<\/strong><\/p>\n
- \n
- JavaScript for WordPress Developers<\/a><\/li>\n
- A Quick Start Guide To The WordPress REST API<\/a><\/li>\n
- JavaScript and the WordPress REST API: Understanding the Jargon<\/a><\/li>\n<\/ul>\n
Familiarity with Vue.js (2.x)<\/a> is also essential. The Single Page App (SPA) uses many of Vue’s features such as single-file components, custom events, computed properties, lifecycle hooks, as well as Axios to interact with the WordPress REST API. If you’re new to Vue, it’s really easy to pick up, and you can get started in just a couple of hours with these tutorials:<\/p>\n
- \n
- Vue.js 2 – Getting Started by Academind<\/a><\/li>\n
- Introduction to Vue.js by Vue Mastery<\/a><\/li>\n<\/ul>\n
Although Vue apps can be written in pure ES5 syntax, I will be using some new features of JavaScript introduced in versions ES6 and ES7. If you need to get up to speed with ES6, take a look at the following:<\/p>\n
- \n
- ES6 JavaScript – The Basics<\/a><\/li>\n
- The WordPress Developer\u2019s Guide To ES2015 (ES6)<\/a><\/li>\n<\/ul>\n
Whether you need to use modern JavaScript or Vue.js will completely depend on your requirements and preferences. My goal is to help you explore the possibilities of integrating Single Page Applications in WordPress with a practical Search app. So let’s get started!<\/p>\n
Overview of the Vue SPA in WordPress<\/h2>\n
For this article, I’ve built a Single Page Search app in WordPress with Vue.js using a child theme of the Twenty Seventeen WordPress theme. You can download the child theme from here<\/a> to follow along with the article.<\/p>\n
The Search app can be rendered on any WordPress page using Custom Page Templates<\/a>. The Page Template basically provides the Vue instance with an existing DOM element to mount on.<\/p>\n
\n![\"Integrating](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2018\/05\/integrating-vue-with-wordpress.png\")
Integrating a Vue.js App in WordPress with Custom Page Templates<\/figcaption><\/figure>\n<\/div>\n The app thus adopts a hybrid or a mixed approach, where a server-side application (WordPress) also serves the frontend, but portions of it are rendered with a client-side application like Vue. This is different from a pure SPA that may use a headless or a decoupled CMS, where the server-side engine is only responsible for providing the content (through an API) and does not generate the HTML for rendering it.<\/p>\n
Enhancing Search Experience with Vue.js<\/h3>\n
In a traditional search scenario, each request to the server causes the page to reload. However, with Vue.js or an SPA approach, the page is dynamically updated as the user interacts with the search but without the constant reloads. This makes for a very pleasing user experience.<\/p>\n
In fact, you can try out the pen I’ve created right here<\/a>.<\/p>\n
My Vue Search app builds on the example from the pen I’ve linked to above. So, let’s get a sense of the inner workings of the Search app before diving into the code.<\/p>\n
Anatomy of the Vue Single Page Search App<\/h2>\n
The following infographic explains how the Search App is composed using several reusable components<\/a> that interact with each other.<\/p>\n
\n![\"vue](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2018\/05\/internal-strucutre-vue-search-spa-600x600.png\")
Internals of the Vue Single Page Search App<\/figcaption><\/figure>\n<\/div>\n At a high-level, here’s what the various components do:<\/p>\n
- \n
AppNavigation<\/code> provides the router links for Vue Router to render theAppQuickSearch<\/code> andAppCustomSearch<\/code> components.<\/li>\nAppQuickSearch<\/code> andAppCustomSearch<\/code> work as parent components toAppFilterSwitches<\/code> andAppGetPosts<\/code>. However, they result in two completely independent Search applications, each equipped with its own of data, methods and properties.<\/li>\nAppFilterSwitches<\/code> renders input toggle switches that may either be checkboxes or radio buttons depending on the parameters passed to it.<\/li>\nAppGetPosts<\/code> fetches data from the WordPress REST API and filters it using the search key and toggle inputs. It then calls theAppDisplayPost<\/code> component for each post in the filtered result.<\/li>\nAppDisplayPost<\/code> renders the markup for an individual post item and displays it in the search results.<\/li>\n<\/ul>\nAll of this takes place inside a Custom Page Template assigned to a specific page(s) in WordPress.<\/p>\n
Using Vue Single-File Components<\/h3>\n
You may have seen many examples of Vue components created with the
Vue.component<\/a><\/code> syntax that use in-DOM templates or JavaScript template strings. However, to build the Search app in WordPress, I’ve made use of Vue’s powerful single-file components<\/a> instead.<\/p>\nSingle-file components have many inherent advantages – the ability to provide pre-compiled JavaScript<\/a> (render functions) to the browser, syntax highlighting, case-insensitive component selectors, and component-scoped CSS<\/a> to name a few. They also allow me to write modular and manageable code by splitting the codebase into multiple (.Vue) files.<\/p>\n
Now that you have a fair idea of how things work, let’s start building the app.<\/p>\n
Using Vue-CLI to Set Up a Local Development Workflow<\/h2>\n
Splitting the code into multiple (.Vue) files with single-file components will require the use of development tools like Vue Loader, Webpack, Babel etc. However, don’t let this throw you off as I’m going to keep things very simple and not deal with configuration files.<\/p>\n
With the Vue-CLI<\/a> you can quickly scaffold a Vue app that’s pre-configured with the best build tools for a modern frontend workflow. So, let’s set up the CLI first.<\/p>\n
Step 1: Install Node.js<\/h3>\n
To use the Vue-CLI, you’ll require Node.js<\/a> ( 8.x preferred, npm version 3+) installed on your system. You can download the installer for your platform from the Node.js downloads page here<\/a>. Once you’ve set that up, test that the following commands work:<\/p>\n
- \n
node --version<\/code> andnpm --version<\/code><\/li>\n<\/ul>\nStep 2: Install Vue-CLI<\/h3>\n
Next, open your system’s terminal (PowerShell in my case), and install the Vue-CLI (2.x) globally by running the
npm install -g vue-cli<\/code> command. Once complete, test that it works by running thevue --version<\/code> command.<\/p>\n\n![\"setting](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2018\/05\/setting-up-vue-cli-2.png\")
Setting up Vue-CLI (2.x) for creating Vue apps<\/figcaption><\/figure>\n<\/div>\n In the image above, you’ll notice that I’ve also installed
ESLint<\/a><\/code> globally withnpm install -g eslint<\/code>. This is because I use theVisual Studio Code<\/a><\/code> editor and its plugins to format and lint my JavaScript. You can use any code editor of your choice but configuring one with a JavaScript linter is highly recommended.<\/p>\nWith the basic setup done, let’s create an app in WordPress with the Vue-CLI.<\/p>\n
Scaffolding a Vue app with Vue-CLI<\/h2>\n
To create the Vue app, I’ve used the official webpack-simple<\/a> vuejs-template. However, you may want to use a more sophisticated template based on your requirements.<\/p>\n
The template sets up a Vue project with Webpack and configures it with a development server and other modern build tools. This provides us with an elaborate development workflow. Among other things, it allows us to write code using NextGen (ES6\/ES7) JavaScript during development, but ship the compiled JavaScript bundle in ES5 for better browser compatibility.<\/p>\n
Step 1: Set up the Vue app inside WordPress<\/h3>\n
To set up the Vue project, navigate to your WordPress theme or child theme using your system’s terminal. Here, I am using PowerShell (in Windows 10) integrated with the Visual Studio Code editor.<\/p>\n
\n![\"navigate](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2018\/05\/navigate-to-wordpress-theme.png\")
Navigate to the directory of your WordPress theme<\/figcaption><\/figure>\n<\/div>\n Step 2: Create a Vue app with the Webpack-Simple template<\/h3>\n
Next, run the command
vue init webpack-simple project-name<\/code>, substitutingproject-name<\/code> with the name of your project (spa in my example), and follow the on-screen instructions.<\/p>\n\n![\"vue](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2018\/05\/scaffolding-with-vue-init.png\")
Scaffolding a Vue app with vue init and a Webpack template<\/figcaption><\/figure>\n<\/div>\n Note: Skip this step if you’re following along with my vuetwentyseventeen child theme<\/a>. It already contains the app in the
spa<\/code> project folder.<\/p>\nThis creates the Vue project inside the
<project-name><\/code> directory with configurations for modern build tools.<\/p>\nStep 3: Install Development Dependencies<\/h3>\n
If you head over to your WordPress theme using your code editor, and look inside the newly created project folder, among the many new files, you’ll notice a file called
package.json<\/code>. It basically lists all the development tools that the app will require. These tools still need to be installed though, and to do so, run the following:<\/p>\n- \n
cd project-name<\/code>(substitue project-name<\/em> with your project-folder)<\/li>\nnpm install<\/code><\/li>\n<\/ul>\nNPM<\/a> will then download and install all the required dependencies in a folder called
node_modules<\/code><\/p>\n\n![\"installing](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2018\/05\/installing-dev-dependencies.png\")
Installing development dependencies with NPM<\/figcaption><\/figure>\n<\/div>\n Note that we won’t be deploying any of these downloaded files in WordPress. They are only required during the development phase.<\/p>\n
Step 4: Run the Webpack Dev Server alongside WordPress<\/h3>\n
The final step involves running the Webpack development server that was installed in the previous step. It may seem strange at first, but you have to run the development server (installed in the previous step), and keep it running along with your local WordPress server (XAMP, WAMP, VVV etc.).<\/p>\n
Even though the Vue SPA is a client-side application, it initially needs to be served by a server, and the Webpack server will do this for us. Only when development is complete, will we serve the final JavaScript bundle through WordPress.<\/p>\n
To start the development server, run the command
npm run dev<\/code> from the Vue project folder. You will then see the starter Vue app automatically open atlocalhost:8080<\/code> in your browser.<\/p>\n\n![\"running](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2018\/05\/running-development-server-600x600.png\")
Running the Webpack development server<\/figcaption><\/figure>\n<\/div>\n The Vue Bundle (build.js)<\/h3>\n
If you look at the page source of the starter app in your browser, you’ll notice that the page contains only a single script file –
build.js<\/code>. This is because when you ran the development server, Webpack automatically compiled<\/a> the Vue app and bundled it with the Vue library, and any other dependencies into a single JavaScript file.<\/p>\nHowever, do note that the file does not physically exist on your system, and is dynamically generated by Node and Webpack at runtime.<\/p>\n
\n![\"in](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2018\/05\/in-memory-javascript-bundle-generated-by-webpack.png\")
The JavaScript bundle dynamically generated at runtime by Webpack<\/figcaption><\/figure>\n<\/div>\n To generate a physical build file that you can ship with your app, you have to run
npm run build<\/code>, which we will see at a later stage.<\/p>\nAt this stage, we have a fully functional Vue app served by a development server from inside the WordPress theme folder. However, it has nothing to do with WordPress yet. So, let’s look at how you can integrate the Vue app with your WordPress theme.<\/p>\n
Integrating the Vue SPA with WordPress<\/h2>\n
Integrating the Vue app with WordPress essentially requires three things:<\/p>\n
- \n
- A DOM element in WordPress for the Vue app to mount on<\/li>\n
- Enqueueing the Vue bundle in WordPress<\/li>\n
- Informing Vue about the DOM mount point in WordPress<\/li>\n<\/ul>\n
Providing the DOM Element in WordPress for Vue<\/h3>\n
You may want to hook the Vue app on a single WordPress page or multiple pages, or conditionally. All Vue needs is a DOM element that exists on your WordPress page of choice.<\/p>\n
For this, you can make use of the WordPress
Template Hierarchy<\/a><\/code> to decide the necessary template file that needs to be edited. In my example, I want the Search app to appear on any WordPress page that uses a specific Custom Page Template. You may instead want to use regular Page Templates<\/a> to target specific pages based on your requirements.<\/p>\nThe Custom Page Template
templates\/vue-search-app-template.php<\/code> of my example child theme provides the DOM element,#wp-vue-app<\/code> for Vue.<\/p>\n
- The WordPress Developer\u2019s Guide To ES2015 (ES6)<\/a><\/li>\n<\/ul>\n
- Introduction to Vue.js by Vue Mastery<\/a><\/li>\n<\/ul>\n
- A Quick Start Guide To The WordPress REST API<\/a><\/li>\n
- Anatomy of the Vue Single Page Search App<\/a><\/li>\n
![\"register](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2018\/05\/npm-run-dev.png\")
![\"register](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2018\/05\/npm-run-build.png\")
![\"specifying](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2018\/05\/specifying-mount-point-in-vue.png\")
![\"injecting](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2018\/05\/injecting-vue-in-wordpress-600x600.png\")
![\"vue](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2018\/05\/vue-search-app-wordpress.png\")
![\"vue](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2018\/05\/vue-folder-structure-in-wordpress-600x600.png\")
![\"configuring](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2018\/05\/configuring-eslint-for-vue-wordpress.png\")