Aller au contenu principal

Références de ressources

Les « Resource References » vous permettent d’utiliser des fichiers externes dans les Blueprints.

Les étapes de Blueprint comme installPlugin ou installTheme nécessitent l’emplacement de l’extension ou du thème à installer.

Cet emplacement peut être défini comme une ressource URL du fichier .zip contenant le thème ou l’extension. Il peut aussi être défini comme une ressource wordpress.org/plugins ou wordpress.org/themes pour les extensions/thèmes publiés dans les répertoires officiels WordPress.

Les références de ressources suivantes sont disponibles :

URLReference​

La ressource URLReference sert à référencer des fichiers stockés sur un serveur distant. La ressource URLReference est définie comme suit :

type URLReference = {
	resource: 'url';
	url: string;
};

Pour utiliser la ressource URLReference, vous devez fournir l’URL du fichier. Par exemple, pour référencer un fichier nommé "index.html" stocké sur un serveur distant, vous pouvez créer une URLReference comme suit :

{
	"resource": "url",
	"url": "https://example.com/index.html"
}

La ressource url fonctionne avec des étapes de Blueprint comme installPlugin ou installTheme. Ces étapes nécessitent un ResourceType pour définir l’emplacement de l’extension ou du thème à installer.

Avec "resource": "url", nous pouvons définir l’emplacement d’un .zip contenant l’extension/le thème. Utilisez cette option pour des artifacts ZIP construits hébergés sur une URL accessible publiquement qui ne nécessite pas d’authentification, comme un asset de release. Les URL de téléchargement direct d’artifacts CI peuvent fonctionner, mais elles sont souvent de courte durée ou restreintes.

Pour du code source stocké dans un dépôt Git, préférez git:directory. Cette ressource peut récupérer un sous-répertoire de dépôt depuis une branche, une étiquette ou un commit sans nécessiter d’archive ZIP.

Avant d’utiliser une ressource url, vérifiez que l’URL :

  • Télécharge directement le fichier. Elle ne doit pas renvoyer une page HTML, un avertissement de redirection, une page de connexion, un aperçu de fichier de dépôt ni une page d’erreur de proxy.
  • Est disponible sans cookies, authentification, VPN ni session temporaire de navigateur.
  • Envoie des en-têtes CORS qui autorisent Playground à la récupérer.
  • Pointe vers le type de fichier attendu. installPlugin et installTheme nécessitent une archive ZIP d’extension ou de thème, sauf si vous utilisez un autre type de ressource.
  • Restera disponible. Les URL de tunnel temporaires, les assets de release en brouillon et les artifacts CI de courte durée peuvent expirer.
  • Est une véritable archive ZIP lorsque l’étape attend un ZIP. Les téléchargements très petits signifient souvent que le serveur a renvoyé une page d’erreur HTML au lieu de l’archive.

Pour du code source GitHub, ne faites pas pointer url vers une page de dépôt ou un ZIP généré depuis une branche lorsque vous pouvez utiliser git:directory. Utilisez url pour des artifacts ZIP construits et git:directory pour des répertoires de source.

GitDirectoryReference​

La ressource GitDirectoryReference sert à référencer un répertoire dans un dépôt Git. C’est utile lorsqu’une extension ou un thème se trouve dans un sous-dossier d’un dépôt, ou lorsque vous voulez installer depuis une branche, une étiquette ou un commit précis.

type GitDirectoryReference = {
	resource: 'git:directory';
	url: string; // Repository URL (https://, ssh git@..., etc.)
	path?: string; // Optional subdirectory inside the repository
	ref?: string; // Branch, tag, or commit SHA (defaults to HEAD)
	refType?: 'branch' | 'tag' | 'commit'; // Hint for resolving the ref
	'.git'?: boolean; // Experimental: include a .git directory with fetched metadata
};

Exemple :

{
	"step": "installPlugin",
	"pluginData": {
		"resource": "git:directory",
		"url": "https://github.com/WordPress/block-development-examples",
		"ref": "HEAD",
		"path": "plugins/data-basics-59c8f8"
	},
	"options": {
		"activate": true,
		"targetFolderName": "data-basics"
	}
}

Notes :

  • Lorsque vous utilisez un nom de branche ou d’étiquette pour ref, vous devez indiquer refType (par exemple "refType": "branch"). Sans cela, seul HEAD est résolu de façon fiable.
  • Playground détecte automatiquement les fournisseurs comme GitHub et GitLab.
  • Les URL de dépôt peuvent inclure ou omettre un suffixe final .git. Les barres obliques finales supplémentaires sont ignorées.
  • Cette ressource gère les récupérations via proxy CORS et les sparse checkouts ; vous pouvez donc utiliser des URL qui pointent vers des sous-répertoires ou branches précis.
  • Cette ressource peut être utilisée avec des étapes comme installPlugin et installTheme.
  • Définissez ".git": true pour inclure un dossier .git contenant les packfiles et les refs afin que les outils sensibles à Git puissent détecter le checkout. Cela reflète actuellement un clone superficiel de la ref sélectionnée.
  • Le nom du dossier est dérivé de l’URL par défaut (par exemple https-github-com-WordPress-block-development-examples-HEAD-at-plugins-data-basics-59c8f8). Utilisez options.targetFolderName dans l’étape pour le remplacer, comme dans l’exemple ci-dessus.

CoreThemeReference​

La ressource CoreThemeReference sert à référencer les thèmes du cœur WordPress. La ressource CoreThemeReference est définie comme suit :

type CoreThemeReference = {
	resource: 'wordpress.org/themes';
	slug: string;
	version?: string;
};

Pour utiliser la ressource CoreThemeReference, vous devez fournir le slug du thème. Par exemple, pour référencer le thème "Twenty Twenty-One", vous pouvez créer une CoreThemeReference comme suit :

{
	"resource": "wordpress.org/themes",
	"slug": "twentytwentyone"
}

CorePluginReference​

La ressource CorePluginReference sert à référencer les extensions du cœur WordPress. La ressource CorePluginReference est définie comme suit :

type CorePluginReference = {
	resource: 'wordpress.org/plugins';
	slug: string;
	version?: string;
};

Pour utiliser la ressource CorePluginReference, vous devez fournir le slug de l’extension. Par exemple, pour référencer l’extension "Akismet", vous pouvez créer une CorePluginReference comme suit :

{
	"resource": "wordpress.org/plugins",
	"slug": "akismet"
}

VFSReference​

La ressource VFSReference sert à référencer des fichiers stockés dans un système de fichiers virtuel (VFS). Le VFS est un système de fichiers stocké en mémoire qui peut servir à stocker des fichiers ne faisant pas partie du système de fichiers du système d’exploitation. La ressource VFSReference est définie comme suit :

type VFSReference = {
	resource: 'vfs';
	path: string;
};

Pour utiliser la ressource VFSReference, vous devez fournir le chemin vers le fichier dans le VFS. Par exemple, pour référencer un fichier nommé "index.html" stocké à la racine du VFS, vous pouvez créer une VFSReference comme suit :

{
	"resource": "vfs",
	"path": "/index.html"
}

LiteralReference​

La ressource LiteralReference sert à référencer des fichiers stockés comme littéraux dans le code. La ressource LiteralReference est définie comme suit :

type LiteralReference = {
	resource: 'literal';
	name: string;
	contents: string | Uint8Array;
};

Pour utiliser la ressource LiteralReference, vous devez fournir le nom du fichier et son contenu. Par exemple, pour référencer un fichier nommé "index.html" qui contient le texte "Hello, World!", vous pouvez créer une LiteralReference comme suit :

{
	"resource": "literal",
	"name": "index.html",
	"contents": "Hello, World!"
}

BundledReference​

La ressource BundledReference sert à référencer des fichiers inclus avec le Blueprint lui-même. C’est particulièrement utile pour créer des bundles de Blueprint autonomes qui incluent toutes les ressources nécessaires. La ressource BundledReference est définie comme suit :

type BundledReference = {
	resource: 'bundled';
	path: string;
};

Pour utiliser la ressource BundledReference, vous devez fournir le chemin relatif vers le fichier dans le bundle. Par exemple, pour référencer un fichier nommé "plugin.php" inclus avec le Blueprint, vous pouvez créer une BundledReference comme suit :

{
	"resource": "bundled",
	"path": "plugin.php"
}

Les bundles de Blueprint peuvent être distribués dans différents formats, notamment :

  • Des fichiers ZIP avec un fichier blueprint.json au premier niveau.
  • Des répertoires contenant un fichier blueprint.json et les ressources associées.
  • Des URL distantes où le Blueprint et ses ressources sont hébergés ensemble.

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