Add WordPress Playground Block

[adamziel]

Description

This PR adds the WordPress Playground Block to Composer dependencies.

The block enables embedding WordPress Playground in posts and pages – both as:

• A plain WordPress site
• An interactive plugin code editor + WordPress site preview combo

Motivation

The Playground block would unlock a next-level interactive learning experience on learn.wp.org. Tutorials for testers, designers, and developers could include not just screenshots and videos, but actual live WordPress instances opened directly on the relevant page, e.g. the Site editor. Developers could learn to build plugins by interacting with a live code editor where a simple plugin is already created for them, and they're encouraged to customize it.

How does it work?

The WordPress site displayed in the Playground block can be customized using the block toolbar and block inspector controls. The changes made directly in the embedded WordPress are not saved yet. The most powerful customization tool available in the block is the custom Blueprint inspector control – with a single JSON file, you can prepare any WordPress site at all.

Next steps

I would love to hear your thoughts and find out whether the block has the features most important for you or is it missing anything crucial.

cc @westnz @jonathanbossenger

[jonathanbossenger]

@adamziel thank you for creating this PR

I'm going to put out a call for Training team members to help test/review this PR.

[jonathanbossenger]

Note to reviewers, one of the other items to consider is accessibility, so it would also be ideal if the new block is tested for accessibility using the axeDevTools browser extension

[courtneyr-dev]

I love the direction. Can we check in with Accessibility team as well?

[jonathanbossenger]

Can we check in with Accessibility team as well?

@courtneyr-dev in the past, I've checked with members of the Accessibility team, and they've confirmed that using the axeDevTools browser extension is a good process to follow.

If you're aware of any other tools we can use to test this for Accessibility, please link them here, and we can add them to the testing process.

[bbertucc]

axe doesn't cover everything. I'm happy to test if you let me know where I can test it. (I tried to download the plugin and install it on a fresh install with no luck - it never came up when looking for blocks.)

[alexstine]

If Playground renders in an iFrame, it will already be disadvantaged for accessibility. I would not consider an approve on this until there was an option to open in a new window, non-iFrame option.

Thanks.

[jonathanbossenger]

I'm happy to test if you let me know where I can test it.

@bbertucc are you comfortable testing it using the Learn WordPress local development environment? (details in the readme).

Alternatively, you can download the zip file manually from the plugin repository.

[adamziel]

If Playground renders in an iFrame, it will already be disadvantaged for accessibility. I would not consider an approve on this until there was an option to open in a new window, non-iFrame option.

@alexstine thank you, that's useful! An "open in a new window" option can be added with a relative ease 👍

I tried to download the plugin and install it on a fresh install with no luck - it never came up when looking for blocks.

@bbertucc Oh no! Thank you for reporting the problem, I'll double-check that. Is there any chance it's because the plugin doesn't provide any search keywords and the block is difficult to find? Or is it just not there, even if you type "WordPress Playground" verbatim? Meanwhile, are you able to test using the Learn WordPress local dev env like @jonathanbossenger suggested?

[bbertucc]

@jonathanbossenger - i'll spinup a local environment. sounds like @adamziel still has a bit more work to do, so I'll check it out after the plugin has been updated.

[jonathanbossenger]

Is there any chance it's because the plugin doesn't provide any search keywords and the block is difficult to find? Or is it just not there, even if you type "WordPress Playground" verbatim?

@adamziel I think the problem is also that the original version of this block was named "Interactive Playground Block" and as such, that's what the slug is. As you might know, you cannot unfortunately change the plugin slug. When searching for "Interactive Playground Block", the block does appear in search results.

[adamziel]

That could be it @jonathanbossenger! I just installed the plugin on a Local site and the block did come up. Would you mind trying again @bbertucc? And, in the meantime, we'll explore the open in a new window mode.

[adamziel]

@alexstine I've explored an iframe-less "Open in a new window" feature, and I ran into two technical blockers.

We can't open the same site in a new window. We can only open a new site with the same initial configuration.

The iframed WordPress site cannot be seamlessly opened in a new window. The embedded Playground only exists in the context of the current domain because of the Privacy Sandbox. We could open new a site with the same initial configuration as the iframed site.

To illustrate: Say I write a theme customization tutorial for a site that a custom theme, say adventurer. Then, I send a link to my friend. They would see a WordPress site with the adventurer theme and a button that says "open in a new window". If they update the theme to, say, twentytwentyfour it's all fine. But if they click the "open in a new window" button after that customization, the newly opened site would not reflect that update – it would be a brand new site with the adventurer theme.

That doesn't seem like a deal-breaker as the block could clearly communicate that limitation, e.g. by naming the button "start over in a new window".

Here's a larger challenge, though.

A code editor would be unreliable in an iframe-less setup.

Imagine a technical tutorial that teaches people how to write their first plugin. We need a code editor and a WordPress preview side by side.

How would it work without iframing the WordPress site, though? Clicking on any link would reload the entire page, including the code editor. Also, the code editor would effectively be rendered as a part of the WordPress site within the theme and it would be affected by WordPress styles, plugins, hooks. Furthermore, if the student saves a plugin with a syntax error, the WordPress site won't reload which means there will be no way to fix that error from the code editor.

I can't think of a good way of resolving the problems associated with modifying a state of the system from inside that system. Iframes provide a degree of separation required to debug fatal errors.

Let's find an accessible way forward

What are three most important specific accessibility issues related to iframes? Is there something Playground can do to resolve them? If not, let's discuss alternative paths forward. The interactive iframe-based materials would benefit millions of future learners and I'd argue there's value in creating them even if they wouldn't be fully accessible. Perhaps every iframe-based tutorial could also have a static, iframe-less version with the same code examples and instructions intended for use in a local environment with your own WordPress installation and a code editor?

cc @jonathanbossenger

[alexstine]

@adamziel iFrames are simply just challenging for accessibility. They are somewhat better on Windows today but Mac Voiceover uses a much different interaction model. What worries me about this is having an iFrame inside an iFrame since the Gutenberg editor canvas is now an iFrame. Sites like CodePen have been really hard for me to use and only recently became an option. For most of my coding stuff, I'd add it to a GitHub Gist.

I guess I'll try to revive my local environment and test the plugin.

The other thing you need to keep in mind is iFrames don't exactly care where they are placed so if you have important content after the iFrame such as instructions on what to do, I won't get that information because I'll first have to navigate beyond the iFrame. That is the biggest reason I don't want to see this on Learn right now, I am not confident that there is enough accessibility checking in place to say "any content following the iFrame must have a heading for easily skipping passed the iFrame." Trying to enforce this would be tricky.

Thanks.

[bbertucc]

@adamziel - the block came up this time, but the error popped up in my console: Unhandled Promise Rejection: TypeError: ReadableByteStreamController is not implemented. Attaching a screenshot.

[adamziel]

@alexstine thank you for explaining!

Sites like CodePen have been really hard for me to use and only recently became an option.

Is the recent change related to Voiceover updates, or CodePen updates?

I guess I'll try to revive my local environment and test the plugin.

I'm updating the plugin today and will post a testing link here that will open the plugin in Playground. It would mean even more iframes, though, but it wouldn't require setting up a dev env.

Also, about the iframes I'm noodling on the following ideas:

1. Always create an invisible heading after the iframe that the Voiceover can read. I'm not sure what would be useful to say there, though. Would a text such as "skip the code example" be useful in this context?
2. Do not load the iframe upfront. Instead, require a click and also offer an iframeless alternative.

Would either of these be helpful?

[alexstine]

@adamziel CodePen changes. It used to crash whatever browser I used. Still hard to navigate but somewhat better today.

I think as long as there is a way to skip the iFrame and only load the iFrame when ready, that should be enough. New window option would not be required.

Thanks.

[adamziel]

@bbertucc oh no, it seems like the plugin doesn't work in Safari. I created an issue to track this and will follow up shortly. In the meantime, would you mind trying it out on Chrome? Note the plugin has a live preview link here: https://wordpress.org/plugins/interactive-code-block/advanced/

[adamziel]

@jonathanbossenger @bbertucc @alexstine I've fixed a number of issues in the block and Playground. The latest version 0.1.8 seems to work properly in Safari, local WordPress, and with and without the Gutenberg plugin. I would love to get your feedback. If you'd like to try it in Playground, here's two links you could use:

Edit: It seems like these Playground URLs were not posted correctly. I'm figuring out a solution now.

• A single page showcasing the site editor using the Playground block
• That same page, but open in the post editor

And, here's the list of issues fixed thanks to your feedback so far:

• Playground Block broken in Safari playground-tools#176
• Playground block: Not showing up on a fresh WordPress install playground-tools#170
• Playground block not loading in an iframed editor playground-tools#177

[alexstine]

@adamziel Looks like those are the same 2 links. Thanks.

[adamziel]

@alexstine It seems like these Playground URLs were not posted correctly, there's something GitHub does with formatting it seems. I'm figuring out a solution to provide working URLs.

[adamziel]

Alright, sorry for the kerfuffle. I've ended up shipping a new Playground feature to post these links here:

• Website: Support Base64-encoding Blueprints passed in the URL wordpress-playground#1091

Here are working links:

• Post with the WordPress Playground block
• The same post in wp-admin editor

[alexstine]

@adamziel Are you still working on the links to skip the Playground embed?

[adamziel]

@alexstine, yes, that feature isn't a part of the block yet. I expect to ship it next week.

[ironnysh]

Hi all,
I tested the Playground block in Safari and Firefox (on Mac).

General

Almost everything works fine: I was able to add the block and interact with all the options and features available from the sidebar.

The only problem I had was going from Plugin to Editor script mode: adding and running code in Plugin mode worked every time, but Editor script "broke" the preview without providing a meaningful error.

Accessibility

I also tested both links with Axe (the extension isn't supported on Safari)

• The Post with the WordPress Playground block has one issue: <iframe> has no accessible name

To solve this problem, you need to fix at least (1) of the following:
Element has no title attribute
aria-label attribute does not exist or is empty
aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty
Element's default semantics were not overridden with role="none" or role="presentation"

• The same post in wp-admin editor has 31 issues—all are inside the Playground block but 30 originate from Twenty Twenty-Four.
  • The only issue relevant to the block itself is the <iframe> has no accessible name (see above).

Hope it helps :-)

[adamziel]

@ironnysh @alexstine I just released a new version of the plugin where all the reported issues are fixed:

Post with the WordPress Playground block
The same post in wp-admin editor

Are you still working on the links to skip the Playground embed?

@alexstine the plugin now displays a button to activate the live preview. Only after that button is clicked, the iframe is displayed. Does that make the page easier to navigate?

The only problem I had was going from Plugin to Editor script mode: adding and running code in Plugin mode worked every time, but Editor script "broke" the preview without providing a meaningful error.

@ironnysh Good find! I went ahead and removed the ability to change the mode. While useful, it isn't a crucial feature and doesn't have to block this PR.

The Post with the WordPress Playground block has one issue: <iframe> has no accessible name

Thank you for reporting! I just released a new version 0.2.1 that provides an accessible name for that iframe.

[adamziel]

@alexstine would you be able to confirm this recent change made the block more usable?

[alexstine]

@adamziel I don't know where to test it, I don't see it on the links you provided above.

[jonathanbossenger]

@alexstine at the moment, the way I am testing this is via the Learn WordPress local development environment. But I know you've had some problems with the local environment in the past.

This PR only adds the plugin to the list of available plugins for Learn WordPress but does not implement the block anywhere, unless it's physically added by a content creator.

How would you feel about provisionally merging this PR, then I'll add a single instance of this block to a test lesson on Learn WordPress.

We can create this lesson in preview mode, and share the preview URL in a separate GitHub issue in this repository for testing and feedback.

That way any interested parties can test out the block on Learn WordPress, but without it being in use anywhere else on the site.

If we ultimately decide it's not fit for use, it's a minor task to revert the PR, as it's just two lines in the composer.json file.

[alexstine]

@jonathanbossenger Sounds good.

[jonathanbossenger]

Perfect, thanks @alexstine and everyone else involved here.

@pkevan when you have a moment, could I ask you to merge and deploy this change, so we can start testing the playground block on Learn WordPress?

I have created a GitHub issue where we can all test this together once it's merged.

#2352

Once this PR is merged, I will update that issue with a link to the test lesson.

[jonathanbossenger]

@adamwoodnz would you be able to assist getting this PR merge tested and deployed?

[pkevan]

I mentioned this elsewhere but I don't think this will work on wp.org as-is since we don't have build capabilities on deploy, so it would need to be added as a plugin, which might need consideration as it would be enabled network-wide.

[adamziel]

@pkevan ah, bummer! What kind of consideration would be required?

[pkevan]

For completeness, this was added as a plugin from https://plugins.svn.wordpress.org/interactive-code-block/tags/0.2.1/