Docs/Guides: WordPress Playground for plugin developers #1750
Conversation
juanmaguitar
requested review from
bph,
adamziel,
justintadlock,
ndiego and
ryanwelcher
|
|
||
| The WordPress Playground is an innovative tool that allows plugin developers to build, test and showcase their plugins directly in a browser environment. | ||
|
|
||
| This guide will explore **how you can leverage the WordPress Playground to enhance your plugin development workflow, create live demos to showcase your WordPress plugin to the world, and streamline your plugin testing process**. |
There was a problem hiding this comment.
bolding beyond a few words is super distracting, and when it's two lines, it kind of looses the emphasize and blends just in.
|
|
||
| ### Plugin in the WordPress themes directory | ||
|
|
||
| With WordPress Playground, you can quickly launch a WordPress installation with any plugin available in the [WordPress Plugins Directory](https://wordpress.org/plugins/) installed and activated. Simply pass the `plugin` [query parameter](/developers/apis/query-api) to the [Playground URL](https://playground.wordpress.net) like this: https://playground.wordpress.net/?plugin=gutenberg. |
There was a problem hiding this comment.
"any" mean every plugin, and that's probably not the case. I would feather it with 'almost any'
I think this would need a bit more explanations, as a plugin developer might not have read the other pages in the documentation.
"All you need to do is add 'plugin' as a query parameter to the URL and use the slug of the plugin from the WordPress directory as value" It might be better illustrated with a multi-word plugin slug like
https://playground.wordpress.net/?plugin=create-block-theme
There was a problem hiding this comment.
"any" mean every plugin, and that's probably not the case. I would feather it with 'almost any'
What do you mean by this? Is there any case that you know of of a plugin published in the WordPress Plugins Directory that cannot be loaded in a WordPress Playground instance?
There was a problem hiding this comment.
Yes, there are quite a few because they need additional PHP modules or other additional configurations. It might be going down, but you can't assume that every plugin works with Playground.
There was a problem hiding this comment.
I see. Thanks for the clarification.
I'll add the almost any 👍
| "path": "/wordpress/wp-content/plugins/0-plugin.php", | ||
| "data": { | ||
| "resource": "url", | ||
| "url": "https://gist.githubusercontent.com/ndiego/456b74b243d86c97cda89264c68cbdee/raw/ff00cf25e6eebe4f5a4eaecff10286f71e65340b/block-hooks-demo.php" |
There was a problem hiding this comment.
Not a blocker:
We should adhere to the external links policies of the documentation team, and not link to personal GitHub spaces.
Maybe that Gist can be moved to the /wptrainingteam, too or can be brought over to the blueprints gallery repo.
There was a problem hiding this comment.
I agree, but AFAIK gists are only available under GitHub users and not organizations. Is there any "WordPress user " we could use for this?
In this case, maybe we need to blend the external links policies a little bit in order to show this capability of WP Playground. This example is taken from an example in the Blueprints Gallery
There was a problem hiding this comment.
In a different blueprint example, the file was uploaded to the directory of the examples. Maybe we can modify that examples.
There was a problem hiding this comment.
I have changed the displayed example to use the file at the Blueprints Gallery GitHub repo and added a tip callout referencing the example in the GitHub Gallery creating a plugin from the code in a gist
| Some useful tools and resources provided by the Playground project to work with blueprints are: | ||
|
|
||
| - Check the [Blueprints Gallery](https://github.com/WordPress/blueprints/blob/trunk/GALLERY.md) to explore real-world code examples of using WordPress Playground to launch a WordPress site with a variety of setups. | ||
| - The [WordPress Playground Step Library](https://akirk.github.io/playground-step-library/#) tool provides a visual interface to drag or click the steps to create a blueprint for WordPress Playground. You can also create your own steps! |
There was a problem hiding this comment.
Again, not a blocker, but as soon as you add the Playground Step Library to the official documentation, it also becomes official. There should be a plan to bring the Playground Step Library to the /WordPress organization, even if it's just a experimental repo.
There was a problem hiding this comment.
This is a good point, but I'm not sure, it should stop us from sharing valuable resources with the community at this stage.
There are a lot of "non-official" resources recommended from the Links and Resources section. For example, the https://github-proxy.com/ tool itself is also not part of the /WordPress organization.
I would open a broader conversation about this, but in the meantime I would continue sharing as many helpful resources we can to ease the work with WordPress Playground.
cc: @adam
There was a problem hiding this comment.
As I said, it's not a blocker to this PR, but I do feel strongly to at least try to bring these tools inside WordPress as soon as possible. It adds to the credibility and the increases developer trust. It shouldn't be too difficult to adhere to the policy as we are all in those spaces anyway.
There was a problem hiding this comment.
at least try to bring these tools inside WordPress as soon as possible
I agree 🤝
|
|
||
| ::: | ||
|
|
||
| Through properties and [`steps`](/blueprints/steps) in the Blueprint, you can configure the Playground instance's initial setup, providing your plugins with the content and configuration needed for proper showcasing. |
There was a problem hiding this comment.
"(...) and configuration needed for proper showcasing" seems to lack a noun, and proper might not be the right word....
Try something like this:
"(... and configuration needed for showcasing your plugin's compelling features and functionality."
There was a problem hiding this comment.
Sounds much better. Thanks!
|
|
||
| :::info | ||
|
|
||
| One thing you may want to do to provide a good demo with WordPress Playground is to load default content to better showcase the features of your plugin or theme. Check out the [Providing content for your demo](/guides/providing-content-for-your-demo) guide to learn more |
There was a problem hiding this comment.
That sentence feels a bit to long... Something like this might tighten it up a bit:
"A great demo with WordPress Playground, might require that you load default content for your plugin and theme."
|
|
||
| ### `writeFile` | ||
|
|
||
| With the `writeFile` step you can create on the fly any plugin file taking the code from a file stored on a GitHub repo or a gist. |
There was a problem hiding this comment.
Try: "With the writefile step you can create any plugin file on the fly, referencing code from a *.php file stored on a GitHub or Gist."
|
|
||
| ### Local plugin development and testing with Playground | ||
|
|
||
| From a plugins' folder in your local development environment, you can quickly load locally a Playground instance with that plugin loaded and activated. You can do that by launching, in the plugin's directory, the [`wp-now` command](/developers/local-development/wp-now) from your preferred command line program or the [Visual Code Studio extension](/developers/local-development/vscode-extension) from the [Visual Studio Code](https://code.visualstudio.com/) IDE. |
There was a problem hiding this comment.
"With WP-Now, you can quickly load a Playground instance locally from a plugin's folder, with that plugin loaded and activated. Use the wp-now command from the command line of your plugin's root directory. "
..Not sure whether that's better...
Co-authored-by: Birgit Pauli-Haack <[email protected]>
Co-authored-by: Birgit Pauli-Haack <[email protected]>
…ress-juanmaguitar/wordpress-playground into docs/guide-for-plugin-developers-2
|
Thanks for your feedback @bph |
As both #1664 and #1663 require info about how to provide content for a demo in Playground I think it's best to create a separate guide with this topic that can be referenced from these guides This PR belong to a set of three guides that are meant to be published together - WordPress Playground for Theme Developers #1732 - WordPress Playground for Plugin Developers #1750 - Providing content for your demo #1747
…ress-juanmaguitar/wordpress-playground into docs/guide-for-plugin-developers-2
Co-authored-by: Birgit Pauli-Haack <[email protected]>
This PR addresses #1664
This PR belong to a set of three guides that are meant to be published together
Note: There was an older version of this PR at #1745 that was closed