In this tutorial, I will explain you step by step how to create a mobile application (iOS and Android) of your WordPress website using the latest technologies. We’ll be using Ionic Framework, ECMAScript 6, npm, webpack, and Apache Cordova.
At the end of this tutorial you will get the following application. It has only three modules, a Home module that displays your latest posts, a Post module that displays a specific post, and a Menu module that displays the menu.
The beautiful, open source front-end SDK for developing amazing mobile apps with web technologies.
Ionic Framework ecosystem is large, including Ionic CLI (command line tool), Ionic Push (easy push notifications), and Ionic Platform (backend services). It is currently one of the top open-source projects on GitHub with more than 19,000 stars and over 600,000 apps created.
ECMAScript 6 (ES6)
ECMAScript 2015 (6th Edition) is the current version of the ECMAScript Language Specification standard. ES6 got officially approved and published as a standard on June 17, 2015 by the ECMA General Assembly.
Node Package Manager (npm)
Why Not Bower?
In my opinion, webpack has been a game changer in the industry, exit complicated Grunt or Gulp scripts that you need to maintain. webpack allows you to require any type of file (.js, .coffee, .css, .scss, .png, .jpg, .svg, etc.) and pipe them through loaders to generate static assets that are available to your application.
The difference with Grunt and Gulp is that the majority of your needs (minification and compilation) can be covered by just adding some configuration, there’s no need to create scripts. For instance, requiring a Sass file, compiling it, autoprefixing it, and injecting the resulting minified CSS into your application will be as simple as this:
I don’t think I need to show you the equivalent using Gulp or Grunt. I think you get my point.
This tutorial assumes that you have:
- a basic knowledge of AngularJS and Ionic
- a WordPress website ready to be queried (a local installation is fine)
- a machine with , npm, Bower (we’ll need it for some dependencies)
- Git installed with write access without sudo on the project folder
Before we get started, you will need to install two things:
- a WordPress plugin that turns your blog into a RESTFUL API
- the application itself
To fetch the posts for your WordPress installation, you will need to install WP REST API plugin. Make sure that you install version 1.2.x as version 2.x is on its way.
- In WordPress, go to Plugins > Add New.
- Search for WP REST API (WP API).
- Click Install Now to install the plugin.
- If the installation is successful, click Activate Plugin to activate it.
If the installation was successful, open a browser and enter http://example.com/wp-json. This should give you a response similar to the one below.
To install the application, clone the repository, using the following commands.
Next, create a configuration file and install the dependencies.
To make sure both the application and the REST API work together, open config/. This is your personal configuration file, which is ignored by Git. Change the base URL of the API to the one for your WordPress installation.
npm run devserver and open http://localhost:8080/webpack-dev-server/ in a browser. If everything works as expected, you should be in front of a running application that displays your WordPress posts. I have created a demo application to give you an idea of what to expect.
Now that you can see the result of what we are after, let me go through the details. Note that the following code samples are simplified. You can find the source code on GitHub.
npm install command installed several libraries. Some of them are direct dependencies while the rest are development dependencies.
The direct dependencies are dependencies that your application needs in order to run properly when built.
Notice that the application doesn’t directly depend on AngularJS, because ionic-sdk already includes , , , and .
wp-api-angularjs (WordPress WP API client for AngularJS) is a set of AngularJS services that allow communication with the REST API plugin that you installed earlier. You can see the complete list of dependencies on GitHub.
Development dependencies are mostly webpack loaders. Loaders are functions that take the source of a resource file, apply some changes, and return the new source. We need loaders that handle .scss, .js (ES6), .html, and .json. You can see a complete list of development dependencies on GitHub.
5. Application Architecture
I have been developing AngularJS applications for a long time and after a lot of experimenting I have committed to the following architecture:
- a file that can be edited live under the
- every AngularJS module needs a proper folder
- every module file
*.module.jsmust define a unique namespace (and be the only place where this namespace appears)
- every module file
*.module.jsmust declare all its dependencies (even if dependencies are already injected in the app)
- every module file
*.module.jsmust declare all its configs, controllers, services, filters, etc.
- every config, controller, service, filter, etc. must export a function (CommonJS)
- if a module needs a specific style, the .scss file must live within the module
These recommendations are powerful as they assure that you to have loosely coupled modules that can be shared by several applications without running into problems.
This is what the application folder structure looks like:
When using webpack, an entry point is necessary. Our entry point is lib/. It contains our application’s basic dependencies (such as ionic.bundle that contains AngularJS), our home-made modules, and adds the Sass entry point.
Now that we have imported our dependencies we can create our application module. Let’s call our app prototype. It has
wp-api-angularjs, and our home-made modules as dependencies.
Once the module is created, we can export it as a standard CommonJS module.
This is a great example of what an AngularJS module should look like.
Our application has a side menu
<ion-side-menu ui-view="menu"> in which the Menu module will be rendered. It also has a content section
<ion-nav-view name="content"> in which the Home and Post modules will appear.
ui-view directive is part of the UI-router that Ionic uses. It tells
$state (UI-router service) where to place your templates. Similarly, the
name directive attached to
<ion-nav-view> is a custom Ionic directive that is using
ui-view underneath. You can consider both directives identical.
Here is a simplified version of the
root state, the state that all modules share:
For more information about named views, please refer to the documentation on GitHub.
The Menu module is very simple. Its purpose is to add a menu inside
<ion-side-menu>. Without this module, the side menu would be blank. The menu module declares only a config file, it has
ui.router as dependencies.
The most interesting part is the configuration. We do not want to create a state for the Menu module as it is available everywhere. Instead, we decorate the
root state with the menu content. With the
ui-view="menu" being defined in the
root state, we need to use
menu@root to refer to it.
The Home module displays the latests posts of your WordPress website. It has a config file, a controller, and it depends on the following libraries:
The config adds a new state,
root.home, with the
/home URL that has a template and a controller (both living within the module).
This is a simplified version of the Home controller logic. It contains two functions:
loadMore: This function populates
vm.posts. It uses the
$wpApiPostsservice, which is part of the wp-api-angularjs library.
refresh: This function removes posts and calls
The template has a
ion-refresher directive that allows users to reload the page by pulling the page down. It also has a
ion-infinite-scroll directive that calls the
loadMore function when reached. Posts are displayed using the
Tip: Use the
track by expression for better performance. It minimizes DOM manipulation when a post is updated.
The Post module displays only one post. It has a config file, a controller, and it depends on the same librairies as the Home module.
Similar to the Home module, the config adds a new state,
root.post, with the
/post/:id URL. It also registers a view and a controller.
The controller retrieves the post specified in the url
/post/:id via the
$stateParams service (UI router service).
The template has a
ion-spinner directive that displays a loader while the data is being fetched from the WordPress REST API. When the post is loaded, we use an Ionic card to render the author avatar, the post title, and the post content.
Tip: Use the
::, (introduced in Angular 1.3) to avoid watching data that will not change over time.
bootstrap.scss file that we imported in our entry point is as simple as this:
First, we import our variables. We then import the Ionic styles. Importing our variables before Ionic allows us to overwrite whatever Sass variables Ionic has declared.
For example, if you want the positive color to be red instead of blue, you can overwrite it like this:
6. Android and iOS
Run the following commands inside the project folder and chose the platform you want to build for.
In addition to installing platforms within the
/platforms folder, the script will install one plugin. For the demo, we need the
cordova-plugin-whitelist plugin. It is necessary to allow the application to query the WordPress REST API we created earlier.
If you open
<access origin="*" />). Of course, this is only for demo purposes. If you deploy your application to production, then make sure you restrict access like this:
- Android SDK
npm run runAndroid command is a shortcut for
rm -rf www/* && webpack && cordova run android. This removes everything within the www folder, dumps a non-minified version of the app in it, and runs the
android command. If an Android device is connected (run
adb devices to make sure), the command will load the app on the device, otherwise it will use the Android emulator.
- OS X
If you do not have an Apple device, you should install the iOS Simulator. It’s really good and better than the Android emulator.
npm run runIosEmulator is a shortcut for
rm -rf www/* && webpack && cordova run ios. The
npm run runIosDevice command is a shortcut for
rm -rf www/* && webpack && cordova run ios --device.
With this tutorial, I’ve tried to show you how easy it is to create a hybrid, mobile application for your WordPress website. You should now be able to:
- create loosely coupled modules that respect CommonJS specs
- import CommonJS modules with ECMAScript 6
- use the WordPress REST API client side (with wp-api-angularjs)
- leverage Ionic Framework to create a great user interface
- use webpack to bundle your application
- use Cordova to run the application on iOS and Android
If you want to go further, then take a look at a project I created few months ago, WordPress Hybrid Client.
WordPress Hybrid Client
WordPress Hybrid Client (WPHC) is an open-source project available on GitHub that helps you to create iOS and Android versions of your WordPress website for free. WPHC is based on the same technology stack that we used in this tutorial.
WPHC includes the following features:
- push notifications
- bookmarks (offline mode)
- Google Analytics support
- automatic content updates
- social buttons
- accessibility (post font size)
- multiple languages (English, French, Chinese)
- infinite scroll
- syntax highlighter for tech blogs
- image caching
- app rating