Utiliser les Blueprints

Vous pouvez utiliser les Blueprints de l’une des manières suivantes :

En les passant comme fragment d’URL au Playground.
En les chargeant depuis une URL avec le paramètre blueprint-url.
En utilisant des bundles de Blueprint (fichiers ZIP ou répertoires).
En utilisant l’API JavaScript.

Fragment d’URL

La façon la plus simple de commencer avec les Blueprints consiste à en coller un dans le "fragment" de l’URL sur le site WordPress Playground, par exemple https://playground.wordpress.net/#{"preferredVersions....

Par exemple, pour créer un Playground avec des versions précises de WordPress et de PHP, vous utiliseriez le Blueprint suivant :

{
	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
	"preferredVersions": {
		"php": "8.3",
		"wp": "6.5"
	}
}

Puis vous iriez sur https://playground.wordpress.net/#{"preferredVersions":{"php":"8.3","wp":"6.5"}}.

En JavaScript, vous pouvez obtenir une version compacte de n’importe quel JSON de Blueprint avec JSON.stringify et JSON.parse Exemple :

const blueprintJson = `{
	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
	"preferredVersions": {
		"php": "8.3",
		"wp": "6.5"
	}
}`;
const minifiedBlueprintJson = JSON.stringify(JSON.parse(blueprintJson)); // {"preferredVersions":{"php":"8.3","wp":"6.5"}}
const encodedBlueprint = encodeURIComponent(minifiedBlueprintJson);
const playgroundUrl = `https://playground.wordpress.net/#${encodedBlueprint}`;

Vous n’aurez pas à coller de liens pour suivre. Nous utiliserons des exemples de code avec un bouton "Try it out" qui exécutera automatiquement les exemples pour vous :

Fragments de Blueprint encodés

Lorsque vous créez des liens Playground depuis JavaScript ou des outils d’automatisation, encodez une seule fois le JSON minifié avec encodeURIComponent() et ajoutez-le après # :

const blueprint = {
	$schema: 'https://playground.wordpress.net/blueprint-schema.json',
	preferredVersions: {
		php: '8.3',
		wp: '6.5',
	},
};
const playgroundUrl = `https://playground.wordpress.net/#${encodeURIComponent(JSON.stringify(blueprint))}`;

Playground prend aussi en charge les Blueprints encodés en Base64. Base64 est utile lorsqu’une plateforme modifie les fragments JSON ou lorsque vous voulez un lien compact et facile à copier. Par exemple, voici le Blueprint ci-dessus au format Base64 : eyIkc2NoZW1hIjogImh0dHBzOi8vcGxheWdyb3VuZC53b3JkcHJlc3MubmV0L2JsdWVwcmludC1zY2hlbWEuanNvbiIsInByZWZlcnJlZFZlcnNpb25zIjogeyJwaHAiOiAiNy40Iiwid3AiOiAiNi41In19.

Pour l’exécuter, allez sur https://playground.wordpress.net/#eyIkc2NoZW1hIjogImh0dHBzOi8vcGxheWdyb3VuZC53b3JkcHJlc3MubmV0L2JsdWVwcmludC1zY2hlbWEuanNvbiIsInByZWZlcnJlZFZlcnNpb25zIjogeyJwaHAiOiAiNy40Iiwid3AiOiAiNi41In19

URIError: URI malformed

Si un lien Playground échoue avec URIError: URI malformed, le fragment de Blueprint encodé est généralement mal formé. Les causes courantes incluent un échappement % invalide, un fragment encodé deux fois ou du JSON collé dans l’URL sans encodage.

Reconstruisez le lien depuis l’objet Blueprint d’origine et encodez-le une seule fois :

const playgroundUrl = `https://playground.wordpress.net/#${encodeURIComponent(JSON.stringify(blueprint))}`;

Si un autre outil modifie les fragments d’URL, utilisez plutôt un Blueprint encodé en Base64.

En JavaScript, vous pouvez obtenir n’importe quel JSON de Blueprint au format Base64 avec la fonction globale btoa().

Exemple :

const blueprintJson = `{
	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
	"preferredVersions": {
		"php": "8.3",
		"wp": "6.5"
	}
}`;
const minifiedBlueprintJson = btoa(blueprintJson); // eyIkc2NoZW1hIjogImh0dHBzOi8vcGxheWdyb3VuZC53b3JkcHJlc3MubmV0L2JsdWVwcmludC1zY2hlbWEuanNvbiIsInByZWZlcnJlZFZlcnNpb25zIjogeyJwaHAiOiAiNy40Iiwid3AiOiAiNi41In19

Charger un Blueprint depuis une URL

Quand votre Blueprint devient trop volumineux, vous pouvez le charger avec le paramètre de requête ?blueprint-url dans l’URL, comme ceci :

https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/adamziel/blueprints/trunk/blueprints/latest-gutenberg/blueprint.json

Notez que le Blueprint doit être accessible publiquement et servi avec le bon en-tête Access-Control-Allow-Origin :

Access-Control-Allow-Origin: *

Lorsqu’une URL de Blueprint échoue avec BlueprintFetchError, vérifiez ces points :

L’URL doit renvoyer un fichier JSON ou un bundle ZIP de Blueprint, pas une page HTML.
Les URL GitHub doivent utiliser raw.githubusercontent.com, pas github.com/.../blob/....
Les URL GitLab doivent utiliser l’URL du fichier brut, pas une page /-/blob/.
Le fichier doit être accessible sans connexion, cookies, VPN ni session temporaire du navigateur.
Les releases en brouillon, les artifacts CI expirés et les URL temporaires de tunnel peuvent cesser de fonctionner même si le Blueprint était valide auparavant.
Si vous hébergez le fichier vous-même, configurez CORS pour que https://playground.wordpress.net puisse le récupérer.

Bundles de Blueprint

Le paramètre ?blueprint-url prend maintenant aussi en charge les bundles de Blueprint au format ZIP. Un bundle de Blueprint est un fichier ZIP qui contient un fichier blueprint.json à la racine, avec les ressources supplémentaires référencées par le Blueprint.

Par exemple, vous pouvez charger un bundle de Blueprint comme ceci :

https://playground.wordpress.net/?blueprint-url=https://example.com/my-blueprint-bundle.zip

Lorsque vous utilisez un bundle de Blueprint, vous pouvez référencer les ressources incluses avec le type de ressource bundled :

{
	"landingPage": "/my-file.txt",
	"steps": [
		{
			"step": "writeFile",
			"path": "/wordpress/my-file.txt",
			"data": {
				"resource": "bundled",
				"path": "/bundled-text-file.txt"
			}
		}
	]
}

Pour plus d’informations sur les bundles de Blueprint, consultez la documentation des Bundles de Blueprint.

API JavaScript

Vous pouvez aussi utiliser les Blueprints avec l’API JavaScript grâce à la fonction startPlaygroundWeb() du paquet @wp-playground/client. Voici un petit exemple autonome que vous pouvez exécuter sur JSFiddle ou CodePen :

<iframe id="wp-playground" style="width: 1200px; height: 800px"></iframe>
<script type="module">
	import { startPlaygroundWeb } from 'https://playground.wordpress.net/client/index.js';

	const client = await startPlaygroundWeb({
		iframe: document.getElementById('wp-playground'),
		remoteUrl: `https://playground.wordpress.net/remote.html`,
		blueprint: {
			landingPage: '/wp-admin/',
			preferredVersions: {
				php: '8.3',
				wp: 'latest',
			},
			steps: [
				{
					step: 'login',
					username: 'admin',
					password: 'password',
				},
				{
					step: 'installPlugin',
					pluginData: {
						resource: 'wordpress.org/plugins',
						slug: 'friends',
					},
				},
			],
		},
	});

	const response = await client.run({
		// wp-load.php is only required if you want to interact with WordPress.
		code: '<?php require_once "/wordpress/wp-load.php"; $posts = get_posts(); echo "Post Title: " . $posts[0]->post_title;',
	});
	console.log(response.text);
</script>

Fragment d’URL​

Fragments de Blueprint encodés​

URIError: URI malformed​

Charger un Blueprint depuis une URL​

Bundles de Blueprint​

API JavaScript​