-
Notifications
You must be signed in to change notification settings - Fork 263
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Docs/Guides: Providing content for your demo #1747
Merged
bgrgicak
merged 7 commits into
WordPress:trunk
from
wordpress-juanmaguitar:docs/guide-providing-content-for-your-demo
Sep 12, 2024
Merged
Changes from all commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
88a9281
Providing content for your demo guide
juanmaguitar a4110b6
Added reference to example in blueprints gallery
juanmaguitar 27782ea
added example for importStarterContent option
juanmaguitar a1e9806
Merge branch 'trunk' into docs/guide-providing-content-for-your-demo
juanmaguitar 1a77571
runPHP
juanmaguitar 6d502e9
Merge branch 'docs/guide-providing-content-for-your-demo' of github.c…
juanmaguitar 048fec6
Merge branch 'trunk' into docs/guide-providing-content-for-your-demo
juanmaguitar File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
210 changes: 210 additions & 0 deletions
210
packages/docs/site/docs/main/guides/providing-content-for-your-demo.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,210 @@ | ||
| --- | ||
| title: Providing content for your demo | ||
| slug: /guides/providing-content-for-your-demo | ||
| description: Providing content for your demo with WordPress Playground | ||
| --- | ||
|
|
||
| One of the things you may want to do to provide a good demo with WordPress Playground is to load default content to better highlight the features of your plugin or theme. This default content may include images or other assets. | ||
|
|
||
| There are several blueprint steps and strategies you can use to import content (or generate it) in the Playground instance: | ||
|
|
||
| ## `importWxr` | ||
|
|
||
| With the [`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/): | ||
|
|
||
| ```json | ||
| "steps": [ | ||
| ..., | ||
| { | ||
| "step": "importWxr", | ||
| "file": { | ||
| "resource": "url", | ||
| "url": "https://raw.githubusercontent.com/WordPress/blueprints/trunk/blueprints/install-activate-setup-theme-from-gh-repo/blueprint-content.xml" | ||
| } | ||
| }, | ||
| ... | ||
| ] | ||
| ``` | ||
|
|
||
| [<kbd> Run Blueprint </kbd>](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/install-activate-setup-theme-from-gh-repo/blueprint.json) [<kbd> See <code>blueprint.json</code> </kbd>](https://github.com/WordPress/blueprints/blob/eb6da7dfa295a095eea2e424c0ae83a219803a8d/blueprints/install-activate-setup-theme-from-gh-repo/blueprint.json#L43) | ||
|
|
||
| :::info | ||
| To include images in your imported content, a good 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}`. | ||
|
|
||
| ```html | ||
| <!-- wp:image {"lightbox":{"enabled":false},"id":4751,"width":"78px","sizeSlug":"full","linkDestination":"none","align":"center","className":"no-border"} --> | ||
| <figure class="wp-block-image aligncenter size-full is-resized no-border"> | ||
| <img src="https://raw.githubusercontent.com/WordPress/blueprints/trunk/blueprints/install-activate-setup-theme-from-gh-repo/images/avatars.png" alt="" class="wp-image-4751" style="width:78px" /> | ||
| </figure> | ||
| <!-- /wp:image --> | ||
| ``` | ||
|
|
||
| ::: | ||
|
|
||
| It is recommended to upload your exported `.xml` file and any referenced assets (such as images) to the same directory as your `blueprint.json` in your GitHub repository. | ||
|
|
||
| ## `importWordPressFiles` | ||
|
|
||
| With the [`importWordPressFiles`](/blueprints/steps#importWordPressFiles) step, you can import your own top-level WordPress files from a given `.zip` file into the instance's root folder. For example, if a `.zip` file contains the `wp-content` and `wp-includes` directories, they will replace the corresponding directories in Playground's root folder. | ||
|
|
||
| This `zip` file can be created from any Playground instance with the "Download as zip" option in the [Playground Options Menu](/web-instance#playground-options-menu). | ||
|
|
||
| You can prepare a demo for your WordPress theme or plugin (including images and other assets) in a Playground instance and then export a snapshot of that demo into a `.zip` file. This file can be imported later using the `importWordPressFiles` step. | ||
|
|
||
| ```json | ||
| { | ||
| "landingPage": "/", | ||
| "login": true, | ||
| "steps": [ | ||
| { | ||
| "step": "importWordPressFiles", | ||
| "wordPressFilesZip": { | ||
| "resource": "url", | ||
| "url": "https://raw.githubusercontent.com/adamziel/playground-sites/main/playground-for-site-builders/playground.zip" | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| [<kbd> Run Blueprint </kbd>](https://playground.wordpress.net/builder/builder.html#{%22landingPage%22:%22/%22,%22login%22:true,%22steps%22:[{%22step%22:%22importWordPressFiles%22,%22wordPressFilesZip%22:{%22resource%22:%22url%22,%22url%22:%22https://raw.githubusercontent.com/adamziel/playground-sites/main/playground-for-site-builders/playground.zip%22}}]}) | ||
|
|
||
| ## `importThemeStarterContent` | ||
|
|
||
| [Some themes have starter content](https://make.wordpress.org/core/2016/11/30/starter-content-for-themes-in-4-7/) that can be published to highlight the features of a theme. | ||
|
|
||
| With the [`importThemeStarterContent` step](/blueprints/steps#importThemeStarterContent) you can publish the starter content of any theme even if that theme is not the one activated in the Playground instance. | ||
|
|
||
| ```json | ||
|
|
||
| "steps": [ | ||
| { | ||
| "step": "installTheme", | ||
| "themeZipFile": { | ||
| "resource": "wordpress.org/themes", | ||
| "slug": "twentytwenty" | ||
| } | ||
| }, | ||
| { | ||
| "step": "installTheme", | ||
| "themeZipFile": { | ||
| "resource": "wordpress.org/themes", | ||
| "slug": "twentytwentyone" | ||
| }, | ||
| "options": { | ||
| "activate": true | ||
| } | ||
| }, | ||
| { | ||
| "step": "importThemeStarterContent", | ||
| "themeSlug": "twentytwenty" | ||
| } | ||
| ] | ||
|
|
||
| ``` | ||
|
|
||
| [<kbd> Run Blueprint </kbd>](https://playground.wordpress.net/builder/builder.html#{%22steps%22:[{%22step%22:%22installTheme%22,%22themeZipFile%22:{%22resource%22:%22wordpress.org/themes%22,%22slug%22:%22twentytwenty%22}},{%22step%22:%22installTheme%22,%22themeZipFile%22:{%22resource%22:%22wordpress.org/themes%22,%22slug%22:%22twentytwentyone%22},%22options%22:{%22activate%22:true}},{%22step%22:%22importThemeStarterContent%22,%22themeSlug%22:%22twentytwenty%22}]}) | ||
|
|
||
| You can also publish the starter content of a theme when installing it with the [`installTheme` step](/blueprints/steps#installTheme) by setting to `true` its `importStarterContent` option: | ||
|
|
||
| ```json | ||
| { | ||
| "steps": [ | ||
| { | ||
| "step": "installTheme", | ||
| "themeZipFile": { | ||
| "resource": "wordpress.org/themes", | ||
| "slug": "twentytwenty" | ||
| }, | ||
| "options": { | ||
| "activate": true, | ||
| "importStarterContent": true | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| [<kbd> Run Blueprint </kbd>](https://playground.wordpress.net/builder/builder.html#{%22steps%22:[{%22step%22:%22installTheme%22,%22themeZipFile%22:{%22resource%22:%22wordpress.org/themes%22,%22slug%22:%22twentytwenty%22},%22options%22:{%22activate%22:true,%22importStarterContent%22:true}}]}) | ||
|
|
||
| ## `wp-cli` | ||
|
|
||
| Another way of generating content for your theme or plugin is via the `wp-cli` step that allows you to run [WP-CLI commands](https://developer.wordpress.org/cli/commands/) such as [`wp post generate`](https://developer.wordpress.org/cli/commands/post/generate/): | ||
|
|
||
| ```json | ||
| { | ||
| "landingPage": "/wp-admin/edit.php", | ||
| "login": true, | ||
| "steps": [ | ||
| { | ||
| "step": "wp-cli", | ||
| "command": "wp post generate --count=20 --post_type=post --post_date=1999-01-04" | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| [<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}]}) | ||
|
|
||
| You can also use the `wp-cli` step in combination with the `writeFile` step to create posts based on existing content and to import images to the Playground instance: | ||
|
|
||
| ```json | ||
| { | ||
| "$schema": "https://playground.wordpress.net/blueprint-schema.json", | ||
| "landingPage": "/?p=4", | ||
| "login": true, | ||
| "steps": [ | ||
| { | ||
| "step": "writeFile", | ||
| "path": "/wordpress/wp-content/postcontent.md", | ||
| "data": { | ||
| "resource": "url", | ||
| "url": "https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/wpcli-post-with-image/postcontent.md" | ||
| } | ||
| }, | ||
| { | ||
| "step": "wp-cli", | ||
| "command": "wp post create --post_title='Welcome to Playground' --post_status='published' /wordpress/wp-content/postcontent.md" | ||
| }, | ||
| { | ||
| "step": "writeFile", | ||
| "path": "/wordpress/wp-content/Select-storage-method.png", | ||
| "data": { | ||
| "resource": "url", | ||
| "url": "https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/wpcli-post-with-image/Select-storage-method.png" | ||
| } | ||
| }, | ||
| { | ||
| "step": "wp-cli", | ||
| "command": "wp media import wordpress/wp-content/Select-storage-method.png --post_id=4 --title='Select your storage method' --featured_image" | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| [<kbd> Run Blueprint </kbd>](https://playground.wordpress.net/builder/builder.html#{%22$schema%22:%22https://playground.wordpress.net/blueprint-schema.json%22,%22meta%22:{%22title%22:%22Use%20wp-cli%20to%20add%20a%20post%20with%20image%22,%22description%22:%22Use%20wp-cli%20to%20create%20a%20post%20from%20text%20file%20with%20block%20markup%20and%20a%20featured%20image%22,%22author%22:%22bph%22,%22categories%22:[%22Content%22,%22wpcli%22]},%22landingPage%22:%22/?p=4%22,%22login%22:true,%22steps%22:[{%22step%22:%22writeFile%22,%22path%22:%22/wordpress/wp-content/postcontent.md%22,%22data%22:{%22resource%22:%22url%22,%22url%22:%22https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/wpcli-post-with-image/postcontent.md%22}},{%22step%22:%22wp-cli%22,%22command%22:%22wp%20post%20create%20--post_title='Welcome%20to%20Playground'%20--post_status='published'%20/wordpress/wp-content/postcontent.md%22},{%22step%22:%22writeFile%22,%22path%22:%22/wordpress/wp-content/Select-storage-method.png%22,%22data%22:{%22resource%22:%22url%22,%22url%22:%22https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/wpcli-post-with-image/Select-storage-method.png%22}},{%22step%22:%22wp-cli%22,%22command%22:%22wp%20media%20import%20wordpress/wp-content/Select-storage-method.png%20--post_id=4%20--title='Select%20your%20storage%20method'%20--featured_image%22}]}) | ||
|
|
||
| :::tip | ||
|
|
||
| Check the ["Use wp-cli to add a post with image"](https://github.com/WordPress/blueprints/tree/trunk/blueprints/wpcli-post-with-image) example from the [Blueprints Gallery](https://github.com/WordPress/blueprints/blob/trunk/GALLERY.md) to see the full example showing the connection between the content and the featured image. | ||
|
|
||
| ::: | ||
|
|
||
| ## `runPHP` | ||
|
|
||
| With the [`runPHP` step](https://wordpress.github.io/wordpress-playground/blueprints/steps#runPHP) you can run any PHP code you require to insert info into your WordPress installation, for example by using the [`wp_insert_post` function](https://developer.wordpress.org/reference/functions/wp_insert_post/). | ||
|
|
||
| ```json | ||
| { | ||
| "landingPage": "/wp-admin/edit.php", | ||
| "login": true, | ||
| "steps": [ | ||
| { | ||
| "step": "runPHP", | ||
| "code": "<?php require_once 'wordpress/wp-load.php'; wp_insert_post(array('post_title' => 'Simple post from PHP', 'post_content' => '<!-- wp:paragraph --><p>This is a simple post inserted with wp_insert_post</p><!-- /wp:paragraph -->', 'post_author' => 1, 'post_status' => 'publish')); ?>" | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| [<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:%22runPHP%22,%22code%22:%22%3C?php%20require_once%20'wordpress/wp-load.php';%20wp_insert_post(array('post_title'%20=%3E%20'Simple%20post%20from%20wp_insert_post',%20'post_content'%20%20=%3E%20'%3C!--%20wp:paragraph%20--%3E%3Cp%3EThis%20is%20a%20simple%20post%20inserted%20with%20wp_insert_post%3C/p%3E%3C!--%20/wp:paragraph%20--%3E',%20'post_author'%20%20%20=%3E%201,%20'post_status'%20=%3E%20'publish'));%20?%3E%22}]}>) | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How would that look? Like this? It probably would warrant another examples
"step": "installTheme", "themeZipFile": { "resource": "wordpress.org/themes", "slug": "twentytwentyone" "importStarterContent": true },There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I added an example using the
importStarterContentoption at 27782ea