Skip to content
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.

Sign up for GitHub

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

Blueprints: Directory Resources #1793

Merged
merged 15 commits into from
Oct 7, 2024
Merged

Blueprints: Directory Resources #1793

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
91bdfb0
Draft DirectoryResoruce
adamziel Sep 21, 2024
12bb446
Introduce a new resource type: Directory. Prototype the first resourc…
adamziel Sep 22, 2024
8636bcb
Accept directory resources in installPlugin, installTheme, writeFiles…
adamziel Sep 23, 2024
cff3355
Adjust types
adamziel Sep 23, 2024
6c2a3da
Rename the resource identifiers
adamziel Sep 23, 2024
e56e750
Merge pluginZipFile and pluginDirectory into pluginData
adamziel Sep 23, 2024
0853b94
Rename pluginZipFile to pluginData in markdown files and comments
adamziel Sep 23, 2024
e490c6f
Keep the previous installPlugin and installTheme JS API options working
adamziel Sep 23, 2024
6a231fe
Add unit tests
adamziel Sep 23, 2024
6448f28
Throw in GitDirectoryResource
adamziel Sep 23, 2024
92473b3
Make the unit tests pass
adamziel Sep 23, 2024
1500eba
Document the writeFiles step
adamziel Sep 23, 2024
a77ce5a
Merge branch 'trunk' into install-plugin-accept-directory
adamziel Oct 7, 2024
289bb1a
Merge branch 'trunk' into install-plugin-accept-directory
adamziel Oct 7, 2024
ac13fd9
Refactor pluginZipFile to pluginData
adamziel Oct 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ You can connect to the Playground using the JavaScript client. Here's an example
},
{
step: 'installPlugin',
pluginZipFile: {
pluginData: {
resource: 'wordpress.org/plugins',
slug: 'friends',
},
Expand Down
2 changes: 1 addition & 1 deletion packages/docs/site/docs/blueprints/01-index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ Because Blueprints can be pasted in the URL, you can embed or link to a Playgrou
"steps": [
{
"step": "installTheme",
"themeZipFile": {
"themeData": {
"resource": "wordpress.org/themes",
"slug": "pendant"
},
Expand Down
2 changes: 1 addition & 1 deletion packages/docs/site/docs/blueprints/02-using-blueprints.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ You can also use Blueprints with the JavaScript API using the `startPlaygroundWe
},
{
step: 'installPlugin',
pluginZipFile: {
pluginData: {
resource: 'wordpress.org/plugins',
slug: 'friends',
},
Expand Down
2 changes: 1 addition & 1 deletion packages/docs/site/docs/blueprints/03-data-format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ Arguably the most powerful property, `steps` allows you to configure the Playgro
},
{
"step": "installPlugin",
"pluginZipFile": {
"pluginData": {
"resource": "wordpress.org/plugins",
"slug": "gutenberg"
}
Expand Down
4 changes: 2 additions & 2 deletions packages/docs/site/docs/blueprints/05-steps-shorthands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,14 +43,14 @@ Or
[
{
"step": "installPlugin",
"pluginZipFile": {
"pluginData": {
"resource": "wordpress.org/plugins",
"slug": "hello-dolly"
}
},
{
"step": "installPlugin",
"pluginZipFile": {
"pluginData": {
"resource": "url",
"url": "https://raw.githubusercontent.com/adamziel/blueprints/trunk/docs/assets/hello-from-the-dashboard.zip"
}
Expand Down
10 changes: 5 additions & 5 deletions packages/docs/site/docs/blueprints/08-examples.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,14 @@ Let's see some cool things you can do with Blueprints.
"steps": [
{
"step": "installPlugin",
"pluginZipFile": {
"pluginData": {
"resource": "wordpress.org/plugins",
"slug": "coblocks"
}
},
{
"step": "installTheme",
"themeZipFile": {
"themeData": {
"resource": "wordpress.org/themes",
"slug": "pendant"
}
Expand Down Expand Up @@ -91,14 +91,14 @@ blueprint={{
"steps": [
{
"step": "installPlugin",
"pluginZipFile": {
"pluginData": {
"resource": "url",
"url": "https://your-site.com/your-plugin.zip"
}
},
{
"step": "installTheme",
"themeZipFile": {
"themeData": {
"resource": "url",
"url": "https://your-site.com/your-theme.zip"
}
Expand Down Expand Up @@ -173,7 +173,7 @@ Use the `writeFile` step to add code to a mu-plugin that runs on every request.
},
{
"step": "installPlugin",
"pluginZipFile": {
"pluginData": {
"resource": "wordpress.org/plugins",
"slug": "interactive-code-block"
}
Expand Down
24 changes: 12 additions & 12 deletions packages/docs/site/docs/blueprints/tutorial/03-build-your-first-blueprint.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ Adventurer is an open-source theme [available in the WordPress theme directory](
"steps": [
{
"step": "installTheme",
"themeZipFile": {
"themeData": {
"resource": "wordpress.org/themes",
"slug": "adventurer"
}
Expand All @@ -117,7 +117,7 @@ The site should now look like the screenshot below:

### Resources

The `themeZipFile` defines a [resource](/blueprints/steps/resources) and referrences an external file required to complete the step. Playground supports different types of resources, including
The `themeData` defines a [resource](/blueprints/steps/resources) and referrences an external file required to complete the step. Playground supports different types of resources, including

- `url`,
- `wordpress.org/themes`,
Expand Down Expand Up @@ -145,14 +145,14 @@ A classic WordPress plugin that displays random lyrics from the song "Hello, Dol
"steps": [
{
"step": "installTheme",
"themeZipFile": {
"themeData": {
"resource": "wordpress.org/themes",
"slug": "adventurer"
}
},
{
"step": "installPlugin",
"pluginZipFile": {
"pluginData": {
"resource": "wordpress.org/plugins",
"slug": "hello-dolly"
}
Expand All @@ -165,7 +165,7 @@ A classic WordPress plugin that displays random lyrics from the song "Hello, Dol

The Hello Dolly plugin is now installed and activated.

Like the `themeZipFile`, the `pluginZipFile` defines a reference to an external file required for the step. The example uses the `wordpress.org/plugins` resource to install the plugin with the matching `slug` from the WordPress plugin directory.
Like the `themeData`, the `pluginData` defines a reference to an external file required for the step. The example uses the `wordpress.org/plugins` resource to install the plugin with the matching `slug` from the WordPress plugin directory.

## 5. Install a custom plugin

Expand Down Expand Up @@ -240,14 +240,14 @@ Here's the complete Blueprint:
"steps": [
{
"step": "installTheme",
"themeZipFile": {
"themeData": {
"resource": "wordpress.org/themes",
"slug": "adventurer"
}
},
{
"step": "installPlugin",
"pluginZipFile": {
"pluginData": {
"resource": "wordpress.org/plugins",
"slug": "hello-dolly"
}
Expand Down Expand Up @@ -289,21 +289,21 @@ Encoding PHP files as `JSON` can be useful for quick testing, but it's inconveni
"steps": [
{
"step": "installTheme",
"themeZipFile": {
"themeData": {
"resource": "wordpress.org/themes",
"slug": "adventurer"
}
},
{
"step": "installPlugin",
"pluginZipFile": {
"pluginData": {
"resource": "wordpress.org/plugins",
"slug": "hello-dolly"
}
},
{
"step": "installPlugin",
"pluginZipFile": {
"pluginData": {
"resource": "url",
"url": "https://raw.githubusercontent.com/wordpress/blueprints/trunk/docs/assets/hello-from-the-dashboard.zip"
}
Expand All @@ -325,7 +325,7 @@ You can shorten that Blueprint even more using the shorthand syntax:
"steps": [
{
"step": "installTheme",
"themeZipFile": {
"themeData": {
"resource": "wordpress.org/themes",
"slug": "adventurer"
}
Expand Down Expand Up @@ -392,7 +392,7 @@ Here's what the final Blueprint looks like:
"steps": [
{
"step": "installTheme",
"themeZipFile": {
"themeData": {
"resource": "wordpress.org/themes",
"slug": "adventurer"
}
Expand Down
10 changes: 5 additions & 5 deletions packages/docs/site/docs/developers/03-build-an-app/01-index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,21 +58,21 @@ You can still showcase it on Playground by using [JSON Blueprints](/blueprints).
"steps": [
{
"step": "installPlugin",
"pluginZipFile": {
"pluginData": {
"resource": "url",
"url": "https://your-site.com/your-plugin.zip"
}
},
{
"step": "installTheme",
"themeZipFile": {
"themeData": {
"resource": "url",
"url": "https://your-site.com/your-theme.zip"
}
},
{
"step": "importWxr",
"pluginZipFile": {
"pluginData": {
"resource": "url",
"url": "https://your-site.com/starter-content.wxr"
}
Expand Down Expand Up @@ -100,7 +100,7 @@ Those zip bundles aren't any different from regular WordPress Plugins, which mea
"steps": [
{
"step": "installPlugin",
"pluginZipFile": {
"pluginData": {
"resource": "url",
"url": "https://your-site.com/pull-request-1234.zip"
}
Expand Down Expand Up @@ -146,7 +146,7 @@ blueprint={{
},
{
"step": "installPlugin",
"pluginZipFile": {
"pluginData": {
"resource": "vfs",
"path": "/wordpress/pr/gutenberg.zip"
}
Expand Down
4 changes: 2 additions & 2 deletions packages/docs/site/docs/developers/06-apis/01-index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ display={`{
},
{
"step": "installPlugin",
"pluginZipFile": {
"pluginData": {
"resource": "wordpress.org/plugins",
"slug": "friends"
}
Expand All @@ -65,7 +65,7 @@ blueprint={{
},
{
step: 'installPlugin',
pluginZipFile: {
pluginData: {
resource: 'wordpress.org/plugins',
slug: 'friends',
},
Expand Down
2 changes: 1 addition & 1 deletion .../site/docs/developers/06-apis/javascript-api/04-blueprint-json-in-api-client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ const client = await startPlaygroundWeb({
{ step: 'login' },
{
step: 'installPlugin',
pluginZipFile: {
pluginData: {
resource: 'wordpress.org/plugins',
slug: 'gutenberg',
},
Expand Down
2 changes: 1 addition & 1 deletion .../docs/developers/06-apis/javascript-api/05-blueprint-functions-in-api-client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ await installPlugin(client, {
// Resources can only be used with JSON Blueprints.
// If you use functions, you must provide the resolved
// file.
pluginZipFile: await fetch(pluginUrl),
pluginData: await fetch(pluginUrl),
});
```

Expand Down
10 changes: 5 additions & 5 deletions packages/docs/site/docs/main/guides/for-plugin-developers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ You can also load any plugin from the WordPress plugins directory by setting the
"steps": [
{
"step": "installPlugin",
"pluginZipFile": {
"pluginData": {
"resource": "wordpress.org/plugins",
"slug": "gutenberg"
}
Expand All @@ -42,15 +42,15 @@ You can also load any plugin from the WordPress plugins directory by setting the
}
```

[<kbd> &nbsp; Run Blueprint &nbsp; </kbd>](https://playground.wordpress.net/builder/builder.html#{%22landingPage%22:%22/wp-admin/plugins.php%22,%22login%22:true,%22steps%22:[{%22step%22:%22installPlugin%22,%22pluginZipFile%22:{%22resource%22:%22wordpress.org/plugins%22,%22slug%22:%22gutenberg%22}}]})
[<kbd> &nbsp; Run Blueprint &nbsp; </kbd>](https://playground.wordpress.net/builder/builder.html#{%22landingPage%22:%22/wp-admin/plugins.php%22,%22login%22:true,%22steps%22:[{%22step%22:%22installPlugin%22,%22pluginData%22:{%22resource%22:%22wordpress.org/plugins%22,%22slug%22:%22gutenberg%22}}]})

Blueprints can be passed to a Playground instance [in several ways](/blueprints/using-blueprints).

### Plugin in a GitHub repository

A plugin stored in a GitHub repository can also be loaded in a Playground instance via Blueprints.

With the `pluginZipFile` property of the [`installPlugin` blueprint step](/blueprints/steps#installPlugin), you can define a [`url` resource](/blueprints/steps/resources#urlreference) that points to the location of the `.zip` file containing the plugin you want to load in the Playground instance.
With the `pluginData` property of the [`installPlugin` blueprint step](/blueprints/steps#installPlugin), you can define a [`url` resource](/blueprints/steps/resources#urlreference) that points to the location of the `.zip` file containing the plugin you want to load in the Playground instance.

To avoid CORS issues, the Playground project provides a [GitHub proxy](https://playground.wordpress.net/proxy) that allows you to generate a `.zip` from a repository (or even a folder inside a repo) containing your plugin.

Expand All @@ -67,7 +67,7 @@ For example, the following `blueprint.json` installs a plugin from a GitHub repo
"steps": [
{
"step": "installPlugin",
"pluginZipFile": {
"pluginData": {
"resource": "url",
"url": "https://github-proxy.com/proxy/?repo=wptrainingteam/devblog-dataviews-plugin"
}
Expand All @@ -76,7 +76,7 @@ For example, the following `blueprint.json` installs a plugin from a GitHub repo
}
```

[<kbd> &nbsp; Run Blueprint &nbsp; </kbd>](https://playground.wordpress.net/builder/builder.html#{%22landingPage%22:%22/wp-admin/admin.php?page=add-media-from-third-party-service%22,%22login%22:true,%22steps%22:[{%22step%22:%22installPlugin%22,%22pluginZipFile%22:{%22resource%22:%22url%22,%22url%22:%22https://github-proxy.com/proxy/?repo=wptrainingteam/devblog-dataviews-plugin%22}}]})
[<kbd> &nbsp; Run Blueprint &nbsp; </kbd>](https://playground.wordpress.net/builder/builder.html#{%22landingPage%22:%22/wp-admin/admin.php?page=add-media-from-third-party-service%22,%22login%22:true,%22steps%22:[{%22step%22:%22installPlugin%22,%22pluginData%22:{%22resource%22:%22url%22,%22url%22:%22https://github-proxy.com/proxy/?repo=wptrainingteam/devblog-dataviews-plugin%22}}]})

### Plugin from code in a file or gist in GitHub

Expand Down
10 changes: 5 additions & 5 deletions packages/docs/site/docs/main/guides/for-theme-developers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ You can also load any theme from the WordPress themes directory by setting the [
"steps": [
{
"step": "installTheme",
"themeZipFile": {
"themeData": {
"resource": "wordpress.org/themes",
"slug": "twentytwenty"
},
Expand All @@ -40,13 +40,13 @@ You can also load any theme from the WordPress themes directory by setting the [
}
```

[<kbd> &nbsp; Run Blueprint &nbsp; </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}}]})
[<kbd> &nbsp; Run Blueprint &nbsp; </kbd>](https://playground.wordpress.net/builder/builder.html#{%22steps%22:[{%22step%22:%22installTheme%22,%22themeData%22:{%22resource%22:%22wordpress.org/themes%22,%22slug%22:%22twentytwenty%22},%22options%22:{%22activate%22:true,%22importStarterContent%22:true}}]})

### Themes in a GitHub repository

A theme stored in a GitHub repository can also be loaded in a Playground instance with Blueprints.

In the `themeZipFile` property of the [`installTheme` blueprint step](/blueprints/steps#InstallThemeStep), you can define a [`url` resource](/blueprints/steps/resources#urlreference) that points to the location of the `.zip` file containing the theme you want to load in the Playground instance.
In the `themeData` property of the [`installTheme` blueprint step](/blueprints/steps#InstallThemeStep), you can define a [`url` resource](/blueprints/steps/resources#urlreference) that points to the location of the `.zip` file containing the theme you want to load in the Playground instance.

To avoid CORS issues, the Playground project provides a [GitHub proxy](https://playground.wordpress.net/proxy) that allows you to generate a `.zip` from a repository (or even a folder inside a repo) containing your or theme.

Expand All @@ -61,7 +61,7 @@ For example the following `blueprint.json` installs a theme from a GitHub reposi
"steps": [
{
"step": "installTheme",
"themeZipFile": {
"themeData": {
"resource": "url",
"url": "https://github-proxy.com/proxy/?repo=Automattic/themes&branch=trunk&directory=assembler"
},
Expand All @@ -73,7 +73,7 @@ For example the following `blueprint.json` installs a theme from a GitHub reposi
}
```

[<kbd> &nbsp; Run Blueprint &nbsp; </kbd>](https://playground.wordpress.net/builder/builder.html#{%22steps%22:[{%22step%22:%22installTheme%22,%22themeZipFile%22:{%22resource%22:%22url%22,%22url%22:%22https://github-proxy.com/proxy/?repo=Automattic/themes&branch=trunk&directory=assembler%22},%22options%22:{%22activate%22:true}}]})
[<kbd> &nbsp; Run Blueprint &nbsp; </kbd>](https://playground.wordpress.net/builder/builder.html#{%22steps%22:[{%22step%22:%22installTheme%22,%22themeData%22:{%22resource%22:%22url%22,%22url%22:%22https://github-proxy.com/proxy/?repo=Automattic/themes&branch=trunk&directory=assembler%22},%22options%22:{%22activate%22:true}}]})

A blueprint can be passed to a Playground instance [in several ways](/blueprints/using-blueprints).

Expand Down
Loading
Loading