You want your app’s homepage to be more than a simple page or post list? Here’s how to create a fully customized home screen for your app.

Along with building a custom homepage, this tutorial is also a good occasion to put into practice some of the key notions of WP-AppKit theme customization:

Starting Point

Let’s build our homepage on the following basis:

  • We have 2 categories for our WordPress posts: “Blog” and “Tutorials“, and we’d like to display the 3 last posts of each of those categories on the app’s homepage: first the 3 last “Blog” posts, then the 3 last “Tutorials” posts.
  • The 2 categories will also have their own “post list” screen in the app, displaying all posts from respectively “Blog” and “Tutorials” categories, with the corresponding “Blog” and “Tutorials” entries in app navigation.
  • So we consider that we have 2 components (type “Post List”, taxonomy Category) added to our app in WordPress Back Office: first component labelled “Blog” with component slug “blog”, and second named “Tutorials” with component slug “tutorials”.

Here’s an example of what this homepage could look like:

Create A Custom Screen For The Homepage

Except when specified otherwise, all the following code snippets go in the functions.js file of your WP-AppKit theme. HTML examples are based on the Q-Android and Q-iOS default themes but the same principle could work for any other theme.

To create our custom home screen, simply add the following App.addCustomRoute() call to add a new home route that will render using the home.html template:

Then set this new home route as app’s default route, so that it displays at app launch:

Create The HomePage Custom Template

Create a file named home.html at the root of your WP-AppKit theme. This will be the template used to render our homepage.

In this template let’s write the 2 loops that will display our “Blog” and “Tutorials” lists:

Build Post Lists And Pass Them To The Homepage Template

In the previous home template you can see that we used blog_posts and tutorials_posts variables to display our posts.
Those 2 post lists must respectively contain the last 3 posts of our “Blog” and “Tutorials” components. Here’s how we retrieve those posts from our components using TemplateTags.getComponent() and how we pass them to the home.html template, using the template-args filter:

Handle Back Button

At this point if you launch your app you should see your homepage, displaying the last 3 posts of Blog and Tutorials categories.

If you click on a post in a list, the post will display. However, you may notice that the back button that should appear to come back to the home screen does not show up. This is due to 2 things:

  •  The home screen is a custom screen that we created manually with App.addCustomRoute(), so it is not linked by default to App History, which is used to display the back button. Here’s how to take our home screen into account in app history so that the back button displays when we expect it to:

Now the back button should display well when navigating from home to a post.

Add Home Screen To App’s Menu

Finally, let’s add our home screen to the our app’s off-canvas menu:

Our “Home” custom screen is not part of the app components that we set in app’s edition panel, so it won’t appear automatically in your app’s navigation. To add it, simply go to your menu.html template and add the “Home” entry (i.e. a link to our custom “#home” route) to the menu items list:

Here You Go!

We hope this tutorial will help you building nice homepages for your apps. Custom screen creation, template customization and custom app data retrieval like we did here are really useful in many other situations where you want to go further than the default app’s behavior of simply displaying post lists, singles and pages…

Thanks for reading and don’t hesitate to post any questions or feedback in the comments!

Published by Mathieu on January 31, 2017

Freelance Senior Web Developer, WordPress since 2009, JS/Backbone since 2012, Custom Back-End devs, WebApps and Plugins for clients and the community.


  1. Hi Mathieu !

    Great post indeed ; a useful summary of many key notions leading to an efficient home page. Think I’m gonna try it for my next app.

    Keep on the good job !

    Best regards,

    P.S. : I’ve migrated my web site under SSL ; your team told me it was not harmful for my running app and at the end od the process, I can tell you it’s right. Changing all url to https (and implementing redirections) didn’t impact my app at all. This could be an interesting topic for your blog…

    • Thanks Philippe!
      Thanks for your feedback about https migration, good news that it went well for you, could be an interesting topic for a future post indeed.


Leave a Reply

Your email address will not be published. Required fields are marked *

Having questions?

FAQ | Tutorials | Documentation


Contact Us