Docs/Guides: WordPress Playground for theme developers #1732
Conversation
…s-juanmaguitar/wordpress-playground into docs/guide-for-theme-developers
| `https://playground.wordpress.net/#{"preferredVersions":{"php":"7.4","wp":"6.5"}}`. | ||
|
|
||
| :::tip | ||
| In Javascript, you can get a compact version of any blueprint json with [`JSON.stringify`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) and [`JSON.parse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) |
There was a problem hiding this comment.
I believe we should spell "json" as "JSON" according to the style guide: https://make.wordpress.org/docs/style-guide/formatting/filenames/
| @@ -45,6 +62,24 @@ Some tools, including GitHub, might not format the Blueprint correctly when past | |||
|
|
|||
| To run it, go to https://playground.wordpress.net/#eyIkc2NoZW1hIjogImh0dHBzOi8vcGxheWdyb3VuZC53b3JkcHJlc3MubmV0L2JsdWVwcmludC1zY2hlbWEuanNvbiIsInByZWZlcnJlZFZlcnNpb25zIjogeyJwaHAiOiAiNy40Iiwid3AiOiAiNi41In19 | |||
|
|
|||
| :::tip | |||
| In Javascript, You can get any blueprint json in [Base64 format](https://developer.mozilla.org/en-US/docs/Glossary/Base64#javascript_support) with global function `btoa()` | |||
There was a problem hiding this comment.
Needs period at the end of sentence:
with global function btoa().
| @@ -4,4 +4,225 @@ slug: /for-theme-developers | |||
| description: WordPress Playground for Theme Developers | |||
| --- | |||
|
|
|||
| what Playground tools can I use in my development workflow | |||
| The WordPress Playground is an innovative tool that allows theme developers to build, test and showcase their themes directly in a browser environment. | |||
There was a problem hiding this comment.
Add comma after "test."
"build, test, and showcase"
|
|
||
| ### `resetData` | ||
|
|
||
| With [`resetData`](/blueprints/steps#resetData) step, you can remove the default content of a WordPress installation in order to import your own content. |
There was a problem hiding this comment.
Add "the" after "With":
With the resetData step...
|
|
||
| ### `writeFile` | ||
|
|
||
| With [`writeFile`](/blueprints/steps#resetData) step, you can write data to a file at a specified path. You may want to use this step to write custom PHP code in a PHP file inside the `mu-plugins` of the Playground WordPress instance, so the code is executed automatically when the instance is loaded. |
There was a problem hiding this comment.
Add "the" after "With":
With the writeFile step...
There was a problem hiding this comment.
I think you also mean "mu-plugins directory". It's not 100% clear from the text.
|
|
||
| ### `updateUserMeta` | ||
|
|
||
| With [`updateUserMeta`](/blueprints/steps#updateUserMeta) step, you can update any user metadata. For example, you could update the metadata of the default `admin` user of any WordPress installation: |
There was a problem hiding this comment.
Add "the" after "With":
With the updateUserMeta step...
|
|
||
| ### `importWxr` | ||
|
|
||
| With [`importWxr`](/blueprints/steps#importWxr) step, you can import your own content via a `.xml` file previously [exported from an existing WordPress installation](https://wordpress.org/documentation/article/tools-export-screen/): |
There was a problem hiding this comment.
Add "the" after "With":
With the importWxr step...
| ] | ||
| ``` | ||
|
|
||
| It is recommended that the exported `.xml` is uploaded to GitHub repository in the same directory the `blueprint.json` is |
There was a problem hiding this comment.
A few corrections and slightly better sentence structure:
It is recommended to upload your exported .xml file to the same directory as your blueprint.json in your GitHub repository.
| It is recommended that the exported `.xml` is uploaded to GitHub repository in the same directory the `blueprint.json` is | ||
|
|
||
| :::tip | ||
| One of the things you'll want to import for your default content are images. A recommended approach is to upload the images to your GitHub repo and search/replace the path for them in the exported `.xml` file using the URL format: `https://raw.githubusercontent.com/{repo}/{branch}/{image_path}` |
There was a problem hiding this comment.
"are" should be "is" in the first sentence:
One of the things you'll want to import for your default content is images.
|
|
||
| ### `setSiteOptions` | ||
|
|
||
| With [`setSiteOptions`](/blueprints/steps#setSiteOptions) step, you can set [site options](https://developer.wordpress.org/apis/options/#available-options-by-category) such as site name, description or which page to use for posts. |
There was a problem hiding this comment.
Three issues:
- "With" should have "the" after it.
- There's a missing comma after "description."
- There's a parallelism issue with the last item in the list (doesn't match the structure of the previous items.
Try this:
With the setSiteOptions step, you can set site options such as the site name, description, or page to use for posts.
| ] | ||
| ``` | ||
|
|
||
| There's also a shorthand [`siteOptions`](/blueprints/steps/shorthands#siteoptions) than can be used instead of the `setSiteOptions` step. |
There was a problem hiding this comment.
"a shorthand siteOptions ___ that can be used..."
Should "step" be there in the blank? Or, should it be written "siteOptions shorthand"?
There was a problem hiding this comment.
Yes, I think this sounds better
There's also a
siteOptionsshorthand that can be used instead of thesetSiteOptionsstep.
|
|
||
| ### `plugins` | ||
|
|
||
| With the shorthand [`plugins`](/blueprints/steps/shorthands#plugins) you can set a list of plugins you want to be installed and activated with your theme in the Playground instance. |
There was a problem hiding this comment.
Same potential issue here as above. I think this should read as:
With the plugins shorthand...
| "plugins": ["todo-list-block", "markdown-comment-block"] | ||
| ``` | ||
|
|
||
| You can also use the [`installPlugin`](/blueprints/steps#installPlugin) step to install and activate plugins for your Playground instance but the shorthand way is recommended |
There was a problem hiding this comment.
Add a period at the end of the sentence.
|
|
||
| ### `login` | ||
|
|
||
| With the shorthand [`login`](/blueprints/steps/shorthands#login) you can launch your Playground instance with the user logged |
There was a problem hiding this comment.
At the end of the sentence:
...with the user logged in:
|
|
||
| ### Local theme development and testing with Playground | ||
|
|
||
| From the root folder of a block theme's code, you can quickly load locally a Playground instance with that theme loaded and activated by launching the [`wp-now` command](/developers/local-development/wp-now) or the [Visual Code Studio extension](/developers/local-development/vscode-extension). |
There was a problem hiding this comment.
It's not clear where the reader would put the following code. To this point, they've been working in JSON files. It should be clear that this step would use a command line program. Keep in mind that many theme authors are going to be less familiar with this.
Something like this would work:
"...by launcing the wp-now command from your preferred command line program.
There was a problem hiding this comment.
I tweaked the sentence into:
From the root folder of a block theme's code, you can quickly load locally a Playground instance with that theme loaded and activated. You can do that by launching, in a theme directory, the
wp-nowcommand from your preferred command line program or the Visual Code Studio extension from the Visual Studio Code IDE.
|
|
||
| You can connect your Playground instance to a GitHub repository and create a Pull Request with the changes you’ve done through the WordPress UI in the Playground instance, leveraging the [Create Block Theme](https://wordpress.org/plugins/create-block-theme/) plugin. You can also make changes to that theme and export a zip. | ||
|
|
||
| Note that you'll need [Create Block Theme](https://wordpress.org/plugins/create-block-theme/) plugin installed and activated in the Playground instance in order to use this workflow. |
There was a problem hiding this comment.
Add "the" before "Create Block Theme."
|
|
||
| :::tip | ||
|
|
||
| Check [About Playground > Build > Save changes done on a Block Theme and create GitHub Pull Requests](/about/build#save-changes-done-on-a-block-theme-and-create-github-pull-requests) for more info |
There was a problem hiding this comment.
Add period at the end of the sentence.
|
Thanks for your review @justintadlock |
…s-juanmaguitar/wordpress-playground into docs/guide-for-theme-developers
juanmaguitar
changed the title
| @@ -93,11 +93,11 @@ Some useful tools and resources provided by the Playground project to work with | |||
|
|
|||
| Through properties and [`steps`](/blueprints/steps) in the blueprint, you can configure the initial setup of your theme in the Playground instance. | |||
|
|
|||
| ### Importing content for your demo | |||
| ### Providing content for your demo | |||
|
|
|||
| One of the things you may want to do to provide a good demo of your theme via Playground is to load default content to better highlight the features of your theme. This default content may include images or other assets. | |||
There was a problem hiding this comment.
The first sentence seems a bit long. See if this tightens it up a bit.
"To provide a good demo of your theme via Playground, you may want to load it with default content that highlights the features of your theme. "
There was a problem hiding this comment.
Thanks for the suggestion!
I have extracted the whole "Providing content for your demo" section into a new guide (see #1747) to reference this content from both the "Playground for theme developers" and "Playground for plugin developers" guides.
I have updated this PR with your suggested shorter version in the info callout referencing the "Providing content for your demo" guide
| ``` | ||
|
|
||
| [<kbd> Run Blueprint </kbd>](https://playground.wordpress.net/builder/builder.html#{%22landingPage%22:%22/wp-admin/edit.php%22,%22login%22:true,%22steps%22:[{%22step%22:%22wp-cli%22,%22command%22:%22wp%20post%20generate%20--count=20%20--post_type=post%20--post_date=1999-01-04%22}]}) | ||
|
|
There was a problem hiding this comment.
You could also link to the Blueprint Gallery entry of https://github.com/WordPress/blueprints/tree/trunk/blueprints/wpcli-post-with-image
The shows the connection between content and featured image.
There was a problem hiding this comment.
I added a tip referencing that example
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
This PR addresses #1664 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 _Note: There was an older version of this PR at #1745 that was closed_ --------- Co-authored-by: Birgit Pauli-Haack <[email protected]>
This PR addresses #1663
This PR belong to a set of three guides that are meant to be published together