Plugin Directory: Preview button revisited

Based on feedback about our first attempt at testing a plugin preview feature, we have an improved version ready to go. This version builds on feedback and suggestions, and in particular is designed to give pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party developers the opportunity to safely experiment and test the preview experience for their plugins before making them public.

About Plugin Previews in the Playground

If you haven’t noticed it yet, the WordPress Playground is an amazing feature that lets anyone safely run a temporary WordPress install within their browser. It uses WASM to run a complete WordPress install – PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.php., database, and all – entirely from within your web browser. No server needed, nothing to install.

For a while now Playground has supported loading any plugin or theme from the plugin directory; here’s how.

About the new Plugin Preview button

As with the last attempt, the new Plugin Preview feature simply adds a convenient button to plugins in the plugin directory. The button takes the user to Playground with that plugin installed. It’s right beside the Download button, like this:

The important differences this time around are:

1. The button is double-opt-in. It’s not shown by default for any plugins.
2. It’s now possible for plugin developers to configure the preview environment and install dependencies (other plugins and themes).
3. Plugin developers can test the preview before making it available to the public.
4. Most php extensions are now supported.
5. Remote network requests are now supported.

I’ll explain these in more detail below.

Opt-in.

There are two things required for a plugin preview button to appear to all users:

1. A valid blueprint.json file must be provided in a blueprints sub-directory of the plugin’s assets folder.
2. The plugin preview must be set to “public” from the plugin’s Advanced view by a committer.

Note: Part 2 is intentionally not yet deployedDeploy Launching code from a local development environment to the production web server, so that it's available to visitors., meaning no plugin preview buttons are yet available to the public. This is intended to give a grace period for plugin developers to experiment with blueprints, customize the experience, and decide if they want to use it.

If a valid blueprint.json file is present, then the Preview button will be present for plugin committers only. In which case it will look like this:


It’s called Test Preview because that’s why it’s there: to allow plugin committers to test their plugin in the Playground environment and decide whether or not to make it easily available to the public.

Blueprints.

Blueprints are jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. files used to set up a WordPress Playground instance.

They can be used to specify things like PHP and WP versions, the landing page, and (most importantly) a series of automated steps such as logging in, and installing and activating plugins and themes.

The blueprint for your plugin should be committed to the assets folder with subversionSVN Apache Subversion (often abbreviated SVN, after its command name svn) is a software versioning and revision control system. Software developers use Subversion to maintain current and historical versions of files such as source code, web pages, and documentation. Its goal is to be a mostly compatible successor to the widely used Concurrent Versions System (CVS). WordPress core and the wordpress.org released code are all centrally managed through SVN. https://subversion.apache.org/. as assets/blueprints/blueprint.json. Initially only the one blueprint file is supported, but we expect to allow multiple in future.

Here’s an example of a simple blueprint.json file that you could use as a starting point:

{
    "landingPage": "\/wp-admin\/edit.php",
    "preferredVersions": {
        "php": "7.4",
        "wp": "5.9"
    },
    "phpExtensionBundles": [
        "kitchen-sink"
    ],
    "steps": [
        {
            "step": "login",
            "username": "admin",
            "password": "password"
        }
    ]
}

The features used here are:

• landingPage, which specifies the URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org of the page that the user will land on when the preview loads.
• preferredVersions, which specifies versions of PHP and WordPress.
• phpExtensionBundles, which in this case specifies that we want most common PHP extensions to be available (kitchen-sink).
• steps, which tells Playground what to do before displaying the landing page. In this case, it will simply log the user in to wp-admin.

Here’s an example of a more advanced blueprint.json that demonstrates some more features you could use to create a rich demo environment for users:

{
	"landingPage": "/wp-admin/post.php?post=5&action=edit",
	"preferredVersions": {
		"php": "7.4",
		"wp": "5.9"
	},
	"phpExtensionBundles": [
		"kitchen-sink"
	],
	"steps": [
		{
			"step": "login",
			"username": "admin",
			"password": "password"
		},
		{
			"step": "installPlugin",
			"pluginZipFile": {
				"resource": "wordpress.org\/plugins",
				"slug": "my-imaginary-plugin-dependency"
			},
			"options": {
				"activate": true
			}
		},
		{
			"step": "installPlugin",
			"pluginZipFile": {
				"resource": "wordpress.org\/plugins",
				"slug": "my-imaginary-plugin"
			},
			"options": {
				"activate": true
			}
		},
		{
			"step": "installTheme",
			"themeZipFile": {
				"resource": "wordpress.org\/themes",
				"slug": "my-imaginary-theme"
			}
		},
		{
			"step": "setSiteOptions",
			"options": {
				"some_required_option_1": "your_favorite_values",
				"some_required_option_2": "your_favorite_values"
			}
		},
		{
			"step": "runPHP",
			"code": "<?php\ninclude 'wordpress/wp-load.php';\nwp_insert_post(array(\n'import_id' => 5,\n'post_title' => 'Example Post',\n'post_content' => '<!-- wp:paragraph -->\n<p>a normal paragraph</p>\n<!-- \/wp:paragraph -->',\n'post_status' => 'publish',\n'post_author' => 1\n));"
		}
	]
}

This demonstrates some more advanced Blueprint features such as:

• Installing plugin dependencies (my-imaginary-plugin-dependency)
• Installing and activating a theme (my-imaginary-theme)
• Setting wp_options (some_required_option_1 and some_required_option_2)
• Running PHP code to create a demo post (runPHP)

You’ll find much more about Blueprints in the Playground documentation, including several helpful examples.

Almost any of the documented Blueprint features should work. There are some particular caveats to blueprints as used by the Plugin Preview button feature however:

• Your blueprint.json file must validate as per PHP’s json_decode() function. If no Test Preview button appears, check that it’s valid. (Note that this means backtick quotes as used in this example are not supported as they are invalid in json) .
• If you forget to install and activate your own plugin with an installPlugin step, the plugin directory will add that step for you when adding the blueprint to the Preview button.
• The blueprint will be whitespace-normalized before use.
• There is a 100kb size limit. This is an arbitrary limit necessary for tedious reasons; I expect we’ll increase or remove it in future.

What’s next

We expect to improve on the preview feature in a number of ways. In the short term:

• We’ll take the preview button out of test mode and allow public use very soon, depending on your feedback.
• A coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. patch will propose adding an identical Preview button to the plugin directory UIUI UI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing. in core. (Whether or not this is adopted will depend of course on core team discussion and process).
• Better Blueprint validation and error reporting.
• Support for multiple blueprint.json files.
• UI/UXUX UX is an acronym for User Experience - the way the user uses the UI. Think ‘what they are doing’ and less about how they do it. design improvements.

In the longer term, we’ll collect and discuss ideas, and post proposals in MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. tracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. tickets and/or Make p2 posts.

Feedback, questions, and support

You’re welcome to post suggestions, ideas, and questions in comments on this post.

Over time we’ll direct support questions and requests to other forums as available.