Agentur Allison

During the development of my “SCW Stock Control for WooCommerce” plugin I wanted to improve the appearance of the popup you see when clicking “view details” link on the WP Admin > Plugins page. In this article I explain how I arrived at the popup as shown below.

How to add a banner and plugin information to the “view details” popup box with Easy Digital Downloads (EDD)

EDD has a small but very important tickbox in Downloads > Settings > Extensions. If you tick “Selling WordPress Plugins?” then additional meta boxes will show in your Downloads screen which all you you to to upload a README.txt file from which EDD will then parse the plugin information and sections.

To get started I enabled the tickbox, then I went back to my Download and added the README file URL, banner images, plugin URL and ticked to override the description and changelog from the Downloads screen (which in my case were empty – best to only store the information in one place to avoid confusion).

This worked pretty well but was not perfect. I was missing the author and version fields; and I wanted to set the “last updated” field to the date the plugin code was last modified.

Easy Digital Downloads (EDD) provide a sample PHP file for handling updates in custom plugins which contains the EDD_SL_Plugin_Updater class. In this class there’s a function called plugins_api_filter() which gets the plugin information from the plugin website and shows it in the “view details” popup.

By customising plugins_api_filter() I was able to change the content of the popup. For my purposes, most of the data was fine so I left it as it was. For the other content I wanted to show I created Constants which I put in the core file of my plugin to remind myself that these will need updating with every release.

define( 'SCW_VERSION', '1.0.0' );
define( 'SCW_AUTHOR', '<a href="https://example.com">Author Name</a>' );
define( 'SCW_UPDATED', '2022-03-02 18:00:00' );

In the above Constants I added a “last updated” date. EDD does pull in the date but it’s the date when the download was last updated. As this could be any change eg a price I wanted to set my own date to show when the code was last modified. WordPress uses the strtotime() function so the date format can be any English textual datetime description.

Next in the function plugins_api_filter() right before “return $_data;” I added my new object elements:

// Set SCW information
$_data->version = SCW_STOCK_CONTROL_FOR_WOOCOMMERCE_VERSION; 
$_data->author = SCW_AUTHOR;
$_data->last_updated = SCW_UPDATED;

And there you have it! A good looking popup with banners and plugin information 🙂

Understanding README.txt

The README.txt file uses a modified version of markdown which allows the WordPress directory to parse information about your plugin. But even if your plugin is not available on the WP plugin site you can use README.txt to show information in the plugins popup if you tick the “WordPress plugin” checkbox in EDD settings.

The README syntax is explained in the official WordPress plugin handbook here: https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works/. For an example of how a README file can look I recommend the sample README.txt of the WordPress Boilerplate plugin: https://github.com/DevinVinson/WordPress-Plugin-Boilerplate/blob/master/plugin-name/README.txt. Maintained by Tom McFarlin and Devin Vinso, the WP Plugin Boilerplate is a great way to get an understanding how a WP plugin structure can be built.

For example for my Installation tab I use a simple structure consisting of a section heading wrapped into double equal signs (==), Bold headings wrapped into double asterisks (**) and a numbered list.

== Installation ==

**Installation through WP Admin**

1. Go to your WordPress Admin > Plugins and upload the zip file 
2. Click Activate
3. Go to SCW > Settings and enter your licence key 

If like me you find that code can be the best documentation, then have a look at the install_plugin_information function in the plugin-install.php file (currently around line 510) which shows you the names of the expected object elements. For example, if you want to add sections for Description, Changelog, Installation, FAQs, Screenshots, Reviews and Other Notes then the section names to use are listed as:

  $plugins_section_titles = array(
		'description'  => _x( 'Description', 'Plugin installer section title' ),
		'installation' => _x( 'Installation', 'Plugin installer section title' ),
		'faq'          => _x( 'FAQ', 'Plugin installer section title' ),
		'screenshots'  => _x( 'Screenshots', 'Plugin installer section title' ),
		'changelog'    => _x( 'Changelog', 'Plugin installer section title' ),
		'reviews'      => _x( 'Reviews', 'Plugin installer section title' ),
		'other_notes'  => _x( 'Other Notes', 'Plugin installer section title' ),
	);

You can also add custom section headings, but these will be shown in the “Description” tab as a new heading.

Upgrade Notice

In the core updates screen you can also display a short update message, no longer than 300 characters. EDD supports this through the README.txt file, all you need to do is to add a heading for Upgrade Notice and enter your text like so:

== Upgrade Notice == 

Bug fixes related to logs. 

This will then show on the core upgrade page:

WordPress uses strip_tags() for the notice, so remember to use plain text only. The code in /wp-admin/update-core.php:

// Get the upgrade notice for the new plugin version.
if ( isset( $plugin_data->update->upgrade_notice ) ) {
	$upgrade_notice = '<br />' . strip_tags( $plugin_data->update->upgrade_notice );
} else {
	$upgrade_notice = '';
}