Use Setup Tasks to provide a first-class on-boarding experience for merchants

As a plugin author, you’ll often have one or more set up tasks you want to guide your user through to get the most out of your plugin. Two challenges are making sure users see your tasks and making sure they complete them all.

The WooCommerce home screen is a consolidated landing space for users to get their store set up and effectively manage day-to-day operations for their business. Adding setup tasks to the task list alongside the usual setup steps will draw users to complete your tasks and also help them keep track of how far through the setup process they are.

We’ve built the user experience for you, so all that’s left is just to plug your tasks in!

Getting started

In this post we’ll talk briefly about the setup task list and go through the steps to create your own setup task for display in the WooCommerce home screen.

If your extension has a setup task associated with it, you can display it in the task list, this will prompt a merchant to go through important steps required to setup your extension.

screenshot-one wordpress test-2020 12 02-17_01_48

Step 1: Register your task in PHP

The first thing you’ll need to do is register the task on the PHP side. To do this, you’ll need to add your callback to the filter woocommerce_get_registered_extended_tasks.

In PHP it will look like this:

add_filter( 'woocommerce_get_registered_extended_tasks', 'pluginprefix_your_method_to_register_the_task', 10, 1 );

The method to add your task will be like this:

function pluginprefix_your_method_to_register_the_task( $registered_tasks_list_items ) {
    $new_task_name = 'your_task_name';
    if ( ! in_array( $new_task_name, $registered_tasks_list_items, true ) ) {
        array_push( $registered_tasks_list_items, $new_task_name );
    }
    return $registered_tasks_list_items;
}

Step 2 – Add the task in JavaScript.

Next, you have to add your task to the tasks list in JavaScript. To do this, you have to add a filter to woocommerce_admin_onboarding_task_list with your task.

The code will look like:

const myTask = {
    key: 'example',
    title: 'Example',
    content: 'This is an example task.',
    container: <Task />,
    completed: false,
    visible: true,
    additionalInfo: 'Additional info here',
    time: '2 minutes',
    isDismissable: true,
    onDismiss: () => console.log( "The task was dismissed" ),
    type: 'extension'
},

addFilter(
    'woocommerce_admin_onboarding_task_list',
    'plugin-domain',
    ( tasks ) => {
        return [
            ...tasks,
            myTask,
        ];
    }
);

The extended setup tasks will have:

NameTypeRequiredDescription
keyStringYesIdentifier.
titleStringYesTask title.
contentStringNoThe content that will be visible in the Extensions setup list.
containerComponentYesThe task component that will be visible after selecting the item.
completedBooleanYesWhether the task is completed or not.
visibleBooleanYesWhether the task is visible or not.
additionalInfoStringNoAdditional information.
timeStringYesTime it takes to finish up the task.
isDismissableBooleanNoWhether the task is dismissable or not. If false the Dismiss button won’t be visible.
onDismissFunctionNoCallback method that it’s triggered on dismission.
typeStringYesType of task list item, setup items will be in the store setup and extension in the extensions setup.

Summary

In summary you only need to:

Register your task on the PHP side.

Your PHP file should have these things:

/**
 * Register the task list item.
 */
function register_task_item() {
     add_filter( 'woocommerce_get_registered_extended_tasks', 'pluginprefix_your_method_to_register_the_task', 10, 1 );
}

add_action( 'admin_enqueue_scripts', 'register_task_item' );

/**
 * Unregister task.
 */
function pluginprefix_deactivate() {
    remove_filter( 'woocommerce_get_registered_extended_tasks', 'pluginprefix_your_method_to_register_the_task', 10, 1 );
}

register_deactivation_hook( __FILE__, 'deactivate_task' );
Add the component, the filter addition and the task list item configuration on your JavaScript side

And your JavaScript file may look something like this:

/**
 * Create your component that will be visible after clicking the task list item.
 */
const TaskComponent = () => {
    return (
        <p> This is a component </p>
    );
};

/**
 * Configure the task list item.
 */
const myTask = {
    key: 'example',
    title: 'Example',
    content: 'This is an example task.',
    container: <TaskComponent />,
    completed: false,
    visible: true,
    additionalInfo: 'Additional info here',
    time: '2 minutes',
    isDismissable: true,
    onDismiss: () => console.log( "The task was dismissed" ),
    type: 'extension'
},

/**
 * Add your item to the tasks list.
 */
addFilter(
    'woocommerce_admin_onboarding_task_list',
    'plugin-domain',
    ( tasks ) => {
        return [
            ...tasks,
            myTask,
        ];
    }
);

More help

To generate an example of the extended setup task list in your site, you can clone the woocommerce-admin repository and
run this command from inside the root directory:

# This is just to ensure all the needed dependencies are installed.
> npm install
> npm run example -- --ext=add-task

And activate the plugin: WooCommerce Admin Add Task Example.

The code that creates the extension is here.

An extension setup task like below will be created.

In the example, we can find 2 files, a JavaScript file and a PHP one.

The PHP file creates a plugin (named WooCommerce Admin Add Task Example ) that loads the JavaScript file, sets/gets an isComplete variable and registers the new task by adding the filter woocommerce_get_registered_extended_tasks. The method register_task_item will add the new task to the registered extended task list.

In the JavaScript file, there will be: the task list item configuration, a filter to add the new item to the task list, the component that will be shown after clicking the list item and a couple of buttons (in the component) with their onClick methods to modify the isComplete state.

Features

Additional considerations

  • Every task needs to be registered (through the filter woocommerce_get_registered_extended_tasks).
  • Every time a new extension task element is added the list will be shown, even if it was hidden before.
  • The Dismiss functionality will show an Undo snackbar and trigger the onDimsiss callback.
  • The onDismiss prop will be a method that is triggered just after pressing the Dismiss button in the task item.

5 responses to “Use Setup Tasks to provide a first-class on-boarding experience for merchants”

  1. That sounds interesting. If I may, I would like to give some feedback about this:
    1. The article assumes that a developer is familiar with React. Based on my experience, this is not necessarily the case. React has been a fairly recent addition to WordPress, and many developers might not have experience with it.
    2. The article assumes that a plugin can “load its JavaScript”, but it doesn’t say where, or how, that should be loaded. It’s not always possible to generate an example using NPM, therefore it would be vital to understand how to add the JS loading to an existing plugin, which doesn’t rely on NPM.
    3. The article, doesn’t seem to explain how a task can actually be marked as completed. By the look of it, the “task” is just a piece of HTML with instructions, but it’s not clear of it can get “ticked off”.

    Points #1 and #2 are something I already pointed out in reply to the tutorials for the WooCommerce Admin. There seems to be an assumption that WP/WC developers are familiar with Node, NPM, Webpack and React, but I can assure you that this is not necessarily the case. In my (small) circle, of the 27 developers I interviewed, none of them had much exposure to any of the above tools, apart from some “tinkering”.
    I’m the 28th, and, since I’m mostly involved in backend development and system integrations, I don’t work much on user interfaces. Due to that, I rely mostly on jQuery when I need to add some element on a page, and I wouldn’t know where to start with React. In comparison, the old approach of using add_action() and printing out the HTML directly was far easier (not very clean, I know).

    Bottom line: some guide like “getting started with React & co in WooCommerce”, would be really useful. In fact, I think it’s definitely needed, especially for a key aspect like updating existing code. Developers can’t rely on scripts that generate stuff automatically, when their code already exists, so they need to know how bring it up to speed, without going by trial and error (done already, it took ages). 🙂

    Bonus points
    As an additional, personal note, I would be happy to see TypeScript examples as well. I don’t use JavaScript, because I can’t get my head around it (and, personally, I hate functional programming). TypeScript is just as standard in Node and NPM, and can easily be used with React, therefore I think it would be worth taking it into account. I’m aware that one can copy/paste JS into TS, but that’s not really helpful. 😁

    1. baconscoutsinc Avatar
      baconscoutsinc

      Agreed. WooCommerce development is getting significantly more complex, and I applaud the new features, but it can be difficult to keep up if these things are not already in your wheelhouse.

    2. Thank you so much for this comment, it’s well reasoned and I totally agree with your points about general React exposure in the Woo/Wordpress community.

      This is not something we’re totally unaware of either. It’s a big topic to cover, but I agree with you that a “getting started with React & co in WooCommerce”, post would be really worthwhile and I’ll definitely start some conversations about this.

      As an additional, personal note, I would be happy to see TypeScript examples as well. I don’t use JavaScript,

      This is interesting to me, because much like React I would have expected TS to be a barrier to Woo/WP dev’s who have spent a lot of their front-end time writing jQuery. If we could somehow provide code examples where you could toggle between TS and JS though I imagine this could be very useful.

      1. I used, and still use, jQuery quite a bit. However, as soon as I focused on learning TypeScript, it took me no time at all to get used to it. In fact, I wrote a full service worker on CloudFlare, entirely in TypeScript, with a 99.8% test coverage (the gap is due to the lack of suitable mockups in the testing library), in two weeks, starting from scratch. I find it a far more productive programming language than JS and, in many ways, PHP.

        In fact, I’m slowly changing all my PHP code to typed code, whenever and wherever I can, as long as it doesn’t break anything.

        I have to clarify that I’m a OOP and SQL developer. I learned programming with strictly typed languages like Delphi and moved to C# before “landing” in the PHP world, and, even then, I followed OOP as much as I could. Functional programming is as attractive to me as a Habanero facemask. The latter makes me cry less. 😁

        As of today, the hardest obstacles for me remain React (I’m not a frontend or UI developer, at all) and getting the most out of Node, Webpack and the rest of the “collateral” tools. It’s a difficult task to update everything, especially when one has to maintain full backward compatibility as well.

  2. […] One of the new features on the WooCommerce Admin home screen is the Setup Tasks component. Take a look at this tutorial we published on how to add your own setup tasks. […]

Leave a Reply

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