Using Blueprints
You can use Blueprints in one of two ways:
- By passing them as a URL fragment to the Playground.
- By using the JavaScript API.
URL Fragment
The easiest way to start using Blueprints is to paste one into the URL "fragment" on WordPress Playground website, e.g. https://playground.wordpress.net/#{"preferredVersions...
.
For example, to create a Playground with specific versions of WordPress and PHP you would use the following Blueprint:
{
"$schema": "https://playground.wordpress.net/blueprint-schema.json",
"preferredVersions": {
"php": "7.4",
"wp": "6.5"
}
}
And then you would go to
https://playground.wordpress.net/#{"preferredVersions":{"php":"7.4","wp":"6.5"}}
.
In Javascript, you can get a compact version of any blueprint JSON with JSON.stringify
and JSON.parse
Example:
const blueprintJson = `{
"$schema": "https://playground.wordpress.net/blueprint-schema.json",
"preferredVersions": {
"php": "7.4",
"wp": "6.5"
}
}`;
const minifiedBlueprintJson = JSON.stringify(JSON.parse(blueprintJson)); // {"preferredVersions":{"php":"7.4","wp":"6.5"}}
You won't have to paste links to follow along. We'll use code examples with a "Try it out" button that will automatically run the examples for you:
Base64 encoded Blueprints
Some tools, including GitHub, might not format the Blueprint correctly when pasted into the URL. In such cases, encode your Blueprint in Base64 and append it to the URL. For example, that's the above Blueprint in Base64 format: eyIkc2NoZW1hIjogImh0dHBzOi8vcGxheWdyb3VuZC53b3JkcHJlc3MubmV0L2JsdWVwcmludC1zY2hlbWEuanNvbiIsInByZWZlcnJlZFZlcnNpb25zIjogeyJwaHAiOiAiNy40Iiwid3AiOiAiNi41In19
.
In JavaScript, You can get any blueprint JSON in Base64 format with global function btoa()
.
Example:
const blueprintJson = `{
"$schema": "https://playground.wordpress.net/blueprint-schema.json",
"preferredVersions": {
"php": "7.4",
"wp": "6.5"
}
}`;
const minifiedBlueprintJson = btoa(blueprintJson); // eyIkc2NoZW1hIjogImh0dHBzOi8vcGxheWdyb3VuZC53b3JkcHJlc3MubmV0L2JsdWVwcmludC1zY2hlbWEuanNvbiIsInByZWZlcnJlZFZlcnNpb25zIjogeyJwaHAiOiAiNy40Iiwid3AiOiAiNi41In19
Load Blueprint from a URL
When your Blueprint gets too wieldy, you can load it via the ?blueprint-url
query parameter in the URL, like this:
Note that the Blueprint must be publicly accessible and served with the correct Access-Control-Allow-Origin
header:
Access-Control-Allow-Origin: *
JavaScript API
You can also use Blueprints with the JavaScript API using the startPlaygroundWeb()
function from the @wp-playground/client
package. Here's a small, self-contained example you can run on JSFiddle or CodePen:
<iframe id="wp-playground" style="width: 1200px; height: 800px"></iframe>
<script type="module">
import { startPlaygroundWeb } from 'https://playground.wordpress.net/client/index.js';
const client = await startPlaygroundWeb({
iframe: document.getElementById('wp-playground'),
remoteUrl: `https://playground.wordpress.net/remote.html`,
blueprint: {
landingPage: '/wp-admin/',
preferredVersions: {
php: '8.0',
wp: 'latest',
},
steps: [
{
step: 'login',
username: 'admin',
password: 'password',
},
{
step: 'installPlugin',
pluginZipFile: {
resource: 'wordpress.org/plugins',
slug: 'friends',
},
},
],
},
});
const response = await client.run({
// wp-load.php is only required if you want to interact with WordPress.
code: '<?php require_once "/wordpress/wp-load.php"; $posts = get_posts(); echo "Post Title: " . $posts[0]->post_title;',
});
console.log(response.text);
</script>