Provide a framework for plugin onboarding experiences

[jorbin]

Building off conversations happening in #60992, there is an opportunity for core to provide a framework that is more advanced that the existing register_activation_hook

By framework, I mean a set of hook and potentially broader functionality for plugins to use. I think plugins will still need to figure out what this means for that, but providing a consistent route to enter this will benefit the users of Core.

[kevinwhoffman]

Can I suggest that we frame this problem as "plugin configuration" rather than "plugin onboarding"? Not every plugin that allows for configuration has a distinct onboarding experience, and the need to discover where configuration takes place is not limited to right after activation.

If we can establish a framework for plugins to communicate where configuration takes place, then core can use that value in ways that improve not just onboarding, but the more general problem of discoverability when it comes to understanding all of the possible places where plugins can be configured.

[jeherve]

Replying to kevinwhoffman:

Can I suggest that we frame this problem as "plugin configuration" rather than "plugin onboarding"? Not every plugin that allows for configuration has a distinct onboarding experience, and the need to discover where configuration takes place is not limited to right after activation.

I think that's a good point. Many plugins "only" register a Custom Post Type for example, and linking to the CPT menu after installation would make sense in my opinion, it's the logical next step for the site owner, even if no "onboarding" needs to happen.

[poena]

Adding that the need for onboarding is not limited to plugins, there is a high need for better onboarding for themes.

[jason_the_adams]

Replying to kevinwhoffman:

Can I suggest that we frame this problem as "plugin configuration" rather than "plugin onboarding"? Not every plugin that allows for configuration has a distinct onboarding experience, and the need to discover where configuration takes place is not limited to right after activation.

I want to be careful not to generalize this too much. For many plugins the onboarding is a rather critical step in the process. For me "configuration" implies adjustment, while onboarding is more like installation.

Right now a plugin is simply activated in WordPress. You click "activate" and now it's running. But think about software, where installation is not simply whether it exists on your machine or not, but setting up the initial configuration necessary for it to function properly.

Some examples of this:

• Setting up a payment gateway for a donation plugin
• Providing SSH/FTP credentials for a backup plugin
• Selecting security preferences for a security plugin (to prevent problematic defaults)

I like the idea of having a way for folks to know how to go configure a plugin further after installation (e.g. changing the "Activate" button to "Configure"), but want to make it clear that many plugins move users on redirect to onboard not just because it's useful.

[kevinwhoffman]

In Post Status, @afragen asked for more details about my "Configure" link proposal originally posted in ticket:60992#comment:53, so I'll copy my response here for transparency:

Given that different plugins can live in different areas of WP Admin, I don’t think core can possibly apply a standard “Configure” link to all plugins, so each plugin would define its own “Configure” link. Possible methods of definition include a Configuration field in the plugin header or a hook provided by core. I imagine the value would be a path relative to /wp-admin such as /admin.php?page=wpseo_dashboard#top#first-time-configuration for Yoast SEO. This allows the configuration page to work on sites where WP Admin is in a non-standard location.

Examples:

• For plugins like WooCommerce, Yoast SEO, and GiveWP which have first-time onboarding experiences, the “Configure” link could be set to the onboarding wizard.

• For plugins like ACF that do not have a first-time onboarding experience, the “Configure” link could be set to the Fields Groups page which provides some guidance through an empty state panel.

• For plugins like Hello Dolly with no standalone plugin pages, the “Configure” link can be left undefined and the existing disabled “Active” button can be displayed.

It’s important to emphasize that the “Configure” link should be timeless; it should always allow you to configure the plugin, whether it is immediately after activation or 30 days later. If a user clicks “Configure” some time after completing the onboarding experience, then the plugin should recognize this and redirect them to an appropriate settings page (similar to what happens when you skip an onboarding wizard). Yes, plugins with onboarding experiences would still use a redirect, but the difference is that the plugin determines where it’s best to send the user after the user has signaled an intent to configure the plugin. The user makes the choice, and the plugin responds.

Historically plugins have felt the need to redirect based on an activation hook because there was no other reliable convention in place to direct a user to what’s next after plugin activation . With a prominent “Configure” link in key areas of WP Admin, plugin developers can rely on it as the funnel into plugin configuration and move away from relying on post-activation redirects.

[costdev]

For me "configuration" implies adjustment, while onboarding is more like installation.

But think about software, where installation is not simply whether it exists on your machine or not, but setting up the initial configuration necessary for it to function properly.

I think that's where "configuration" and "initial configuration" don't need to be differentiated by a Core feature, but rather by a plugin detecting whether the user has done an initial configuration yet. I see onboarding as what you see at the "first launch", and the detection/content there is typically done by the application (read: plugin), not the OS (read: WordPress). Thinking along the lines of mobile apps in that regard, rather than desktop installers.

Given that onboarding/initial configuration should have multiple entry points (since plugins can be installed and activated several ways), it seems reasonable to expect that feature-complete onboarding would include state management via an option or transient (like WooCommerce does with _wc_activation_redirect).

---

I'd like to determine the extent to which such a framework might go. For example, do we want to do more than something like this? If so, what are your ideas?

1. Add a '{$plugin}_configuration_url' filter hook.
   1. Plugins can decide whether this goes to an onboarding/initial configuration URL, or a settings page. Or even go to the same URL and perform state checks before/after the page loads.
2. If filtered:
   1. Plugins > Add New: Replace the Active button with a Configure button in the plugin's card.
   2. Modals: Replace the Active button with a Configure button in the modal's footer.
   3. Plugins > Installed plugins: Add a Configure action link in the plugin's row.

Though we're discussing plugins at the moment, if we were to extend this to themes now or in future: {$theme}_configuration_url and either a button, or an extra link in the "New theme activated. <a>Visit site</a>" admin notice post-activation.

And now that I've typed this, Kevin just posted, so I'm going to post this and now scroll up to read what Kevin wrote. 😆

[costdev]

@kevinwhoffman I agree with everything you said - On hook vs plugin header, I'd lean towards a filter hook because the plugin author should be able to decide whether to point it to a URL which determines whether to show onboarding vs settings, or to have separate URLs and conditionally return one of them in the filter's callback.

[kevinwhoffman]

Replying to costdev:

I think that's where "configuration" and "initial configuration" don't need to be differentiated by a Core feature, but rather by a plugin detecting whether the user has done an initial configuration yet.

Well said, we're on the same page here. Configuration is always possible, but the nature of the configuration depends on what has already been done (or not).

On hook vs plugin header, I'd lean towards a filter hook because the plugin author should be able to decide whether to point it to a URL which determines whether to show onboarding vs settings, or to have separate URLs and conditionally return one of them in the filter's callback

Agreed, a filter would be more powerful. I initially liked the simplicity of a plugin header field, but conditional scenarios could be handled much better through a filter. It's also worth noting some of these onboarding URLs can look pretty funky, so including a partial path in the plugin header would likely confuse new developers who don't know exactly what it's for.

[alanfuller]

In terms of user expectation on activate, @kevinwhoffman expressed an opinion that user don't expect activate to actually activate an onboarding or redirect to settings.

I argue that in fact they do.

Most users now are used to apps on phones, in fact many users refer to plugins as apps. With an app from an app store there is a two stage process, install and open. The open activates the intial onboarding like create an account and set up wizard.

I feel this is something that needs to be examined in detail with some real user feedback, rather than the opinions of a couple of people for and against.

I apologize if extensive research has already been done, and if so can we have a link to it?

My opinion is just my opinion, but having used 6.5 heavily I have formed a personal opinion about the lack of auto refresh, regardless of onboarding or not, feels horrendous, I am a plugin developer and know fully about this issue yet every time I add a plugin, which is multiple times a day my gut 'expects' to find the items on the dashboard and my 'gut' panics and thinks something is broken.

I appreciate the efforts looking into this.

[jeherve]

Replying to costdev:

@kevinwhoffman I agree with everything you said - On hook vs plugin header, I'd lean towards a filter hook because the plugin author should be able to decide whether to point it to a URL which determines whether to show onboarding vs settings, or to have separate URLs and conditionally return one of them in the filter's callback.

Would a hook be a viable option here? As long as there hasn't been a page refresh the plugin's code hasn't run, so any functions defining an onboarding/configuration URL would not be available yet, at least from what I can tell.

The plugin header option would allow us to work around that limitation.

[alanfuller]

I was just about to say Plugin Header might be a way to go, but also need to think about localization. I guess the 'polygots' scan could be modified to add a plugin header string by meta - not sure how complex.

[alanfuller]

We also could get really funky and have a plugins.json in the root that is rather like blueprint.json with steps - just a random thought.

[costdev]

Would a hook be a viable option here? As long as there hasn't been a page refresh the plugin's code hasn't run, so any functions defining an onboarding/configuration URL would not be available yet, at least from what I can tell.

Yeah it works because activate_plugin() calls plugin_sandbox_scrape() which loads the main plugin file, which is where I would imagine we'd advise plugin authors to put it. It's a configuration thing, so I wouldn't recommend someone puts it behind an init hook. Options/Transients should already be available if they want to base their URL on the value of one.

---

For fellow "lemme try" people:

1. Enable WP_DEBUG and WP_DEBUG_LOG.
2. Go to Plugins > Add New and install WooCommerce. Do not activate it yet
3. Modify woocommerce/woocommerce.php to add this after the ABSPATH bail:

   add_filter(
           plugin_basename( __FILE__ ) . '_configuration_url',
           function () {
                   return admin_url( 'admin.php?page=wc-admin' );
           }
   );
   

4. Modify wp_ajax_activate_plugin() (in src/wp-admin/includes/ajax-actions.php) so it ends with the following:

   // Add these two lines above the call to wp_send_json_success().
   $configuration_url = apply_filters( $status['plugin'] . '_configuration_url', '' );
   error_log( $configuration_url );
   
   wp_send_json_success( $status );
   

5. Activate WooCommerce and check wp-content/debug.log.

[kevinwhoffman]

Refreshing vs. Redirecting

As soon as a plugin is activated, any presence that it has in the WP Admin UI should instantly be reflected without further action required by the user. This primarily includes items appearing in the admin menu and admin bar, since those elements are likely visible in the viewport when activation occurs. A user who has already clicked "Activate" should not have to take yet another action to see the results of said activation.

Ideally updating the UI would happen without a page refresh, but if a refresh is necessary, I think it's acceptable to reload the current page in order to update the UI. The risk with refreshing the page in order to update the UI is that plugins using the activation hook for onboarding redirects will then take over. I believe this is one of the primary reasons why the auto-refresh was removed in the first place. Perhaps this is a challenge better left to the wider effort of updating WP Admin as I imagine the admin menu and admin bar will change significantly.

WordPress should avoid redirecting to a completely separate plugin onboarding experience as a result of pressing "Activate." Onboarding is configuration, not activation. An "active" plugin has an established meaning in WordPress that we should honor. Active does not mean that the plugin is fully configured and ready to do its job; it simply means that the plugin code is active on the site. WooCommerce, Yoast SEO, and GiveWP can all be "active" without having to open or complete any of their onboarding wizards.

The iPhone App Store as an analog

If we're using the iPhone App store as an analog, then pressing "Get" in the app store is the equivalent of pressing both "Install" and "Activate" on the WordPress Plugins screen. At the end of that process, you've got an app/plugin on your phone/site that is now active and available to use. It is not necessarily configured and ready to do its job.

In order to actually experience the phone app, you tap the "Open" button which appears in place of the "Get" button. In WordPress, this would be the equivalent of pressing the proposed "Configure" button that takes the place of the "Activate" button in the plugin card.

So while it's valuable to consider popular conventions like the App Store when deciding how similar experiences should work within WordPress, we need to be aware that there is not an apples-to-apples comparison. WordPress considers "Install" and "Activate" to be two separate steps whereas the App Store uses a singular "Get" action to accomplish both steps.

[afragen]

Replying to costdev:

4. Modify wp_ajax_activate_plugin() (in src/wp-admin/includes/admin-ajax.php) so it ends with the following:

This is actually in src/wp-admin/includes/ajax-actions.php 😉

[afragen]

Replying to costdev:

Would a hook be a viable option here? As long as there hasn't been a page refresh the plugin's code hasn't run, so any functions defining an onboarding/configuration URL would not be available yet, at least from what I can tell.

Yeah it works because activate_plugin() calls plugin_sandbox_scrape() which loads the main plugin file, which is where I would imagine we'd advise plugin authors to put it. It's a configuration thing, so I wouldn't recommend someone puts it behind an init hook. Options/Transients should already be available if they want to base their URL on the value of one.

---

For fellow "lemme try" people:

1. Enable WP_DEBUG and WP_DEBUG_LOG.
2. Go to Plugins > Add New and install WooCommerce. Do not activate it yet
3. Modify woocommerce/woocommerce.php to add this after the ABSPATH bail:

   add_filter(
           plugin_basename( __FILE__ ) . '_configuration_url',
           function () {
                   return admin_url( 'admin.php?page=wc-admin' );
           }
   );
   

4. Modify wp_ajax_activate_plugin() (in src/wp-admin/includes/admin-ajax.php) so it ends with the following:

   // Add these two lines above the call to wp_send_json_success().
   $configuration_url = apply_filters( $status['plugin'] . '_configuration_url', '' );
   error_log( $configuration_url );
   
   wp_send_json_success( $status );
   

5. Activate WooCommerce and check wp-content/debug.log.

debug.log output from above

[26-Apr-2024 17:45:35 UTC] http://xxxx.test/wp-admin/admin.php?page=wc-admin

[annezazu]

I can't speak to the technical aspects of this work but, thinking ahead to phase 3 and the admin redesign, I'm curious what can be done to build this/present this in a future proof way with the new efforts in mind. It could offer a great stress test with what's being thought of currently. Here's the broader overview issue on the admin redesign for context: ​https://github.com/WordPress/gutenberg/issues/53322

[jason_the_adams]

It seems like the question as to whether pressing "Activate" should load an onboarding experience keeps coming up. I feel like we're trying to find a one-size-fits-all solution as our answer to this question — as we consider things like WP-CLI, remote installation, bulk activation, and so forth. I think that's a mistake.

Consider this one scenario:

1. I download GiveWP
2. I install GiveWP
3. I click "Activate" for GiveWP
4. I'm redirected to onboard GiveWP

That's how it's worked for years (and for many other plugins), and I've never heard of a user describe this as confusing behavior. I think it's a mistake to mess up this UX in the name of it having technical difficulties (e.g. it's done by hijacking the redirect).

That's why I'm a fan of this form registration flow. Depending on the scenario, WP can provide the best UX for the user. Something like:

• Activated one plugin: Redirect them
• Activated many plugins: Display an admin notice
• Activated via WP-CLI: Nothing? Perhaps show the URL to finish configuration at
• Activated remotely: Return the URL

One other scenario we may want to consider here is perhaps giving the plugin the ability to prompt whether onboarding is necessary. If a user activates, completes the onboarding, deactivates, and then activates again, it's not necessary for them to onboard. Perhaps this is implicitly accomplished by not providing an onboarding URL unless it's necessary?

[jason_the_adams]

Replying to annezazu:

I can't speak to the technical aspects of this work but, thinking ahead to phase 3 and the admin redesign, I'm curious what can be done to build this/present this in a future proof way with the new efforts in mind. It could offer a great stress test with what's being thought of currently. Here's the broader overview issue on the admin redesign for context: ​https://github.com/WordPress/gutenberg/issues/53322

If we get this configuration right, I'm hopeful it will better set plugins up for Phase 3, as we'll at least have a formal way for the new design to identify whether a plugin has an onboarding UI and where the user ultimately needs to go to complete it.

[costdev]

Activated one plugin: Redirect them
Activated many plugins: Display an admin notice
Activated via WP-CLI: Nothing? Perhaps show the URL to finish configuration at
Activated remotely: Return the URL

One issue is that on Plugins > Add New, there was no way to allow a user to activate multiple plugins if a redirect occurred. Differentiating "one plugin" from "many plugins" on Plugins > Add New requires preventing the redirect takeover.

Note that by "multiple plugins", I refer to the following two scenarios:

1. Clicking the Activate button in multiple plugin cards.
2. Clicking Activate within the modals for each of a plugin's dependencies, then the Activate button in the dependent plugin's card.

I've seen in some places that there's a belief that users don't install multiple plugins from this screen (I'm not attributing this to you though), which is not quite correct. It's common for a user to have installed an addon for say, WooCommerce, then activate it, only to receive a notice to go back to Plugins > Add New to install and activate WooCommerce. This is one of the scenarios that the Plugin Dependencies feature targeted, and so the concept of installing/activating multiple plugins from this screen, while not new, is more apparent now.

The previous flow as detailed above was both frustrating and confusing to users (I've witnessed this a lot with clients and received emails asking for clarification). Even though things are different now without the redirect, I'm confident that we're all going to produce a more balanced result that will cover more use cases in a way that's straightforward for users.

Regarding WP-CLI based installation/activation: This may be done as part of a one-click setup where the user can select a list of plugins. These can also often be installed and activated on existing site, depending on the tool used, and can use WP-CLI. I think if a configuration URL is provided, we should consider how we might serve this information to users who haven't yet loaded the WordPress admin since activation. This may be a single admin notice on Plugins > Installed plugins, or something else. This would likely need to some further thought and discussion, but should be kept in mind as we look at the various activation methods.

[costdev]

@annezazu I think that at the moment, the technical details amount to a filter for plugin authors (and either at the same time or later, theme authors) to provide a configuration URL. In the current UI, replacing the Active button in plugin cards and adding a Configure link in plugin rows is consistent with existing patterns in these areas of the WordPress admin.

From what I've seen of the admin redesign project so far, I would imagine a configure button would be provided for plugins and themes in the new UI, which would use the same configuration URL provided by such a filter. So from a "build this in a futureproof way" perspective, I think we've got that same mindset.

From a "display this in a futureproof way" perspective, I think we're going to inevitably have some big differences in how things are displayed between the current UI and the redesign. I haven't seen any early mockups of how the plugin and theme screens would display in the new admin. I think I'd need to see a general layout for these screens to theorise further on this, but my intention with this work would be to follow existing patterns so that when the redesign transitions existing patterns to new ones, the work done here would be transitioned in the same way.

[kevinwhoffman]

Replying to jason_the_adams:

It seems like the question as to whether pressing "Activate" should load an onboarding experience keeps coming up. I feel like we're trying to find a one-size-fits-all solution as our answer to this question — as we consider things like WP-CLI, remote installation, bulk activation, and so forth. I think that's a mistake.

Consider this one scenario:

1. I download GiveWP
2. I install GiveWP
3. I click "Activate" for GiveWP
4. I'm redirected to onboard GiveWP

That's how it's worked for years (and for many other plugins), and I've never heard of a user describe this as confusing behavior. I think it's a mistake to mess up this UX in the name of it having technical difficulties (e.g. it's done by hijacking the redirect).

Yes, the redirect method has been used for years, but it doesn't mean it's right. Having prototyped the original GiveWP onboarding wizard, I think the redirect method was a mistake. At the time, we were following the lead of large plugins like WooCommerce and Yoast. In doing so, we perpetuated the unpredictability of the "Activate" button.

Now when a new user installs a plugin, they have no idea whether the "Activate" button will simply activate the plugin or redirect them to an entirely different page.

Consider this scenario, which is the default behavior for a WordPress plugin:

1. I download ACF
2. I install ACF
3. I click "Activate" for ACF
4. ACF is simply activated like the button suggests, and nothing more

That's different behavior compared to GiveWP, but how would you know what to expect?

Imagine if clicking "Get" in the App Store caused some apps to open immediately, but there's no way of telling which apps will do that until you try them. That's what the redirect experience is like for new users of each WordPress plugin.

With the changes to AJAX plugin activations, the redirect method creates even more unpredictability. Now if I click "Activate" and then try to go anywhere else in WP Admin, I'm going to be redirected to that plugin's onboarding experience regardless of whether I'm trying to view my Posts, Pages, Tools, Settings, etc.

The proposed filter and "Configure" link would restore some consistency to the plugin activation experience while still giving plugins with first-time onboarding experiences a clear method of directing users to their preferred next step. We could even consider making the "Configure" text filterable by plugin developers so the button can say "Start Onboarding," "Continue Onboarding", etc. based on the configuration that's been done so far. That's the type of clarity and control that I hope this framework can offer to developers and users alike.

[alanfuller]

Replying to kevinwhoffman:

Imagine if clicking "Get" in the App Store caused some apps to open immediately, but there's no way of telling which apps will do that until you try them. That's what the redirect experience is like for new users of each WordPress plugin.

The App Store analogy is a relevant one, as the vast number of users are accustomed to it. However, App Stores only have two steps: Install and Open. Opening the app includes onboarding in most cases.

Additionally, App stores don't support multi-dependency installs.

So, if the objective is to redesign for the most user-friendly experience (ignoring technical limitations at this stage), in my opinion, for a plugin with no dependencies, on the ADD page, there should be a two-step process: Install and Open. Opening technically activates and runs the plugin, including any onboarding. For plugins with dependencies, the flow should be Install, notify users of dependencies, and give them an opportunity to install. When all dependencies are met, the plugin should Open, running a plugin configured within the dependency setup to be the master, with whatever onboarding is defined in the master plugin.

Now, my second point: This is just my opinion on what users want. In a commercial world, we would gather user requirements through various methods beyond those that participate in trac discussions. (But I do assume App Stores have rather worked out the simple use case.)

[smub]

I appreciate the core team working to add a Refresh button in #60992, but I feel this is adding extra friction and complexity for beginners / non-techy users.

One of the best parts about WordPress is that we have always prioritized in building for the 95% but unfortunately in this situation, we have regressed in our values and are catering to the needs of 1% at the expense of adding friction and complexity for the larger user base.

Based on my experience working with beginner users, vast majority of users and site owners DO NOT bulk install plugins and most don't have a clue of what WP CLI even is.

Heck installing even a single plugin and configuring it to work properly is a tall order for many.

This is why a guided onboarding wizard, some sort of visible walk through, tooltips or admin notice is needed immediately to help the user Get Started. It also has to be prominent enough, so a new user who's not familiar with the UI of WP admin can identify what they should do next.

All of this is fairly normal behavior in mobile apps, SaaS platforms, and frankly most other software that's built today. When you first get a New Mac, you have an onboarding wizard. It doesn't require you to refresh a screen or click a button to see what you'll be greeted with next. Getting a new Mac is similar to setting up a new website.

When you install plugins on your Mac (i.e Dropbox or another extension), it's done ONE at a time -- most normal folks / beginners don't multi-task in the way a Pro user might. And as you'd expect, any app that you install, in this example Dropbox will open up a guided setup wizard (which in plugins we call onboarding wizards). This ensures that your computer can sync to the cloud and your files are secure.

This is the behavior that any user who uses any type of modern technology has come to expect. Most folks DO NOT use the command prompt, and GUI exists for a reason -- to make technology accessible to all.

It's completely normal and I'd say expected from the majority of users (who are non-techies) that when they install a plugin like WooCommerce or another, that they are immediately taken to the NEXT step like we used to, so they can accomplish the job that needs to be done (i.e add a store to their site). We need to learn from the Jobs to Be Done Framework here.

IMO as the first step, it'd be better for us to REVERT to the old way where the activation allows the plugins to trigger the onboarding wizard vs. requiring a user action of any sort (like it was done before).

Yes in the short-term, this breaks the dependency challenge which is of course an important concern. I know this because Thomas at AM built TGMPA library, but in an attempt to fix a problem that's small on a relative scale, we're creating a much bigger problem right now which affects the ease of use of the most critical aspect of the WordPress platform (plugin ecosystem).

Long term, it would be ideal for us to think of a solution that looks at plugin installation and activation with different jobs to be done framework / use-case in mind. For example, we should think about bulk activation experience differently because bulk activation is the smaller use-case here ... and perhaps we can allow plugin authors a function / way to deal with a different type of experience for "Power Users" who are performing bulk tasks on sites. Along the line, we can think of a different filter / hook for dependency plugin user experience / flow. Batching all plugin installs & activation as one user experience is akin to taking an hammer and treating every problem like a nail.

We need to work together and uphold the values that made WordPress as good as it is today by ensuring that we always prioritize the needs of 95% and that ease of use for non-techy / avg. user remains central in every decision that we make. We're doing this in many areas of the WordPress project right now such as the Block Editor which is bringing the project forward as well as the Data Liberation initiative, but unfortunately in this plugin activation scenario we have seen regression. We shouldn't be afraid to undo / rollback to fix the problem we introduced vs. settling for a less than ideal solution.

[costdev]

The biggest issue I'm seeing is that we're yet to reach a common agreement on the following:

1. Beginner users DO install multiple plugins every time they install an addon before they have its dependency, whether that's WooCommerce, Yoast SEO, Gravity Forms, or any other highly extended plugin.

We have all likely worked with a lot of users of various demographics, yet there is disagreement amongst us. This should serve as a reminder that we should avoid extrapolating our personal experiences to represent percentages of users who do X or Y.

We need data, which should be gained by #outreach, and should avoid a tone of "do you want this, or just want it to go back to before?", as that approach risks people opting for negatives just because they've learned to deal with them.

2. Whether or not it's confusing to add a Configure/Get Started button to the flow.

This button would be in the same place as the Activate button they just clicked, which is in the same place as the Install Now button they clicked previously. It's an extra click, but being in the same place as the previous buttons means it's much less likely that a user won't find it.

This not only adds back user control over what happens next, but also ensures that dependencies can be installed and activated before their dependents (note: dependencies are not "nice-to-haves". They are prerequisites much like WP/PHP versions). Furthermore, it provides a consistent entrypoint for plugin and theme authors via a filter that can also be used by the admin redesign for a future Gutenberg-based plugin management screen.

---

I'd ask that rather than pushing for a revert, which has a wider impact than forced redirects, that we instead get data from a project-led outreach program so that we can build on what we have for users and for the project's future plans for these administration areas.

The outreach should be mindful of context: WordPress Core is and isn't like other software, such as Install + Activate being different steps, we don't bypass user consent and control by bulk installing/activating dependencies, we must be transparent by ensuring they can view details of a dependency before they consider installing and activating it, and the dependencies often appear within the same directory as their dependents (except for non-dotorg hosted plugins).

[jorbin]

The question I keep coming back to in my head is "why are plugins so complicated that they require complex onboarding or configuration experiences?" And for these complex plugins, are they the experiences that core should be designing for rather than encouraging smart defaults and things that just work.

[smub]

Replying to costdev:

The biggest issue I'm seeing is that we're yet to reach a common agreement on the following:

1. Beginner users DO install multiple plugins every time they install an addon before they have its dependency, whether that's WooCommerce, Yoast SEO, Gravity Forms, or any other highly extended plugin.

We have all likely worked with a lot of users of various demographics, yet there is disagreement amongst us. This should serve as a reminder that we should avoid extrapolating our personal experiences to represent percentages of users who do X or Y.

We need data, which should be gained by #outreach, and should avoid a tone of "do you want this, or just want it to go back to before?", as that approach risks people opting for negatives just because they've learned to deal with them.

First, I want to say that we're on the same side here. I absolutely agree with you about the importance of a plugin dependency system. We have many WooCommerce extensions in our business like FunnelKit, Advanced Coupons, etc where people may install our Woo extension plugin without realizing that the main Woo plugin is needed, and I would love nothing more for a better UX flow for this.

However given the collective experience of people that are in this thread, I think it's safe to say (even without specific data) that far more users install a standalone plugin vs. one that has dependency on another. Of the top 20 plugins with most active installs, all are standalone. In the top 100, only 8 plugins have dependency on either Elementor or Woo.

Introducing plugin dependencies in core was done with the best of intentions, and I am all for it. But an important aspect (plugin onboarding) was overlooked perhaps, and this is leading to a less than ideal user experience for a much bigger audience than the one that were affected by dependencies.

In the new flow, the screen doesn't reload, so the beginner user has no idea what to do next. There's no new plugin menu added and the wizard doesn't trigger either since the page doesn't refresh. IMO this leads to a far more confusing user experience for beginners.

Andrew Palmer made a good video here: ​https://twitter.com/arniepalmer/status/1779802587644002461 and I do agree with his sentiment.

Guided setups are a positive for the ecosystem because it helps with the ease of use of the platform. It empowers the non-techy user to build their website and take advantage of the full power that WordPress ecosystem offers through plugins. Adding friction here will hurt the overall growth of the platform as beginners are more likely to give up than the Pro Users when they get stuck.

I'm only suggesting a revert here because there's no clear path or timeline that would address the regression that's introduced with the well-intentioned plugin dependency feature.

Regression / bugs are natural part of software. We should embrace them as a learning opportunity to improve, and more importantly we shouldn't be afraid to revert to what was working especially if the new feature introduces challenges / friction that drastically alters an important workflow / aspect of the platform.

Replying to jorbin:

The question I keep coming back to in my head is "why are plugins so complicated that they require complex onboarding or configuration experiences?" And for these complex plugins, are they the experiences that core should be designing for rather than encouraging smart defaults and things that just work

Aaron, I definitely love plugins that do one thing and work without any settings like my ​Missed Schedule Post Publisher plugin. And I too reflected on the same question -- has WordPress just gotten more complex than when I started using it in 2006 that we now need onboarding wizards / guided user flows / etc?

The answer that I came to was No - not really. WordPress itself hasn't gotten more complex. We as a platform and community have leveled up and raised the bar on what we expect to deliver to users in terms of User Experience and Ease of Use, so that we can continue to make WordPress more accessible for the larger non-techy world.

In 2009, we thought it was fine to build Menus with Page Order attributes. Then we as a community raised the bar and added drag & drop menu, and fast forward to today, now we're working towards an amazing Full Site Editing experience.

We should continue to raise the bar as a platform / community and build solutions in Core that helps others in the community to raise the bar for the larger user base.

According to W3Tech, WooCommerce is being used on 13% of all websites that use WordPress, and I think we can both agree that it's no comparison to my simple Missed Schedule Post Publisher plugin.

Not only does WooCommerce needs all the settings / features it has to rival with proprietary platforms like Shopify, a guided Onboarding Wizard is absolutely needed to provide users with the instructions to properly setup arguably the most important aspect of their website (the Ecommerce / payment features) -- and yes Core should have mechanisms built to support plugin authors like WooCommerce, Easy Digital Downloads, GiveWP, Yoast, AIOSEO, etc that are helping drive adoption of WP to the wider market.

I am a big believer in decisions over options and smarter defaults, but in scenarios of powerful plugins that offer the flexibility, a guided wizard / workflow is needed for non-techy users to find the value ... and not get frustrated with WP leading to switching to Squarespace or Wix.

I would love to get your input on how to simplify the payment setup, business default settings like address, etc with smarter defaults. Perhaps we can grab a coffee at WCEU or WCUS because I personally want to learn from your experience and continue to raise the bar on onboarding experience of our plugins.

[chrisbadgett]

Onboarding is different from configuration in my view. Configuration is more like a synonym for settings which most plugins have a link for in the admin and on the plugins list view.

I believe onboarding is more like the "first run" experience immediately on activation of new software. First run onboarding is a critical window of time for new users to customize key settings, input the most important data, and choose to install required elements requiring consent.

"Get Started" is better messaging in my view to make it clear that we need to start for the first time and can trigger first run onboarding flows.

I do like the challenge for smarter defaults and am thinking about how we can improve here. But also some experiences are helpful to the user, beyond smart defaults, with a customizable onboarding flow like when you first turn on a new Macbook Pro and immediately enter a wizard.

I also understand how some web hosts and developers wish to install multiple plugins from repositories at once without setting them up through a wizard. In this case we could benefit from the end user knowing they still need to "Get Started" with the plugins and themes that have skipped the first run onboarding.

[kevinwhoffman]

While the plugin dependencies feature may have shined a light on the problems associated with unpredictable redirects, let’s not make this about catering to plugins with dependencies versus plugins without dependencies. Plugins without dependencies will always be in the majority.

Instead let’s consider that we have an “Activate” button in WordPress core that behaves differently depending on which plugin is installed and has no way of telling the user what it will do until the button is pressed.

Arguments against redirects are not arguments against onboarding. All of the following can be true at once:

• First-time configuration through onboarding experiences has become a staple of modern application workflows that users have come to expect and depend on within certain products.
• Buttons that look the same, have the same ”Activate” label, and appear in the same location within the plugin card component should not behave differently from one plugin to the next.
• Redirects that take away control from the user and force them into an onboarding experience when trying to go literally anywhere else in WP Admin are not a pattern we should continue to encourage.

Again if we’re going to compare plugin activation to app activation, then make sure we’re comparing analogous parts of the workflow. If you downloaded the Dropbox app and it opened automatically while downloading the Spotify app just left in place, then you’d have an analogue for some plugins opening themselves through redirects while others do not.

[alanfuller]

Replying to jorbin:

The question I keep coming back to in my head is "why are plugins so complicated that they require complex onboarding or configuration experiences?"

It is not that they are becomming more complex it is because the user base is becoming less technical and expect more online assistance. Years ago one of my plugins had a settings page with an API key and users were happy to read installation instructions on the read me. Today a large majority find that too difficult ( based on support requests ) and now they have an 'onboarding experience' to guide them to find an API key and input that.

[alanfuller]

Replying to kevinwhoffman:

Arguments against redirects are not arguments against onboarding.

I agree that they are two different things, the issue is today the only way to reliably start a onboarding experience is to detect that the onboarding hasn't happened and redirect.

The purpose of this ticket in my mind is to provide a reliable and consitent and easy for plugin developers to use framework for plugin onboarding experiences. Right now there is little choice.

If you downloaded the Dropbox app and it opened automatically while downloading the Spotify app just left in place, then you’d have an analogue for some plugins opening themselves through redirects while others do not.

Agree no one wants that, but unless I'm mistaken,there is no (defined at install) dependency between DropBox and Spotify. In WP multiple dependent activation needs a relatively complex configuration so the 'correct' onboarding experience happens.

[jason_the_adams]

I think @chrisbadgett did a great job of expressing what are my thoughts as well. Smart defaults and the like an excellent part of building a great UX, but not the only piece. Introducing a new user to an application through an easy-to-use walkthrough that caters to their needs, technical abilities, and so forth helps a user to get maximum value in minimum time and effort — which is the ultimate goal of onboarding.

As @costdev relayed in his response to me, there's certainly a lot of nuance in the various methods of activating plugins in WordPress. That's entirely fine. I think the important thing for WP to recognize is that many major plugins, including WooCommerce, do have a dedicated onboarding page that it's ideal for the user to go to after activation. Frankly, WordPress itself does exactly this after a major update is released. I don't see any reason to debate this, as WP and many plugins have poured so much research into validating the value for the user — otherwise, we wouldn't do it.

This brings me to two points of effort:

1. Providing a simple API for a plugin to optionally provide its onboarding URL, and whether the onboarding still needs to happen.
2. Determine the best way for WP to relay this to the user in the given contexts.

I'd be fine with WP locking down the redirects and other portions of the installation flow if it meant onboarding was a first-class consideration. That's the only reason I've personally known for plugins to get involved in the activation flow, and agree it can result in a poor UX.

Regarding dependencies, I'd be fine with this being the responsibilities of the plugins to determine if they have what they need in order to direct the user to onboarding. I don't think this needs to be a concern of core.

Thanks for the valuable discourse, folks! 😄

[jamesckemp]

Could a quick, interim solution be as simple as:

If multiple plugins are activated, use the new ajax method and add the notice. If a single plugin is activated, proceed as before with the hookable redirect.

[joostdevalk]

I think the long-term solution is actually fairly easy: display an AJAX message for each activated plugin, but allow filtering of the AJAX activation message by the just activated plugin, for example to include a link to your onboarding.

Much less work than what everyone is proposing here, it seems to me.

I’m actually against the automatic redirecting, as what happens is you’re taken from a WordPress UI and UX to a plugin native UI and UX, and that, IMHO, needs to be the result of step taken by the user.

That doesn't mean we shouldn't revert on the change first, I think we've gone about this change the wrong way round and hard deprecated something too fast.

[kevinwhoffman]

Replying to joostdevalk:

I think the long-term solution is actually fairly easy: display an AJAX message for each activated plugin, but allow filtering of the AJAX activation message by the just activated plugin, for example to include a link to your onboarding.

Much less work than what everyone is proposing here, it seems to me.

I'm not sure a filterable message is much less work than what we've been discussing. It sounds similar to what I suggested in comment:22:ticket:61040.

The proposed filter and "Configure" link would restore some consistency to the plugin activation experience while still giving plugins with first-time onboarding experiences a clear method of directing users to their preferred next step. We could even consider making the "Configure" text filterable by plugin developers so the button can say "Start Onboarding," "Continue Onboarding", etc. based on the configuration that's been done so far. That's the type of clarity and control that I hope this framework can offer to developers and users alike.

The advantage of the "Configure" link over an AJAX message is that it positions the next action in the same place where the "Activate" action was previously taken, so the user is already looking at that exact spot in the UI. This is a pattern that WordPress core already follows with Install > Activate and that many app stores follow with workflows to Install > Open, Get > Open, etc.

@joostdevalk If there was a filterable AJAX message, where would it be displayed? In the plugin card, an admin notice at the top of the screen, or somewhere else?

[richtabor]

I appreciate the core team working to add a Refresh button in #60992, but I feel this is adding extra friction and complexity for beginners / non-techy users.

100% agree. Do we know that redirects are a problem? Is it more, or less, of a problem that we’ve introduced now, essentially hiding a plugin’s configuration view?

I’m not confident “Install” > “Activate” > “Configure” on its own is enough of a comparable alternative. Perhaps it introduces more concision, as under what conditions does the “Deactivate” action render now? Only after configuration is complete?

In any case, I support reverting to accommodate for a proper solution.

[kevinwhoffman]

Replying to richtabor:

Do we know that redirects are a problem? Is it more, or less, of a problem that we’ve introduced now, essentially hiding a plugin’s configuration view?

@richtabor isn't the first to ask how we know redirects are a problem. @alanfuller previously questioned how we can make an assumption about user expectations without real user feedback or extensive research. Both are fair questions.

While any proposed solution should be tested for usability, we ought to at least be able to agree that the inconsistency and unpredictability of the post-activation redirect behavior are problematic—not based on opinion, but on established usability heuristics that have been guiding software development for decades.

Consistency and Standards

In ​Nielsen's 10 Usability Heuristics for User Interface Design, the fourth heuristic ​Consistency and Standards addresses the importance of internal and external consistency.

This ​continuum of consistency can be summarized as follows:

To be easy to learn and use, systems should adhere to both internal and external consistency — they should use the same patterns everywhere inside the system and should also follow web-, platform-, and domain-specific conventions.

Internal Consistency

On internal consistency, there is a clear-cut problem. We have an "Activate" button in WordPress core that looks the same, has the same label, and appears in the same location within the plugin card component, but it behaves differently from one plugin to the next.

In Usability Heuristic 4, it is recommended that:

Users should not have to wonder whether different words, situations, or actions mean the same thing.

Along those lines, I'd argue the following should also be true:

Users should not have to wonder whether the same words, situations, or actions mean different things."

Unfortunately when activating plugins today, WordPress users are left wondering whether the same button means something different from one plugin to the next.

A Usability Test (Not) Worth Doing

Here's a usability test we could do with the existing UX on the Add Plugins screen: Ask new users to install the ​top 12 most popular plugins. Before clicking "Activate," ask them whether they expect the action to simply put the plugin into an active state or redirect to an onboarding page on the next page load. You can try this yourself by installing the first 12 plugins from the "Popular" tab.

Spoilers: 5 of the 12 most popular plugins perform a redirect on the first page load after activation:

1. ✅ Elementor - Redirect
2. 🚫 Contact Form 7 - No redirect
3. ✅ Yoast SEO - Redirect
4. 🚫 Classic Editor - No redirect
5. ✅ WooCommerce - Redirect
6. 🚫 Akisment - No Redirect
7. ✅ WPForms - Redirect
8. 🚫 All-in-One WP Migration and Backup - No redirect
9. 🚫 LiteSpeed Cache - No redirect
10. ✅ Really Simple SSL - Redirect
11. 🚫 Wordfence - No redirect
12. 🚫 Jetpack - No redirect

For extra fun, activate all 12 and then refresh. Did you guess which plugin won the battle of redirects?

Since there is no difference in presentation from one plugin's "Activate" button to the next, there is nothing to distinguish the control group from the experimental group. I'd argue that it doesn't even matter whether most users predict the redirect behavior correctly or not. The fact that the behavior is inconsistent and unpredictable should be enough for us to agree that redirects are problematic.

While the recent changes to AJAX plugin activation made redirects more problematic due to the delay between activation and refresh, the inconsistency and unpredictability have always been there since plugins started adopting the pattern.

External Consistency

On external consistency, I feel there is more room for debate depending on how users mentally map WordPress's Install/Activate convention to their experience with other app stores' Get/Open conventions.

• Some have argued that "Activate" is analogous to "Open" and therefore it should launch an onboarding flow just like opening a new app would do.
• Others have argued that "Activate" is more analogous to "Get" and therefore it should only put the plugin into an active state just like getting an iPhone or Mac app puts it into an active state without opening it.

I agree user feedback is very important here to prevent the opinion of a few from dictating the behavior for all.

In Summary

While the question of internal consistency reveals a clear violation of established usability heuristics, the question of external consistency is more open to interpretation and, yes, opinion. While we should seek user feedback to clarify our position on external consistency and eventually the solution, I hope that the above clearly demonstrates why the redirects are problematic in the first place without requiring extensive research.

[kevinwhoffman]

5 out of 12 most popular plugins redirect to an onboarding page on the first page load after activation. The plugins with a redirect are outlined in red.

[alanfuller]

Couple of things

First, (with the thanks for the efforts of volunteers etc that should go without saying ) the UX even with the 6.5.3 fix is awful,unless you are expecting it then the admin notice is totally missable, and for a third row plugin for most screens above the fold and an extra click for no reason -and noidea how that feels on a screen reader, but guessing not good.

Second,I think 'onboarding' shouldn't happen on the activation hook, but on the first time a user actually uses the plugin pages, that is how many on the non redirect examples above execute onboarding.

But, after activation, the user is left guessing where the plugin pages actually are unless the plugin also gives an admin nag or drops a marker on the dashboard (on activation hook - not a redirect but ), so we are then 'freestyling' on the plugin developers to come up with usability patterns so then the UX will continue to be inconsistent.

I hope this ticket can move on to coming up with design patterns and a plugin developer 'api' that can in future be baked into the plugin developer detailed guidelines / review process.

[richtabor]

But, after activation, the user is left guessing where the plugin pages actually are unless the plugin also gives an admin nag or drops a marker on the dashboard (on activation hook - not a redirect but ), so we are then 'freestyling' on the plugin developers to come up with usability patterns so then the UX will continue to be inconsistent.

Yes. This seems the root result of where it’s at today.

Consistency and standards

I agree consistency is paramount, but not at the detriment of usability. Not all plugins need a setup/configure step—but many do. If we’re making it harder to setup 5 out of 12 of the popular plugins, we’re not moving in the right direction.

Thinking out loud riffing ideas, but what about if plugins had “Install”, “Activate”, and an open/launch action when activated. Plugins can provide where/what open/launch means, and can decide if onboarding, configuration is needed on their end. Open/launch doesn’t have to mean a setup or configure flow, it could be a plugin’s main settings view, or guide/info.

It’s essentially moving the redirect one step, but also making the installed plugins page more of a launcher.

[jeherve]

Replying to kevinwhoffman:

The fact that the behavior is inconsistent and unpredictable should be enough for us to agree that redirects are problematic.

Indeed. It's a good example of why we need a better solution.

Spoilers: 5 of the 12 most popular plugins perform a redirect on the first page load after activation:

I'd add one more thing. Even if we do not look at the redirects, we can look at the plugins themvelves: 10 out of those 12 plugins do require some configuration before you can start using them. Only the Classic Editor plugin and the LiteSpeed Cache plugin can be used out of the box.

This is a small sample size obviously, but I think it's a good example of why there is a need for a consistent, core-led post-install configuration flow.

It seems to me like the proposed "Configure" link would do just that. Displayed in the same place as the existing "Active" / "Activate" / "Install Now" / "Update now" buttons, it wouldn't come as a surprise for many site owners. We could rely on a dashicon to make the button pop out a bit more, like we do today for the "Update now" button:

That said, if we think the simple change of state of that button isn't visible enough, we could also change the display of the whole plugin card:

• The card background may change to indicate a different status
• The "Configure" word could be customizable by plugin authors, just as much as the configure link itself, so authors can change it to something that fits their plugin a bit more (e.g. "Create your first contact form", or "Set up your online store").

[jeherve]

Configure button for a newly activated plugin, with dashicon

[alanfuller]

Are we in agreement we need 3 steps?

1. Add
2. Activate
3. Setup / configure / onboard - optional - controlled by plugin developer?

If so

Once the screen greys out Activate the in PHP I would lik eto be able to do this approximately

add_filter ('plugin_post_activate_link', function() {

return array (

'link => admin_url('my_settings_page'),
'button_text' => esc_html('Start Wizard','my-plugin-domain'),
'dashicon' => 'whatever',

) };

and also have a hook like

add_action ('plugin_post_activate_link_clicked', function() {

do_my_onboarding_screens();

} );

This may be far less important - because developers can create their own 'home brew' for detecting if they want to run a wizard, but in all cases the plugin developer would most likely want to detect where a user came from (i.e. an oboarding button click ) and if we can provide a consistent pattern that is easy to use then the user experience is likely to be more consistent.

( edited to add dashicon suggestion by @jeherve )

[kevinwhoffman]

Replying to alanfuller:

Are we in agreement we need 3 steps?

1. Add
2. Activate
3. Setup / configure / onboard - optional - controlled by plugin developer?

Thanks for this question as it helped to me to reconsider what a two-step approach might look like.

Two-step Expectations

My experience with other app stores causes me to expect a two-step process (despite my previous proposal to Install > Activate > Configure).

In generic terms, most app stores:

1. Get the thing into an active state on the device
2. Then open the thing (where onboarding typically follows)

One might say we already have a two-step process with Install and Activate, but the problem is that activation in WordPress—when it includes redirects—actually spans elements of steps 1 and 2 above, which results in unpredictability that is not present in other app stores.

Combining Install and Activate

I recommend we do not break the Install/Activate paradigm in WordPress even though activation is an extra step that most app stores do not require. With that said, it is worth considering combining Install and Activate as the default action specifically on the Add Plugins screen.

In my experience:

• I am nearly always activating a plugin after installing it from the Add Plugins screen.
• Sometimes I'm installing and activating multiple plugins (which is when the redirects become especially problematic).
• I rarely, if ever, install a plugin from the Add Plugins screen and then do not activate it right away. If I do delay activation, it's because I know a redirect is going to take me way.

"Install and Activate" then "Open"

By combining Install and Activate, we could achieve a two-step flow that is more in line with other app store experiences:

1. "Install and Activate"
2. "Open" (or what I've previously been referring to as "Configure")

I've been thinking about a more suitable term for "Configure" and came to the realization that "Open" is a more generic, familiar, and flexible action for the majority of use cases. Whether you just want to get users to your plugin page or kick off an onboarding experience, "Open" makes sense in both scenarios. The text could still be filtered to "Start Onboarding" or something else if the plugin desires. And if there is no value defined by the plugin, then the disabled "Active" button could be displayed by default as it is today. I'll attach a mockup for review.

Installing Without Activating

If we want to maintain an option for users who really want to install without activating from the Add Plugins screen, then here are couple of possibilities:

1. Consider a combo button where "Install and Activate" is the default option while "Install Only" is a secondary option.
2. Consider having "Install and Activate" and "Install Only" actions available in the existing modal that opens when pressing "More Details."

[kevinwhoffman]

A two-step flow where the user is able to "Install and Activate" the plugin in one click, and then "Open" it with a second click. Plugins would have the option to filter the "Open" link and text. If no filter is applied, then the disabled "Active" button would be shown by default. This allows immediate introduction of the filter while allowing plugins to adopt it over time.

[alanfuller]

Conceptually I'm happy with a two step, personally I struggle to recall any reason I have not immeadiately activated. That does not mean there will not be reasons but this is solved by the suggestions made.

I do have one minor concern and maybe some UX experts could chime in, but the disabling of the ACTIVATE button and change of word to the similar worded ACTIVE just does not feel like a positive affirmation of success. I think it is a minor point as once the filter is enabled I'm sure the majority of popular plugins will implement it.

[chrisbadgett]

I am also in agreement with the idea of combining the "Install and Activate" steps into a 1-step flow. And the filterable titled "Open" step-2 makes sense which plugin developers could hook into for initiating set-up wizard onboarding flows. This feels familiar to how apps work on a phone, which makes intuitive sense, especially for new WordPress users.

If a user gets distracted or doesn't notice the open step after activation, ideally the next refresh could still trigger the wizard for the just activated plugin if it has one.

Having a secondary "Install Only" option would be good to have too. For example, if a user is switching from one plugin to another that does similar things, the user may want to install the replacement plugin, but not activate it right away. This could be solved by moving the "More Details" link somewhere else on the card, and using that space directly below the "Install and Activate" button for an "Install Only" text link.

[costdev]

Note that the following states exist for plugins, in the format State -> Possible button text:

• Not installed, has no dependencies -> Install and Activate
• Not installed, has missing dependencies -> (disabled) Install Now
• Not installed, all dependencies are installed but not all are active -> Install Now
• Not installed, all dependencies are installed and active -> Install and Activate
• Installed, inactive, with no dependencies -> Activate
• Installed, inactive, all dependencies active -> Activate
• Installed, inactive, with inactive dependencies -> (disabled) Activate
• Installed, active -> (disabled) Active
• Installed, has update -> Update Now

Also note that bulk installation and/or activation from the Plugins > Add New screen was very strongly opposed throughout the years of Plugin Dependencies' development, which is why I don't include an Install All or Activate All option in the list above.

[jeherve]

I like the idea of combining the "Install" and "Activate" steps into one. It makes a lot of sense.

@kevinwhoffman As you mention:

I rarely, if ever, install a plugin from the Add Plugins screen and then do not activate it right away. If I do delay activation, it's because I know a redirect is going to take me way.

I would add one extra caveat: I would delay activation if I know the plugin has a dependency, i.e. if I do not mean for that plugin to be used on its own on my site and if I have not installed, activated, and configured the dependency yet.

If that's something we can take into account, I think that would be a good approach. To expand on your last flow, it would mean only offering "Install and Activate" if the plugin has no dependency declared in the plugin header, or if the declared dependency is already active.

[alanfuller]

Just thinking are we creating complexity and inconsistency by trying to have one workflow that works both for dependent plugins and standalone plugins?

To be honest, as of yet I have not seen the dependent plugin work flow 'in the wild' so don't feel qualified to give input, so can someone provide a set ( e.g. 3 ) plugins that are dependent so I can see what the current dependent plugin workflow is?

[costdev]

@alanfuller Here are three dependent plugins:

1. Google Listings & Ads
2. Jeg Elementor Kit
3. WPSSO Shipping Delivery Time for WooCommerce SEO

[alanfuller]

OK so I just tried dependent plugins for the first time, and I don't want to critize the hard work that has gone into it, but I didn't find the work flow very user friendly. So I think my question is valid at the moment, are we creating a complexity by combining two work flows.

I add Google listings,it says I need WooCommerce but doesn't give me an option to install that I was expecting. Instead Ihav eto click on more details that opens a modal that give me the option to install.

I install, and close the modal.The install button is still greyed out.

I refresh the page and now I can install Google Ads list, so I do.

Which gives me the option to Activate Google Ads listing, so I try.

And I get 'Activation Failed' with no reason given.

I notice that is still says Woocommerce required - more details -> modal -> Activate button is active
which I press

I now get a refresh notice. So i refresh.

I now have an ACTIVE button for Google Ads - but it still says I need WooCommerce which I thought I had so I go to the modal again, no options so I guess it is OK

And now I can activate Ads Listing.

So it works, sort of ( I spotted some unrelated issues / bugs but I'll raise those elsewhere to keep this just about workflow ) but not a great experience and as an experienced WP user I might live with that.

But what I really want is it to be simple - I select a plugin that requires another plugin why can't I just install (and activate ) them all - why should i have to go back and forth through modals one by one? Maybe there are use cases where the one by one activity is needed, but I would have thought the basic premise, I need two plugins lets get two plugins would be the default.

[smub]

I agree with @alanfuller sentiment that we're creating more complexity by combining two workflows. Even though they feel similar, they aren't. We should work towards building the best workflow for the respective Jobs to Be Done.

But before we do that, the best thing to do is to Revert until we come up with a user-friendly solution as @richtabor @joostdevalk and others have mentioned as well.

Here's an example of what happened when I tried to install WooCommerce on a test site that I had. After I activated WooCommerce - nothing really happened. Unlike a beginner user, I'm aware of this ticket, I scrolled up to look at the Manual Refresh notice.

Here's what my dashboard looked like -- on my screen resolution which I keep magnified since most users don't work on 27" iMac super low font sizes -- I couldn't even see something had changed until I scrolled up to find this manual Refresh Now button.

I also tried the manual refresh workflow on plugin dependencies, and this also leads to more clicks than needed as @alanfuller as described in his experience above. TGMPA user experience that many plugin / theme authors have used for dependencies works. Let user install the plugin they're looking for and once it's installed, let that plugin / theme ask user to install other dependencies with clear explanation so users know why it's needed and have proper communication vs. a blue notice that says Additional plugins are required where the More Details modal shows a generic Readme listing of the plugin vs. having some sort of custom message.

[costdev]

@alanfuller The activation issue you had with WooCommerce seems to be unrelated. That's not what was happening during testing.

The Install Now button not being enabled after installing the dependencies is a known issue where work is intended to resolve that in 6.6.

But what I really want is it to be simple - I select a plugin that requires another plugin why can't I just install (and activate ) them all - why should i have to go back and forth through modals one by one? Maybe there are use cases where the one by one activity is needed, but I would have thought the basic premise, I need two plugins lets get two plugins would be the default.

The primary reasons are transparency and user control. Yes, a user could have control by clicking to install and activate the dependencies, but they won't know what those dependencies are or what they do. Even if not all users want to read the information, any user should be able to.

@smub We should work towards building the best workflow for the respective Jobs to Be Done. But before we do that, the best thing to do is to Revert until we come up with a user-friendly solution

Reverting isn't a prerequisite to making improvements, and I think what we feel about the current flows shouldn't be the reason for a revert. We need to establish data that indicates how users are finding the flows after 6.5.3.

I understand that the flow isn't perfect, though there are limits to what we can do in a minor, and reverting a released major feature has impacts on backward compatibility, documentation, setting precedence, and contributor morale. There was ample time to explore, test and provide feedback on the feature before it was released, and the changes to UX were communicated through all the official channels. The QA channels and time period in WordPress have been established and known for a long time. The flows can be improved or changed without impacting backward compatibility, but we can't revert the whole feature without a backward compatibility break.

Pre-release, reverting would be understandable as a first step, but post-release, balancing what's best for users isn't easy - as we all know - and we should consider how we can iterate before consider reverting as a last resort, rather than considering revert as the first step.

[alanfuller]

Replying to costdev:

@alanfuller The activation issue you had with WooCommerce seems to be unrelated. That's not what was happening during testing.

MAybe I should record a video of teh experience it micht be clearer ( this was on a clean site )

[alanfuller]

Replying to costdev:

The primary reasons are transparency and user control. Yes, a user could have control by clicking to install and activate the dependencies, but they won't know what those dependencies are or what they do. Even if not all users want to read the information, any user should be able to.

I was not advocating hiding dependencies or lossing control, just improving the default behaviour.

So I'm think in the 'card' slist the dependent plugin still with more details but a pre-checked check box and a related button that says Install / Activate ALL

I'm graphically challenged so can't draw what I see in my mind

[alanfuller]

Replying to smub:

But before we do that, the best thing to do is to Revert until we come up with a user-friendly solution as @richtabor @joostdevalk and others have mentioned as well.

Thank you for agreeing with some of my points, but on this point I will say this ticket is not about reverting, but about going forward, this ticket was created off the back of https://core.trac.wordpress.org/ticket/60992 which is where any advocation for reverting should be in my opinion, to help keep the design and optimization of workflows separate from the more emotive topic of reverting.

[alanfuller]

This is the video of my experience of dependency workflow

​https://www.youtube.com/watch?v=AE2MJGVL_sc

[afragen]

FWIW there is a Core Slack meeting in #core-upgrade-install every week at 1800 UTC. Which happens to be now.

[costdev]

Thanks a lot for the video @alanfuller! I misunderstood about the "Activation failed" issue and thought you meant that WooCommerce failed to activate.

For the Install Now button remaining disabled after installing dependencies until you refresh, that's the known issue I'm actively working on. This is somewhat linked to the Deactivate and Delete issue you saw on the Plugins > Installed plugins page. Which should become more straightforward once I finish working on getting the Install Now (or Activate) buttons to live update.

However, when you installed the dependency, closed the modal, then refreshed and clicked Install Now for the dependent, the button should not have changed to an enabled Activate button. That appears to be an unknown issue, and I'll be exploring this tomorrow - thanks for flagging it!

Regarding the notice remaining after all required plugins are installed and activated, I see how this causes confusion as it may suggest those plugins are required but are missing, rather than simply stating that the plugin requires those. The notice uses the info styling (blue) rather than warning (orange) or error (red), though that meaning isn't going to be obvious to many users. We can certainly improve the messaging here, though I think it's worth keeping the notice (or other way to display it) so it's clear that it's a dependent plugin.

The checkbox suggestion is possibly a separate enhancement to the onboarding discussed in this ticket. If you want to create another ticket to discuss this - either now or at a later stage, I'd be interested in the discussion about that.

[kevinwhoffman]

​WordPress 6.6 is set to be released on July 16, 2024.

While I appreciate all of the rich conversation, I am also wary of this ticket becoming so large in scope that we cannot provide a solution in 6.6 that addresses the usability regression introduced in 6.5 for plugins that require onboarding, a change that led others to call for a reversion.

In an effort to avoid a reversion and deliver a better solution in 6.6, I've split out the various opportunities discussed so far in this ticket, stack ranked them according to user need and reach, and recommend pursuing them further in separate tickets across successive releases.

1. Immediate need (6.6): Answer the question, "What do I do next?" after plugin activation

If teleporting users via redirect is no longer a suitable solution, then we ought to provide a clearly marked bridge for users to navigate from activation to onboarding themselves. By keeping the scope small and positioning a solution like the "Open" link as a progressive enhancement, we can avoid reverting Plugin Dependencies altogether and provide a solution that is even better than redirects in time for 6.6.

2a. Iterative improvement (6.6 or later): Streamline the plugin dependencies workflow

I appreciate that @alanfuller highlighted a few pain points, some of which @costdev clarified are already being addressed. As @afragen said in ​Slack, the Plugin Dependencies feature has a long history that should be understood before making further changes. Because of that history, I recommend that improvements to the Plugin Dependencies workflow happen outside of this ticket. We should be mindful of how dependencies affect activation and onboarding, but in order to address Item 1 quickly, we are better off treating the plugin dependency workflow as a detour on the way to activation that doesn't necessarily restrict what happens after activation.

2b. Nice-to-have (6.7): Combine "Install and Activate" into one step on the Add Plugins screen

This would be a small victory that reduces time to value and the steps necessary to activate a plugin, but it does not necessarily need to be coupled with Item 1. We still need to clarify how we are going to maintain the ability to "Install Only" if "Install and Activate" becomes the new default, which is likely to lead to debate. Therefore it is better approached as a separate issue in order to ensure Item 1 can be done in time for the 6.6 release.

3. Someday: Add a full-fledged onboarding framework

Some have rightly called out that adding an "Open" link or combining "Install and Activate" does not constitute a framework, to which I say maybe the scope of this ticket was too broad to begin with. This ticket was born out of discussion in #60992 specifically around the transition from plugin activation to onboarding. Item 1 addresses that need and should be our immediate focus for 6.6. Work towards a more complete onboarding framework should happen in concert with the ​Admin Design effort and should not be considered a blocker to Item 1.

[alanfuller]

This strategy to move forward makes sense to me, split the issue and make progress first on the most pressing, which in my mind is the post activation step.

[adrianduffell]

I think an opportunity presents itself here to explore combining the install and activate flows and consider whether this would better serve 80% or more of end users, many of whom are non-technical.

What are the current use-cases for having the install and activate flows as separate clicks? Could these use-cases be served by a dedicated plugin instead?

If we could combine these flows, I think the proposed onboarding framework and disabling of the redirects becomes easier for plugin devs to accept. The combined flows would produce the same amount of clicks to start the plugin onboarding as that seen in previous WP versions. Using App Store parlance mentioned here previously, these clicks could be:

• Get: performs the install and activate flows.
• Open: starts the plugin onboarding (if the plugin uses the WordPress filter to register a URL)

For WooCommerce, this would return the plugin back to the 6.4 behavior of needing just two clicks for the user to start the Woo onboarding. For simpler plugins, users would only require a single click to have the plugin completely ready on the site.

[afragen]

Since a combined Install/Activate is a brand new UX, it should be in a ticket by itself.

[hellofromTonya]

Related: #61269 (for 6.5.4)

[hellofromTonya]

In 58250:

Upgrade/Install: Restore Activate button's href native behavior.

Restores the Activate button's href native behavior by changing the AJAX activation handler introduced in 6.5.0. It restores the pre-6.5 behavior of clicking the "Activate" button, i.e. navigates the user to the button's href (i.e. to the plugins.php UI).

Why?

Feedback was given after shipping [57545] in 6.5.0 (but was unknown during the development and testing cycles) revealed significant impacts for plugins who's users valued the onboarding / configuration experiences.

6.5.3's [58081] and [58083] added a new user action / step to the workflow. Though helpful, it did not fully resolve the impacts.

For the minor, this commit seeks to restore only the "Activate" button's href pre-6.5 native behavior to resolve the regression.

The next phase of the Add Plugins workflow can then continue in a major release to gain the benefits of a full major to move it from ideation through the development phases. (See #61040). The questions of redirect, how / should configuration be in the workflow, etc. can best be explored and experimented with in a major.

Follow-up to [57545], [58081], [58083].

Props costdev, jorbin, hellofromTonya, afragen, kevinwhoffman, azaozz, adrianduffell, beaulebens, hmbashar, illuminea, ironprogrammer, jjj, lopo, louiswol94, mikachan, nerrad, mukesh27, peterwilsoncc, pooja1210, smub, swissspidy.

Fixes #61319.
See #22316, #60992.

[afragen]

I believe more rapid progress can be made on an onboarding framework by working on smaller pieces and building towards a complete solution.

Given this I think the first discussion that needs to happen is how much of the onboarding process should be designated by core. Should core have a starting point (like the previously proposed filter) and allow the plugin devs greater latitude in shaping their respective onboarding experiences or should core be more opinionated as to this process?

[hellofromTonya]

In 58254:

Upgrade/Install: Restore Activate button's href native behavior.

Restores the Activate button's href native behavior by changing the AJAX activation handler introduced in 6.5.0. It restores the pre-6.5 behavior of clicking the "Activate" button, i.e. navigates the user to the button's href (i.e. to the plugins.php UI).

Why?

Feedback was given after shipping [57545] in 6.5.0 (but was unknown during the development and testing cycles) revealed significant impacts for plugins who's users valued the onboarding / configuration experiences.

6.5.3's [58081] and [58083] added a new user action / step to the workflow. Though helpful, it did not fully resolve the impacts.

For the minor, this commit seeks to restore only the "Activate" button's href pre-6.5 native behavior to resolve the regression.

The next phase of the Add Plugins workflow can then continue in a major release to gain the benefits of a full major to move it from ideation through the development phases. (See #61040). The questions of redirect, how / should configuration be in the workflow, etc. can best be explored and experimented with in a major.

Follow-up to [57545], [58081], [58083].

Reviewed by jorbin.
Merges [58250] to the 6.5 branch.

Props costdev, jorbin, hellofromTonya, afragen, kevinwhoffman, azaozz, adrianduffell, beaulebens, hmbashar, illuminea, ironprogrammer, jjj, lopo, louiswol94, mikachan, nerrad, mukesh27, peterwilsoncc, pooja1210, smub, swissspidy.

Fixes #61319.
See #22316, #60992.

[kevinwhoffman]

One possible focus of the Plugin Onboarding Framework in WordPress 6.6. is to reduce time to value by providing an onramp from plugin activation to an appropriate plugin-defined next step. This keeps the scope small and attainable while answering the universal question, "What do I do next?" after activating a plugin.

[afragen]

@kevinwhoffman one of the considerations in your diagram is, how would core trigger multiple processes, in the correct order, potentially for multiple plugins at the same time?

It’s one of the reasons I think more of the responsibility should be with the plugin with an entry point in core.

[hellofromTonya]

I think it's too early to know if a "framework" is needed or not. I'm offering a new approach to consider how to move this ticket forward to resolution. Allow me to explain.

The current workflow solves the Plugins Dependency (PD)'s the problem statement, as noted from #61319:

The problem PD aims to solve is that when a plugin has a dependency on another, users are left to their devices which leads to inconsistent user experiences and potential for site breakage by deactivating plugins that are relied upon

Is an onboarding / configuration / getting started / welcome "next step" needed in Core? Is it known yet that the majority of users identify a pain point of the auto-redirect/auto-load of these experiences?

Much was learned from the hard removal which led to 6.5.4.

The #61319's Problem Statements are a great starting point for considering if Core should provide the means for the user's next step after activation:

Plugin companies and their users (which are also this project's users) are significantly impacted.

It's unknown if the majority of users want or do not want auto-redirect.

It's now known that impacted plugin's users do want this ability. The size of their user bases is data to suggest the significance of the impact.

A new onboarding framework needs the benefits of major release cycle to understand the impacts, form a scope, do experiments, and then move through the product | enhancement stages.

I suggest repurposing this ticket to:

1. First, understand the impacts and to find out if the majority of users identify the "redirect after activation" as a pain point for them. (Using the ​"Design for the majority" philosophy.)
2. If users say yes, then form a problem statement and scope, and then update this ticket's description and title to reflect it. A problem statement and scope will help to guide the ideation through the development cycle.

It's too late in 6.6 to land code changes, but it's not too late to start working on the above. If changes are needed, starting now could help those to land in 6.7.

What do you all think of this plan and suggestions?

[alanfuller]

I think it is right to challenge the assumption that onboarding is needed as part of core.

The onboarding concept came out of trying to find a solution to the original statement that it was impossible to revert the ajax activation and that it was necessary for plugin dependencies - there was no way back so a new solution needed to be found for plugins - and as the problem came from a core decision - the solution would also have to be assisted by core features.

In all honesty I haven't looked at any depth of 6.5.4 in terms of plugin dependencies ( totally selfishly PD is not something I need or use ) but if it still allows PD to work and the status quo (pre 6.5 ) on existing plugin onboarding is maintained then all is OK and no further action needed.

I understand there is a pain point when plugin developers incorrectly trigger onboarding in bulk activations, but that is plugin code and the purpose of the plugin support forums and reviews.

[kevinwhoffman]

Apologies in advance for the extended metaphor, but... What if we narrowed down our scope to the moment that takes place immediately after a plugin is activated? The problem we'd be solving is the universal need for all interactive plugins to transition a user from plugin activation to "What's next?"

Activating plugins today is like stepping into a teleporter that sometimes whisks you off to an unknown location via a redirect... and sometimes does nothing.

What if core could replace those finicky teleporters with conventional doorways that look and feel like other doorways we've seen before?

Core could provide such a standard doorway (e.g. a filterable "Open" button) after activating a plugin. Users would come to recognize the doorway, what it looks like, where it's located, how it opens, and what it represents.

Rather than being teleported through the doorway without a choice, users could read the sign on the door and decide whether they want to enter through the doorway now or later (i.e. after installing other plugins or dependencies).

Plugin authors wouldn't have to be doorway experts. They could rely on core to provide an accessible and predictable doorway to all users. Plugin authors could decide what sign goes on the door ("Open", "Get Started", "Configure", etc.) and what happens once you pass through the door (jump straight into using the plugin, start an onboarding wizard, configure a settings page, etc.).

And if the plugin author is unaware or chooses not to take advantage of the doorway provided by core, then the door remains locked with a simple "Active" sign on the door, just like it does today.

In this sense, the doorway is a progressive enhancement offered to plugins, but not forced upon them. Through documentation and developer outreach, we can provide a recommended workflow that can be adopted over time, gradually replacing the unpredictable teleporters with predictable doorways that restore user choice.