How to use WordPress Playground for interactive demos – WordPress Developer Blog
WordPress Developer Blog
How to use WordPress Playground for interactive demos
WordPress Playground’s
JavaScript API
is a developer-oriented tool that opens a new world of possibilities. Supporting elaborate standalone instances makes it particularly effective for showcasing a theme or a plugin (or both) and preparing WordPress guides that go beyond textual documentation to provide a layer of interactivity.
Table of Contents
If you’re not familiar with
Playground
, start by reading the previous article:
Introduction to Playground: running WordPress in the browser
. To make the most of this tutorial, you’d need to understand the modularity of the three APIs that power Playground and how they allow you to share themes, plugins, and even complete websites—content included.
What will you build?
The project is inspired by a common use case: demonstrating how a custom plugin coupled with a theme adapted to feature it looks and functions together. This scenario requires a manual that instructs users how and where to set the data displayed in the plugin’s custom fields. Using Playground to spin up a live site with an extra step-by-step guide makes the experience much more engaging.
├── playground
│ ├── zips
│ │ ├── blue-note.zip
│ │ ├── meta-block-sidebar.zip
│ ├── blueprint.json
│ ├── index.html
├── plugins
│ │ ├── meta-block-sidebar
│ │ │ ├── PLUGIN FILES...
├── themes
│ │ ├── blue-note
│ │ │ ├── THEME FILES...
├── README.md
You can find the code on
the GitHub repository
created to accompany this tutorial. The project includes the theme and plugin source files, as well as compressed files used by Playground. Either clone or create it manually before you continue.
Create the Blueprint
Let’s start with the cornerstone of every Playground project: the
blueprint.json
file. If you haven’t cloned the repository, copy and paste the following code into your file:
"$schema": "https://playground.wordpress.net/blueprint-schema.json",
"preferredVersions": {
"php": "latest",
"wp": "latest"
},
"siteOptions": {
"blogname": "WordPress Playground Demo"
},
"plugins": [
"create-block-theme",
"https://raw.githubusercontent.com/wptrainingteam/playground-demo-handover/main/playground/zips/meta-block-sidebar.zip"
],
"steps": [
"step": "installTheme",
"themeZipFile": {
"resource": "url",
"url": "https://raw.githubusercontent.com/wptrainingteam/playground-demo-handover/main/playground/zips/blue-note.zip"
},
"step": "runPHP",
"code": " 'Created by a Blueprint', 'post_content' => '
How do you update the meta fields?
- Open the Settings sidebar by clicking the window icon next to the blue Update button.
- Click the Meta Block Sidebar menu (below the Summary menu).
- Type the Team name and the date the person joined the company in the respective fields.
- Click the blue Update button.
],
"features": {
"networking": true
},
"login": true,
"landingPage": "/?p=4"
Let’s take a moment to explain the different steps Playground will perform for you:
Once launched, Playground will create a WordPress instance, using the latest PHP and WordPress versions supported.
Then, it will rename the site.
Install and activate two plugins:
Create Block Theme
(available on the Plugin Directory and, therefore, fetched using its
slug
), and the custom
Meta Block Sidebar
(available in the same GitHub repository, and, accordingly, fetched from the relevant
URL
).
Install and activate the adapted version of the
Blue Note theme
(fetching it from the same GitHub repository).
Create a post with a step-by-step guide.
Enable networking mode.
Log into the site as an Administrator.
And, finally, open the site displaying the newly created post.
The little user manual packs content and HTML block markup together using WordPress’
wp_insert_post
function
. This method works for short snippets, but it’s wiser to explore Playground’s more robust alternatives:
Importing an XML file using the
importWxr
step
, or
Generating posts via WP-CLI using the eponymous
wp-cli
step
Shorthands
The Blueprint in this tutorial takes advantage of Playground’s shorthand syntax to make this set of instructions less verbose. The following steps are currently supported:
plugins
siteOptions
, and
defineWpConfigConsts
Check out the documentation
to learn more about how and when to use these instead of explicit steps.
Test the Blueprint
Now would be a good time to pause, experiment, and get comfortable with Blueprints. Copy the code above and paste it into the official
Blueprint editor
(still a WIP). Your instance should be identical
to the original demo
To get a concrete sense of the possibilities, try modifying some values right there in the Blueprint editor—maybe the value of
landingPage
(replace
/?p=4
with
/?p=1
) or
blogname
. If something goes wrong, undo your changes, fix any errors the editor alerts you to, and hit the
Run it
button again.
How to load assets in a Blueprint?
Playground needs to be able to access your files to run them. This can be done in several ways: via your custom domain, a GitHub repository, and more. The former ostensibly makes more sense, but browser security restrictions mean you’ll need to handle any Cross-origin resource sharing (CORS) issues on your server. A faster way to go about it is to use GitHub’s special
raw.githubusercontent.com
domain.
To prevent CORS-related errors, make your repository
public
, and point Playground to the absolute paths of the files using the following pattern: https://raw.githubusercontent.com/
{USER}/{REPO}/{BRANCH}/PATH/TO/FILE
If your repository is
private
, you can only access the Playground instance via a custom domain.
Playground’s in-browser editor is an invaluable tool for testing. It’s also the fastest way to start adjusting the original sample to your needs. When you feel confident enough, use it to prototype your project instead of tediously tweaking the JSON on your local machine, hoping you got everything exactly right.
Go ahead and alter the file names and directory structure according to your project’s theme and plugins—don’t forget to update the file paths and sync everything to GitHub, so the files are available online (see the CORS section above). Once you’re happy with the result, copy the code over to your
blueprint.json
file.
You can share the project using
Playground’s Query API
. Here’s what the URL of the example project looks like (click to open in a new tab):
Use the JavaScript API
So far, you haven’t actually tapped into the JavaScript API; let’s see how you can take advantage of its most powerful feature: initiating the Playground API Client. Create an
index.html
file, and copy and paste the following code:
Playground Demo
Source code rel="noopener">on GitHub
The
client
object will load inside the
iframe
via the project’s
remote.html
file—
the only allowed “endpoint”
of this API—and run the steps provided inside the
blueprint
variable,
leveraging the Blueprint API to configure the client
based on your specific settings.
One of the helpful side effects of using the JavaScript API (instead of loading an
iframe
) is that you don’t need to worry about CORS, absolute paths, and public repositories: the client handles everything—as long as you’ve set the correct URL. Paste the contents of the
blueprint.json
file created before. Change any preceding HTML markup and CSS styles to match your needs.
Live testing
Playground’s JavaScript API uses ES Modules, which means you’ll need a local server to run
index.html
in the browser. To launch a simple development server, open the terminal, and type any of the following:
– For PHP:
php -S localhost:8000
– For NodeJS:
npx serve
After you upload everything to GitHub and connect the repository to a custom domain and hosting provider, you can access and share the complete demo via your domain, pointing to the path of your
index.html
file (
).
This is what the original project looks like:
Your turn
Now that you’re all set—with both code samples and a deeper understanding of what each line does—it’s time to create your project: Upload your own modified theme or bespoke plugin, think about how to best generate posts, change the site settings, set up users (and more advanced scenarios) with
wp-cli
, and think what else you could do in the HTML-based demo itself.
How about loading multiple instances on the same page, each showing a different style variation side-by-side? Or, maybe, prepare a live tutorial teaching how to edit a template page and load a Playground in an
iframe
below, asking students to recreate it, and share their results on GitHub (using the
Export Pull Request to GitHub
option in the UI)?
The
JavaScript API
supports much more advanced use cases, so check out
the first part of this series
to see what else is possible with Playground, explore
the Blueprints examples
demos, and apps
for inspiration, and start playing.
Props to
@bph
@zieladam
, and
@bjmcsherry
for reviewing this post.
Share the post:
Share on Mastodon (Opens in new window)
Mastodon
Share on LinkedIn (Opens in new window)
Share on X (Opens in new window)
Share on Bluesky (Opens in new window)
Bluesky
Share on Mail (Opens in new window)
Mail
Share on Reddit (Opens in new window)
Reddit
Share on Tumblr (Opens in new window)
Tumblr
Share on Telegram (Opens in new window)
Telegram
Share on WhatsApp (Opens in new window)
WhatsApp
Categories:
Advanced
Playground
Tags:
Extenders
Playground
3 responses to “How to use WordPress Playground for interactive demos”
Steve Dufresne
April 26, 2024
If you are a plugin author in the wp.org directory, consider adding an interactive demo for your plugin!
You can read more on how to do it here:
If you’re interested in the technical implementation or have some ideas on how to improve it, participate here:
Reply
Gaurav Kumar
June 1, 2024
JavaScript Playground is new things and there is a lot to test.I am testing its compatibility with Elementor and Divi website builders.
Reply
John Shawn
June 30, 2024
Beyond basic installation and activation, how can I leverage JavaScript APIs and Blueprints within WordPress Playground to create truly interactive and engaging demos for themes and plugins?
Reply
Leave a Reply
Cancel reply
Have an idea for a new post?
Learn how to contribute
Share your knowledge with fellow WordPress developers.
Review tips and guidelines
Everything you need to know about writing for the Blog.
Subscribe to the Blog
Join 1,854 other subscribers