I was inspired to find out how to add an inline plugin update message when I saw a recent update notification from WooCommerce. They have quite a fancy customized message that expands on the basic notification that a new version is available:
By sheer concidence, I recently had a situation where I needed to advise users of a critical update to a plugin. I had assumed that the Upgrade Notice section in the readme file would take care of that automatically but it seems that’s no longer the case. So I took a look into how it’s possible to alert users to upgrade a plugin.
In my opinion, this code snippet is vital for any plugin because it appears that WordPress doesn’t currently offer a method for plugin authors to communicate with their users regarding essential updates.
Display plugin upgrade notice to users
Users can be lazy about updating plugins and themes. Often, that doesn’t matter. Updates are usually improvements, minor fixes, enhancements, and so on, and not urgent. Occasionally though, you might have to issue a significant bug fix or security patch and you want your users to update as soon as possible.
Something like this:
Notice the additional message under the new version notification?
To do this, we can use the in_plugin_update_message hook to display a message in the plugins list.
| function prefix_plugin_update_message( $data, $response ) { | |
| printf( | |
| '<div class="update-message"><p><strong>%s</strong></p></div>', | |
| __( 'Version 2.3.4 is a recommended update', 'text-domain' ) | |
| ); | |
| } | |
| add_action( 'in_plugin_update_message-your-plugin/your-plugin.php', 'prefix_plugin_update_message', 10, 2 ); |
Now, at this point, you might be thinking that you’ve spotted a fatal flaw in this method. Perhaps you’re thinking that this won’t work because you need to include your update notice in the previous version of the plugin, before you even know that an update is going to be necessary. And you’d be right…
However, the clever bit here is that we can use this method to grab content from the readme file, namely anything included in the upgrade_notice section.
Amend the code to:
| function prefix_plugin_update_message( $data, $response ) { | |
| if( isset( $data['upgrade_notice'] ) ) { | |
| printf( | |
| '<div class="update-message">%s</div>', | |
| wpautop( $data['upgrade_notice'] ) | |
| ); | |
| } | |
| } | |
| add_action( 'in_plugin_update_message-your-plugin/your-plugin.php', 'prefix_plugin_update_message', 10, 2 ); |
Here, we’re using the $data object passed to the function to read content from the readme file. If the upgrade_notice element exists, then display it.
Even so, bear in mind that you will still need to have this code in your plugin from the start – so I recommend including it now even if you don’t have any plans to use it now. You never know when you’ll suddenly need to inform your users about a crucial update.
What about multisite?
The above method works fine on a single site installation and for multisite installations when the plugin is network enabled. However, you’ll need to add some more code for when your plugin is installed on multisite but only enabled on a site by site basis.
This uses a different hook – after_plugin_row_{file} – which adds a new row to the plugins table.
| function prefix_ms_plugin_update_message( $file, $plugin ) { | |
| if( is_multisite() && version_compare( $plugin['Version'], $plugin['new_version'], '<') ) { | |
| $wp_list_table = _get_list_table( 'WP_Plugins_List_Table' ); | |
| printf( | |
| '<tr class="plugin-update-tr"><td colspan="%s" class="plugin-update update-message notice inline notice-warning notice-alt"><div class="update-message"><h4 style="margin: 0; font-size: 14px;">%s</h4>%s</div></td></tr>', | |
| $wp_list_table->get_column_count(), | |
| $plugin['Name'], | |
| wpautop( $plugin['upgrade_notice'] ) | |
| ); | |
| } | |
| } | |
| add_action( 'after_plugin_row_wp-your-plugin/your-plugin.php', 'prefix_ms_plugin_update_message', 10, 2 ); |
This displays the message like this:
You can see that here we’re checking that we’re on a multisite installation and that the current version of the plugin is less than the new version. Then we add a new row to the plugins table with the upgrade message.
Contact your users directly
Finally, don’t forget that if you’re building plugins, you can contact your users directly – even when you’re distributing your plugins through the WP repo. Add Wisdom to your plugin to gather all your users’ email addresses and contact them directly.