You may have seen some discussion of Merlin recently. Merlin is described as a “highly configurable WordPress theme setup wizard built for theme developers”. From the short video I’ve seen, Merlin looks beautiful. It’s got some nice illustrations and slick animations, the content is brief and to the point, and the whole process looks very neat.

Inspired by Merlin, I started thinking about what I’d like from a theme set-up wizard. This post outlines the wizard which I’m calling Whizzie.

Whizzie – a WordPress theme configuration wizard

The ground rules

Although most projects have a tendency to wander off the original track, there are a few basic rules that I’m determined to stick to with Whizzie. I’ve outlined these below.

  • It should be simple: The primary purpose of the wizard is to make it easy for the user to get started with your theme. The wizard shouldn’t overwhelm the user with detail, although detail should be available if required. Looking at the theme installation process from the point of view of a non-developer, someone who just wants to get their new site off the ground as quick as they can, they probably don’t want to be overloaded with a load of detail about which plugins are getting installed, for instance.
  • It should feel WordPress-y: The short video I’ve seen of Merlin is beautiful. It’s got some nice illustrations and slick animations, the content is brief and to the point, and the whole process looks very neat. My one issue with what I’ve seen of it, and with dtbaker’s wizard (see below), is that neither wizard looks very WordPress-y. So a ground rule for this project is that the wizard should sit in a standard WordPress page and look and feel like it’s part of the WordPress back-end.
  • It shouldn’t be unique to one theme: The wizard should be reusable. One aim of this project is certainly to come up with a wizard that can slotted into other themes with some simple configuration.

Ultimately, I’d like to end up with something that would allow a non-techie user, perhaps with no experience of WordPress, to set up a relatively complex site in a matter of minutes, and which could be integrated by developers into their own themes. We shall see…


The work I’ve done so far, in addition to taking inspiration from Merlin, relies on two main sources: the TGMPA library from Thomas Griffin that is widely used by plugin and theme developers to install recommended plugins; and an Envato Setup Wizard by dtbaker. This wizard is itself based on the WooCommerce wizard.

Wizard sections

At the moment, I’m planning on including the following sections into the wizard:

  • Introduction / Welcome screen
  • Plugin installation
  • Widget installation
  • Design choices for the user, e.g:
    • Layout
    • Color palette
    • Hero image
  • Branding, e.g:
    • Logo upload
    • Color palette
  • License key
  • Content, either/or:
    • Complete import of XML file or similar
    • Form for user to enter simple content, such as hero slogan, about statement, or similar
  • Thank you section

These sections might change as the project develops.

What the wizard does (at the moment)

This is a rundown of Whizzie’s current functionality. There’s a link to the Github repository at the end of this article.

Redirects to theme page

When the user activates a theme that uses Whizzie, they are automatically redirected to the page containing the wizard. This is pretty standard behaviour for plugins and themes, sending the user off to a dedicated page to give them some guidance.

Wizard interface

The wizard is comprised of several slides, one per action. Each slide is just a list item and only the active slide is displayed. When the user clicks a button to move on, the current slide is hidden and the next one displayed.

Install plugins

The only functional slide at the moment is the Install Plugins slide. Installing plugins uses TGMPA but doesn’t require the user to go to the plugins page to install or activate. Instead, it’s a one-click operation to install and activate all the plugins required by the theme. Although I don’t think the standard TGMPA plugins screen is too intimidating, allowing the user to install plugins with one click greatly simplifies the process and makes for a much better user experience.

On this slide, the user can, if they wish, get more information about which plugins are being installed. I plan to extend this to allow the user to deselect plugins if they wish, but still remain within the wizard.

The reason for hiding the list of plugins is to keep the slide as uncluttered as possible. If the user is interested in what plugins are being added, they can find out. Otherwise they can just click the button and move on.

Install widgets

In version 1.1.0 I added in the widgets step. To allow users to install widgets, you need to export the widgets from your demo site using the Widget Importer and Exporter plugin. Rename the exported file to widgets.wie and place it in the whizzie/content folder.

Skip step

Note the ‘Skip’ button on the screenshot above. Certain, if not all, steps should be optional so if the user doesn’t want to install plugins at this point, they can just move onto the next step. This can be configured by the developer if required.

Progress icons

You can see at the bottom of each screenshot that user progress through the wizard is indicated by a series of icons representing the different steps in the wizard. I’m not sure at this stage whether these should become a clickable navigation element allowing the user to skip around within the wizard. I think that linear progression determined by the developer is probably quite important.

Setting up

You can add Whizzie to your own theme by following these steps:

  • Add the files into a new folder in your theme folder.
  • You also need to include TGMPA in its own folder called ‘tgmpa’ so that Whizzie knows where to find it. You should configure TGMPA as you normally would.
  • Edit the config.php file as required. At the moment, this is just to specify the page title and slug for your wizard and to provide some minor configuration for the wizard screens. The config file then loads the main Whizzie class and gets everything going.
// Change the title and slug of your wizard page
$config['page_slug'] = 'get-started';
$config['page_title'] = 'Get Started';

// You can remove elements here as required
// Don't rename the IDs - nothing will break but your changes won't get carried through
$config['steps'] = array(
 'intro' => array(
  'id' => 'intro', // ID for section - don't rename
  'title' => __( 'Welcome to ', 'whizzie' ) . $theme_title, // Section title
  'icon' => 'dashboard', // Uses Dashicons
  'button_text' => __( 'Start Now', 'whizzie' ), // Button text
  'can_skip' => false // Show a skip button?
 'plugins' => array(
  'id' => 'plugins',
  'title' => __( 'Plugins', 'whizzie' ),
  'icon' => 'admin-plugins',
  'button_text' => __( 'Install Plugins', 'whizzie' ),
  'can_skip' => true
 'done' => array(
  'id' => 'done',
  'title' => __( 'All Done', 'whizzie' ),
  'icon' => 'yes'

Suppressing TGMPA notifications

Note that the way to get rid of the default WordPress notifications from TGMPA is to set the has_notices parameter to false when you’re configuring TGMPA.

Things to consider

Importing content

I’ve thought about how best to approach demo content and how to make that meaningful to the user. There’s also the fact that the user might be switching themes on an existing site with its own content. You don’t want to end up overwriting all that. Many themes, particularly those for sale on Theme Forest, offer the option to import an entire demo site, so you can make your site just like the preview. While I get that this might be useful if you want to see how a site is configured, I don’t think it’s all that useful to a real-life user because you’re just going to have to strip out all the content once it’s been imported.

On the other side of this, I’ve used a number of third party themes for different purposes over the years, mainly for client sites. One common feature is that the demo site and your own version are often miles apart. So while I’m not certain of the benefit of importing pages and posts wholescale, I think that adding some content through the wizard will help the user immensely. Ultimately, we want the user to go through the wizard, click on a nice button to view their site, and see what looks like the finished product.


Something like the TGMPA is pretty universal as a way of installing plugins. It would be nice if Whizzie could be this widely applicable; however, given the number of ways that developers find to do non-standard things, I think this might be difficult.

User choice

How many choices do we make for the user? The purpose of the wizard is to configure the theme. Giving too many choices to the user slows down that process and it ends becoming another editing tool. On the other hand, we need to ensure that the user is creating something that is recognisably theirs.

Next steps

I’m going to be adding some more wizard sections in and considering how best to universalize this so that any theme can use it. There’ll be some limitations to that: for instance, I don’t have any plans to support third party theme options frameworks, like Redux.

I also want to have the option of using a hook to call the wizard so that it can be incorporated into a larger theme options page rather than requiring its own page. Perhaps the config file will have a setting to specify whether a theme page already exists.

For now, however, you can take a look at the code and possibly start to use it in your projects. The project is available from You’ll also need to add TGMPA.

Do you develop plugins?

You should try Wisdom, a plugin designed specifically for plugin developers that allows you to track your plugin's usage and provides invaluable data on how your plugin is being used. Find out more.

Leave a Reply

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