Ir al contenido principal

Usar Blueprints

Puedes usar Blueprints de una de estas formas:

  • Pasándolos como un fragmento de URL al Playground.
  • Cargándolos desde una URL con el parámetro blueprint-url.
  • Usando paquetes de Blueprint (archivos ZIP o directorios).
  • Usando la API de JavaScript.

Fragmento de URL​

La forma más sencilla de empezar a usar Blueprints es pegar uno en el "fragmento" de la URL en el sitio de WordPress Playground, por ejemplo https://playground.wordpress.net/#{"preferredVersions....

Por ejemplo, para crear un Playground con versiones específicas de WordPress y PHP, usarías el siguiente Blueprint:

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

Y después irías a https://playground.wordpress.net/#{"preferredVersions":{"php":"8.3","wp":"6.5"}}.

En JavaScript, puedes obtener una versión compacta de cualquier JSON de Blueprint con JSON.stringify y JSON.parse Ejemplo:

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}`;

No tendrás que pegar enlaces para seguir la guía. Usaremos ejemplos de código con un botón "Try it out" que ejecutará automáticamente los ejemplos por ti:

Fragmentos de Blueprint codificados​

Cuando crees enlaces de Playground desde JavaScript o herramientas de automatización, codifica el JSON minificado una vez con encodeURIComponent() y añádelo después de #:

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 también admite Blueprints codificados en Base64. Base64 es útil cuando una plataforma modifica fragmentos JSON o cuando quieres un enlace compacto y fácil de copiar. Por ejemplo, este es el Blueprint anterior en formato Base64: eyIkc2NoZW1hIjogImh0dHBzOi8vcGxheWdyb3VuZC53b3JkcHJlc3MubmV0L2JsdWVwcmludC1zY2hlbWEuanNvbiIsInByZWZlcnJlZFZlcnNpb25zIjogeyJwaHAiOiAiNy40Iiwid3AiOiAiNi41In19.

Para ejecutarlo, ve a https://playground.wordpress.net/#eyIkc2NoZW1hIjogImh0dHBzOi8vcGxheWdyb3VuZC53b3JkcHJlc3MubmV0L2JsdWVwcmludC1zY2hlbWEuanNvbiIsInByZWZlcnJlZFZlcnNpb25zIjogeyJwaHAiOiAiNy40Iiwid3AiOiAiNi41In19

URIError: URI malformed​

Si un enlace de Playground falla con URIError: URI malformed, el fragmento de Blueprint codificado suele estar mal formado. Las causas comunes incluyen un escape % inválido, un fragmento codificado dos veces o JSON pegado en la URL sin codificar.

Reconstruye el enlace desde el objeto Blueprint original y codifícalo una sola vez:

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

Si otra herramienta cambia los fragmentos de URL, usa en su lugar un Blueprint codificado en Base64.

En JavaScript, puedes obtener cualquier JSON de Blueprint en formato Base64 con la función global btoa().

Ejemplo:

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

Cargar un Blueprint desde una URL​

Cuando tu Blueprint sea demasiado grande, puedes cargarlo mediante el parámetro de consulta ?blueprint-url en la URL, así:

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

Ten en cuenta que el Blueprint debe ser accesible públicamente y servirse con el encabezado Access-Control-Allow-Origin correcto:

Access-Control-Allow-Origin: *

Cuando una URL de Blueprint falle con BlueprintFetchError, revisa estos detalles:

  • La URL debe devolver un archivo JSON o un paquete ZIP de Blueprint, no una página HTML.
  • Las URL de GitHub deben usar raw.githubusercontent.com, no github.com/.../blob/....
  • Las URL de GitLab deben usar la URL del archivo sin procesar, no una página /-/blob/.
  • El archivo debe ser accesible sin inicio de sesión, cookies, VPN o una sesión temporal del navegador.
  • Las releases en borrador, los artifacts de CI expirados y las URL temporales de túnel pueden dejar de funcionar aunque el Blueprint fuera válido antes.
  • Si alojas el archivo, configura CORS para que https://playground.wordpress.net pueda obtenerlo.

Paquetes de Blueprint​

El parámetro ?blueprint-url ahora también admite paquetes de Blueprint en formato ZIP. Un paquete de Blueprint es un archivo ZIP que contiene un archivo blueprint.json en el nivel raíz, junto con cualquier recurso adicional referenciado por el Blueprint.

Por ejemplo, puedes cargar un paquete de Blueprint así:

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

Cuando uses un paquete de Blueprint, puedes referenciar recursos incluidos en el paquete con el tipo de recurso bundled:

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

Para más información sobre los paquetes de Blueprint, consulta la documentación de Paquetes de Blueprint.

API de JavaScript​

También puedes usar Blueprints con la API de JavaScript mediante la función startPlaygroundWeb() del paquete @wp-playground/client. Este es un ejemplo pequeño y autónomo que puedes ejecutar en JSFiddle o 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>