New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Setup wizard #311

merged 44 commits into from Sep 4, 2018


None yet
2 participants
Copy link

ChaseWiseman commented Jul 29, 2018


Add a setup wizard framework for plugins to extend to provide a friendlier, stepped UI to configure high-impact plugin settings.


We originally wanted to extend WooCommerce core's WC_Admin_Setup_Wizard class, but after some experimentation it was clear that the rendered markup is not flexible enough for us to shape it for our plugins. We'd end up doing so much method overriding that there wouldn't be much benefit to it. However, the stylesheet alone covers almost all of the UI for us so we use that by loading it in our class.

When a plugin makes use of the wizard, a new “Setup” plugin action link is added to the plugins list screen. This replaces any standard “Configure” link that exists now, and takes users directly to the start of the wizard:


The first step is presented, along with a customizable welcome message:


The user then goes through all of the steps added by the plugin. Wording is up to the plugin, but in general we want to keep things conversational and easy to follow. Settings that get put in the wizard should be high-level merchant decisions that are crucial for plugin operation.

Take a payment gateway’s Environment setting for example. On a standard settings screen this is a simple dropdown with “Test” or “Production” options. However, in the wizard we might present it like this:

label: Do you want to process live payments?
- No, I want to test things out first
- Yes, process payments in the production environment

Plugins can have as few settings and steps as makes sense.

After the last step, they are presented the “Next Steps” screen, where plugins can add more crucial steps to take that don’t fit inside the Wizard context. This is what the screen looks like by default, if a plugin hasn’t defined any of its own next steps:


Any time a user returns to the regular dashboard from the wizard (either by finishing the steps, or bailing using a “No thanks” link), the framework sets a wc_{$plugin_id}_setup_wizard_completeoption. This restores the plugin’s “Configure” link on the plugins page, and can be used by plugins if other UI changes are needed.


New abstract class: \SkyVerge\WooCommerce\PluginFramework\v5_2_0\Admin\Setup_Wizard

This new class handles most of the wizard's base functionality. Displaying the markup, navigating steps, etc... It is not included by default.


There is one abstract register_steps() method that plugins must implement. This is where you define your unique setup steps.

1. Register Steps

A plugin can have as few as one single step. To register a step:

    __( 'Step Name’, 'woocommerce-plugin' ),
    array( $this, 'step_1' ), // display callback
    array( $this, 'save_step_1' ) // save callback

The callbacks defined above must be callable or the step won’t be registered. The save callback isn’t required if the step is purely informational and has no form inputs. There is also a wc_{$plugin_id}_setup_wizard_steps filter.

2. View

The view callback is called inside the step’s <form> element. The content of this markup is entirely up to the plugin. When adding form inputs, you do have a render_form_field() method available. This is a wrapper for woocommerce_form_field() and just adds a few default args to ensure the fields are wrapped properly for styling. You can also add your own input display JS here if needed.

3. Save

The save callback can be used to store the settings values when they’re posted. There is already a nonce check in place, so all you need to do is validate, sanitize, and store the values. The callback can throw a SV_WC_Plugin_Exception for any invalid form values or other issues that need the user’s attention. The message from this exception is displayed by the framework as an error:


4. Next Steps

You can define what’s displayed on the final screen using the get_next_steps() & get_additional_actions() methods. Use these areas for crucial items like “Create your first add-on” or “Customize the look and feel of your invoice”. These should be steps that can’t fit in to the wizard, usually having their own UI, but should be completed to consider setup complete.

The “additional actions” are smaller meta things like leaving a review, etc… Note that if you define your own next steps and the “view docs” step isn’t kept, it will automatically be bumped down to the additional actions.

5. Fire it up!

All that’s left is to init the handler!

 * Loads and initializes the plugin lifecycle handler.
protected function init_setup_handler() {

    require_once( $this->get_framework_path() . '/admin/abstract-sv-wc-plugin-admin-setup-wizard.php' );
    require_once( $this->get_plugin_path() . '/includes/admin/class-wc-plugin-setup-wizard.php' );

    $this->setup_wizard = new \SkyVerge\WooCommerce\Awesome_Plugin\Admin\Setup_Wizard( $this );

Then call your init method wherever you like.


  • Implement in two plugins to identify any flexibility or other pain points
  • Decide on default wording
  • Finish styling all of the input options (we need to apply styles for checkbox toggles, etc...)
  • Decide if any admin notices should be added by default

@ChaseWiseman ChaseWiseman self-assigned this Jul 29, 2018

@unfulvio unfulvio self-assigned this Jul 30, 2018


This comment has been minimized.

Copy link

unfulvio commented Jul 30, 2018

Apart from PIP, I suggest we implement this first with MailChimp Sync. While not exactly a high profile plugin itself, it's where we wanted to implement the wizard initially. But the main reason would be to see how the wizard can interact with an external API in this case (enter MailChimp key, pull lists already, designate one, etc.). If we don't want to choose that, then I'd recommend either Product Reviews Pro or Sequential Order Numbers Pro perhaps, and let the new user pass a few settings within the wizard.


This comment has been minimized.

Copy link

unfulvio commented Jul 30, 2018

@ChaseWiseman I've started playing with this - the abstract looks solid. So far I've a concern to raise about certain gettext strings we use in the Framework. This onboarding Setup Wizard is specifically meant for first time users. We do support some translations in our plugin, but the textdomain of the FW is another thing altogether. I can foresee agencies wanting this translated; some users might be told that the plugin supports their language, but then they open the wizard and they see content in English. So, I think having an onboarding wizard that is easy to translate makes for a much better welcome... Which should be the main goal of having this wizard.

So, what do you think if we move certain translatable strings away from the frameworked abstract and leave those to child implementations that will use their own text domain? We could also make use of getters to retrieve those strings we want to make more accessible and let plugins override those to provide their textdomain versions.


This comment has been minimized.

Copy link

unfulvio commented Jul 31, 2018

@ChaseWiseman I have made a few tweaks to the onboarding wizard and submitted a PR for implementing it into PIP here: skyverge/wc-plugins#2765

The Wizard can be visited at /wp-admin/index.php?page=wc-pip-setup&step=welcome directly (haven't tested it yet on new installs although I'd expect to work if that's handled by FW).

The Setup Wizard will offer 4 steps:

  • Welcome
  • Invoice number generation preferences
  • Enable/Disable Emails
  • Done (finish action with additional steps as defined by FW)

I believe for PIP an important point for merchants is how invoice numbers appear on documents, therefore having the ability to set these as one activates the plugin seems a good UX. The wizard will offer a live preview of what an invoice number will look like:

screenshot from 2018-07-31 17-29-40

For the Emails, on the other hand I am not sure how important is to have them in the Wizard. Nonetheless, I found a problem with checkboxes generation using render_form_field() aka woocommerce_form_field(). It looks like the WC setup wizard CSS will cause the inputs to be moved off screen (9999px away, absolute positioned):

screenshot from 2018-07-31 17-29-52

Unfortunately in the WC onboarding wizard there isn't exactly a checkbox among the steps. There are, but they're heavily customized in the form of toggles. Toggles actually wouldn't be bad for this kind of control (enabled/disable something) but I'm not sure yet how to output those.

What do you think?


This comment has been minimized.

Copy link

unfulvio commented Aug 2, 2018

those toggles look really awesome, thanks!

unfulvio and others added some commits Aug 6, 2018

ChaseWiseman and others added some commits Aug 8, 2018

@ChaseWiseman ChaseWiseman merged commit 90ab62e into master Sep 4, 2018

2 checks passed

continuous-integration/travis-ci/pr The Travis CI build passed
continuous-integration/travis-ci/push The Travis CI build passed

@ChaseWiseman ChaseWiseman deleted the setup-wizard branch Jan 9, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment