Pular para o conteúdo principal

Como usar Blueprints

Você pode usar Blueprints de uma das seguintes maneiras:

  • Passando-os como um fragmento de URL para o Playground.
  • Carregando-os a partir de uma URL usando o parâmetro blueprint-url.
  • Usando pacotes de Blueprint (arquivos ZIP ou diretórios).
  • Usando a API JavaScript.

Fragmento de URL​

A maneira mais fácil de começar a usar Blueprints é colar um deles no "fragmento" da URL no site do WordPress Playground, por exemplo https://playground.wordpress.net/#{"preferredVersions....

Por exemplo, para criar um Playground com versões específicas do WordPress e do PHP, use o seguinte Blueprint:

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

E então acesse https://playground.wordpress.net/#{"preferredVersions":{"php":"8.3","wp":"6.5"}}.

Em JavaScript, você pode obter uma versão compacta de qualquer JSON de Blueprint com JSON.stringify e JSON.parse Exemplo:

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

Você não precisará colar links para acompanhar. Usaremos exemplos de código com um botão "Try it out", que executará automaticamente os exemplos para você:

Fragmentos de Blueprint codificados​

Ao criar links do Playground a partir de JavaScript ou ferramentas de automação, codifique o JSON minificado uma vez com encodeURIComponent() e adicione-o depois 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))}`;

O Playground também aceita Blueprints codificados em Base64. Base64 é útil quando uma plataforma modifica fragmentos JSON ou quando você quer um link compacto e fácil de copiar. Por exemplo, este é o Blueprint acima em formato Base64: eyIkc2NoZW1hIjogImh0dHBzOi8vcGxheWdyb3VuZC53b3JkcHJlc3MubmV0L2JsdWVwcmludC1zY2hlbWEuanNvbiIsInByZWZlcnJlZFZlcnNpb25zIjogeyJwaHAiOiAiNy40Iiwid3AiOiAiNi41In19.

Para executá-lo, acesse https://playground.wordpress.net/#eyIkc2NoZW1hIjogImh0dHBzOi8vcGxheWdyb3VuZC53b3JkcHJlc3MubmV0L2JsdWVwcmludC1zY2hlbWEuanNvbiIsInByZWZlcnJlZFZlcnNpb25zIjogeyJwaHAiOiAiNy40Iiwid3AiOiAiNi41In19

URIError: URI malformed​

Se um link do Playground falhar com URIError: URI malformed, o fragmento de Blueprint codificado geralmente está malformado. Causas comuns incluem um escape % inválido, um fragmento codificado duas vezes ou JSON colado na URL sem codificação.

Reconstrua o link a partir do objeto Blueprint original e codifique-o uma vez:

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

Se outra ferramenta alterar fragmentos de URL, use um Blueprint codificado em Base64.

Em JavaScript, você pode obter qualquer JSON de Blueprint no formato Base64 com a função global btoa().

Exemplo:

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

Carregar Blueprint de uma URL​

Quando o Blueprint ficar grande demais, você pode carregá-lo pelo parâmetro de consulta ?blueprint-url na URL, assim:

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

Observe que o Blueprint deve estar publicamente acessível e ser servido com o cabeçalho Access-Control-Allow-Origin correto:

Access-Control-Allow-Origin: *

Quando uma URL de Blueprint falhar com BlueprintFetchError, verifique estes detalhes:

  • A URL deve retornar um arquivo JSON ou um pacote ZIP de Blueprint, não uma página HTML.
  • URLs do GitHub devem usar raw.githubusercontent.com, não github.com/.../blob/....
  • URLs do GitLab devem usar a URL de arquivo bruto, não uma página /-/blob/.
  • O arquivo deve estar acessível sem login, cookies, VPN ou sessão temporária do navegador.
  • Releases em rascunho, artefatos de CI expirados e URLs temporárias de túnel podem parar de funcionar mesmo que o Blueprint fosse válido antes.
  • Se você hospedar o arquivo, configure CORS para que https://playground.wordpress.net possa buscá-lo.

Pacotes de Blueprint​

O parâmetro ?blueprint-url agora também aceita pacotes de Blueprint no formato ZIP. Um pacote de Blueprint é um arquivo ZIP que contém um arquivo blueprint.json no nível raiz, junto com quaisquer recursos adicionais referenciados pelo Blueprint.

Por exemplo, você pode carregar um pacote de Blueprint assim:

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

Ao usar um pacote de Blueprint, você pode referenciar recursos empacotados com o 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 saber mais sobre pacotes de Blueprint, consulte a documentação de Pacotes de Blueprint.

API JavaScript​

Você também pode usar Blueprints com a API JavaScript usando a função startPlaygroundWeb() do pacote @wp-playground/client. Veja um exemplo pequeno e independente que você pode executar no JSFiddle ou no 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>