Add support for the WordPress.org plugin preview

[dkotter]

Description of the Change

WordPress.org recently launched support for plugin previews utilizing the WordPress Playground feature. Plugins wanting to take advantage of this need to opt in by setting up a blueprint.json file that configures how the preview should load. This PR adds in that file that does the following:

1. Sets up an environment running PHP 7.4 (our supported minimum) and the latest version of WordPress
2. Logs into the admin
3. Installs and activates the plugin
4. Imports some test content
5. Sends the user to an example post with the Winamp block

Note that this PR is targeted to trunk as the hope is we can take advantage of our Plugin Asset Update Action to deploy these changes without having to push out a new release.

Also note once these changes are on .org, the preview button will need to be enabled in a test state. Once verified as working, we can enable it for all users.

How to test the Change

The WordPress Playground allows you to spin up a new environment directly through the URL, by going to https://playground.wordpress.net/# and pasting your JSON config after the #. In this case, the URL should be: https://playground.wordpress.net/#{%20%22$schema%22:%20%22https://playground.wordpress.net/blueprint-schema.json%22,%20%22landingPage%22:%20%22\/wp-admin\/post.php?post=5&action=edit%22,%20%22preferredVersions%22:%20{%20%22php%22:%20%227.4%22,%20%22wp%22:%20%22latest%22%20},%20%22phpExtensionBundles%22:%20[%22kitchen-sink%22],%20%22steps%22:%20[%20{%20%22step%22:%20%22login%22,%20%22username%22:%20%22admin%22,%20%22password%22:%20%22password%22%20},%20{%20%22step%22:%20%22installPlugin%22,%20%22pluginZipFile%22:%20{%20%22resource%22:%20%22wordpress.org\/plugins%22,%20%22slug%22:%20%22retro-winamp-block%22%20},%20%22options%22:%20{%20%22activate%22:%20true%20}%20},%20{%20%22step%22:%20%22importFile%22,%20%22file%22:%20{%20%22resource%22:%20%22url%22,%20%22url%22:%20%22https:\/\/raw.githubusercontent.com\/10up\/retro-winamp-block\/d2ff63d1127713d9f2a11235a002f38f2927b0ca\/.wordpress-org\/blueprints\/demo-data.xml%22%20}%20}%20]%20}

Changelog Entry

Added - Support for the WordPress.org plugin preview

Credits

Props @dkotter

Checklist:

• I agree to follow this project's Code of Conduct.
• I have updated the documentation accordingly.
• I have added tests to cover my change.
• All new and existing tests pass.

[jeffpaul]

@dkotter are we able to import a test audio file and have that pre-set in the block?

[dkotter]

@dkotter are we able to import a test audio file and have that pre-set in the block?

Yeah, that would be ideal and I tried to figure that out but wasn't successful in the time I spent on this. As far as I can tell from reading the docs, there isn't a built-in command to import media yet.

@10up/open-source-practice If anyone has interest in seeing if they can figure this out, that would be great. If not I can take another stab at some point, as we'll definitely want to do something similar in a few of our other plugins.

For reference, here's some of the things I've tried:

1. There's an importWordPressFiles step that can be used to take a zip file and use that to replace the contents of the root directory. Within the WP Playground environment, you can export a zip of that environment. I was hoping that taking that zip and using it in this step would work (as that zip contains the uploads directory as well as a database backup) but it didn't work for me. I may have been doing something wrong though
2. You can run custom PHP in a runPHP step. I was hoping to be able to import a media file using something like media_sideload_image and then use that media file within the block but I couldn't get it to work. It's tricky writing PHP in a json file as well as there's issues because the PHP code doesn't run in a normal WordPress context, so most files aren't loaded yet. I was able to get wp_update_post to work here but could never get media to import. Again, may be something I'm doing wrong
3. I didn't try this out but we are importing content from a WordPress export file during the build process. We may be able to reference media in this file and have it import, assuming the media is publicly available. I don't think this will add the media item to our block but we may be able to do that in a runPHP step

Not sure if there's a way to get error reporting / logging in WordPress Playground because that's been my biggest issue with trying to use the runPHP step, as it often fails but doesn't tell me why. One thing I was going to try but haven't yet is to utilize the wp-now tool to try running things locally to see if I can get better debugging. This is supposedly the same tool that WP Playground uses and does support importing blueprint files, not sure on the debugging/logging part though.

[peterwilsoncc]

I've pushed an update with some sample data that references the full URL of a media file in the sample post, it appears to work as expected.

https://playground.wordpress.net/#{%22$schema%22:%22https://playground.wordpress.net/blueprint-schema.json%22,%22landingPage%22:%22/wp-admin/post.php?post=5&action=edit%22,%22preferredVersions%22:{%22php%22:%227.4%22,%22wp%22:%22latest%22},%22phpExtensionBundles%22:[%22kitchen-sink%22],%22steps%22:[{%22step%22:%22login%22,%22username%22:%22admin%22,%22password%22:%22password%22},{%22step%22:%22installPlugin%22,%22pluginZipFile%22:{%22resource%22:%22wordpress.org/plugins%22,%22slug%22:%22retro-winamp-block%22},%22options%22:{%22activate%22:true}},{%22step%22:%22importFile%22,%22file%22:{%22resource%22:%22url%22,%22url%22:%22https://raw.githubusercontent.com/10up/retro-winamp-block/4b998e304f5ab68b45c67c4bc4cf78a601e642e3/.wordpress-org/blueprints/demo-data.xml%22}}]}

I pushed a media file up (source) but since force pushed it out of existence as I think it would be wise to serve it from either another branch on GitHub or via WordPress.org (which will require updating the import file).

Please don't merge until we decide where to serve the file from!

[ravinderk]

@peterwilsoncc, I've reviewed it, and the WordPress playground functions as expected. Directly referencing audio files contributes to faster booting of the WordPress Playground. I recommend adopting this approach and allowing users to upload audio files for testing the block.

cc: @dkotter @jeffpaul

[dkotter]

I think it would be wise to serve it from either another branch on GitHub or via WordPress.org

For a few of our plugins I've been referencing files to import (like on this PR) just straight from a commit on GitHub (like https://raw.githubusercontent.com/10up/retro-winamp-block/4b998e304f5ab68b45c67c4bc4cf78a601e642e3/.wordpress-org/blueprints/demo-data.xml).

I guess my thought is we could put the audio file in the blueprints directory and reference it in a similar fashion. I'm not opposed to referencing the file from .org either though, just makes it harder to test until that file is actually in place which is why I've been using Github instead.

But curious if you have additional thoughts on the best location for these files, if referencing a commit on Github doesn't seem to be the best approach.

[jeffpaul]

Putting blueprint data/files in the blueprints folder makes the most sense to me

[peterwilsoncc]

But curious if you have additional thoughts on the best location for these files, if referencing a commit on Github doesn't seem to be the best approach.

I'm happy to put it in there.

Here's some files we can use and redistribute. For credit, I suggest we include it in the sample post import into the playground installation. https://openverse.org/search/audio?q=Short&license=pdm,cc0,by,by-sa,by-nd&extension=mp3

[dkotter]

All right, this is ready for review again. I've added a couple test mp3 files and updated our export file to use those files

https://playground.wordpress.net/#{%20%22$schema%22:%20%22https://playground.wordpress.net/blueprint-schema.json%22,%20%22landingPage%22:%20%22\/wp-admin\/post.php?post=5&action=edit%22,%20%22preferredVersions%22:%20{%20%22php%22:%20%227.4%22,%20%22wp%22:%20%22latest%22%20},%20%22phpExtensionBundles%22:%20[%22kitchen-sink%22],%20%22steps%22:%20[%20{%20%22step%22:%20%22login%22,%20%22username%22:%20%22admin%22,%20%22password%22:%20%22password%22%20},%20{%20%22step%22:%20%22installPlugin%22,%20%22pluginZipFile%22:%20{%20%22resource%22:%20%22wordpress.org\/plugins%22,%20%22slug%22:%20%22retro-winamp-block%22%20},%20%22options%22:%20{%20%22activate%22:%20true%20}%20},%20{%20%22step%22:%20%22importFile%22,%20%22file%22:%20{%20%22resource%22:%20%22url%22,%20%22url%22:%20%22https:\/\/raw.githubusercontent.com\/10up\/retro-winamp-block\/d2ff63d1127713d9f2a11235a002f38f2927b0ca\/.wordpress-org\/blueprints\/demo-data.xml%22%20}%20}%20]%20}

[peterwilsoncc]

Looks good to me, thanks Darin.

I've confirmed the file works as expected via JSON.stringify.

[jeffpaul]

@dkotter @peterwilsoncc in testing this on WP.org I'm seeing the generic audio block player render instead of the Winamp player:

[dkotter]

The link added doesn't work for me but if what you're seeing in the Playground is that screenshot, that all looks correct to me. The custom block uses normal audio blocks within it and those render by default. You can toggle to see the Winamp player in the toolbar. By default it's on Audio List but you can choose Preview Player instead.

[jeffpaul]

Ah I see, I don't think I noticed the Audio List vs. Preview Player toolbar toggles before. Thinking perhaps the Preview Player option is the better default (as that's how it'll render on the frontend) but that's something I can open in a separate issue.

[jeffpaul]

This now appears to throw an error:

You attempted to edit an item that does not exist. Perhaps it was deleted?

Perhaps the blueprint was referencing something that was deleted?