Zum Inhalt springen

Logische Erkennungsquellen

Blockstudio erkennt Dateien standardmäßig in physischen Theme-Verzeichnissen. Laufzeittools können diese Verzeichnisse durch einen logischen Bestand ersetzen. Das ist nützlich für Vorschauen, Overlays, generierte Themes, Remote-Mounts und andere Umgebungen, in denen zusammengehörige Dateien kein gemeinsames physisches Stammverzeichnis haben.

Blockstudio parst und registriert weiterhin Blöcke, Seiten, Sammlungen, Muster, Felder, Templates und Template-Teile. Die Quelle legt lediglich fest, welche logischen Dateien sichtbar sind und wo jede sichtbare Datei gelesen werden kann.

Bestandsquellen

Verwende den Filter blockstudio/discovery/sources, um die standardmäßigen Objekte Filesystem_Discovery_Source zu ersetzen:

PHP
use Blockstudio\Inventory_Discovery_Source;

add_filter(
    'blockstudio/discovery/sources',
    function (array $sources, string $context, array $paths): array {
        if ('blocks' !== $context) {
            return $sources;
        }

        return [
            new Inventory_Discovery_Source(
                'preview:feature-card',
                '/runtime-preview/feature-card/blockstudio',
                [
                    'card/block.json' => [
                        'path' => '/theme/blockstudio/card/block.json',
                        'provenance' => [
                            'layer' => 'parent',
                            'inherited' => true,
                        ],
                    ],
                    'card/index.php' => [
                        'path' => '/runtime-preview/feature-card/blockstudio/card/index.php',
                        'provenance' => [
                            'layer' => 'preview',
                        ],
                    ],
                ],
                'parent-and-preview-fingerprint',
                ['/theme/blockstudio', '/runtime-preview/feature-card/blockstudio']
            ),
        ];
    },
    10,
    3
);

Verfügbare Kontexte:

  • blocks
  • fields
  • pages
  • patterns
  • site-templates
  • site-template-parts

Ein Bestand entspricht dem endgültig sichtbaren Verzeichnisbaum. Füge Ebenen zusammen, bevor du ihn zurückgibst:

  • Verwende für jeden sichtbaren logischen Pfad einen Eintrag.
  • Lass die ausgewählte Ebene den physischen Pfad bereitstellen.
  • Lass gelöschte logische Pfade aus.
  • Gib die Einträge in beliebiger Reihenfolge zurück. Blockstudio sortiert sie nach logischem Pfad.
  • Füge leere logische Verzeichnisse im optionalen sechsten Argument des Konstruktors hinzu, wenn die Sichtbarkeit von Verzeichnissen wichtig ist.

Inventory_Discovery_Source eignet sich für bestandsbasierte Arrays. Integrationen können die Schnittstelle Discovery_Source implementieren, wenn Einträge verzögert aufgelöst werden oder aus einem anderen Speichersystem stammen.

Auflösung von Geschwisterpfaden

Logische Geschwister können auf unterschiedliche physische Stammverzeichnisse verweisen. Ein übergeordnetes block.json kann ein Overlay index.php verwenden, und eine Overlay-Seite kann ihr übergeordnetes pages.json, ihren Loader oder ihr Layout übernehmen. Blockstudio löst diese Beziehungen anhand des logischen Pfads auf, bevor die ausgewählten physischen Dateien gelesen werden.

Loader-Pfade außerhalb einer Sammlung behalten die bestehende Sicherheitsgrenze von blockstudio/pages/allow_external_loader_path bei.

Identität und Invalidierung

Jede Quelle stellt Folgendes bereit:

  • Eine stabile Quell-ID für die ausgewählte Laufzeit.
  • Einen Fingerabdruck, der sich bei Änderungen am sichtbaren Bestand ändert.
  • Physische Überwachungspfade für Hot Reload und Cache-Prüfungen.
  • Herkunftsinformationen und Metadaten für jeden Eintrag.

Blockstudio berücksichtigt Quell-IDs und Fingerabdrücke bei den Identitäten der Laufzeit-, Seitenmanifest-, Site-Editor-Template-, Canvas- und Tailwind-Caches.

Verwende blockstudio/cache/context, wenn dieselbe Quellauswahl in mehreren Laufzeitvarianten gerendert werden kann:

PHP
add_filter(
    'blockstudio/cache/context',
    fn ($context, string $scope) => [
        'preview' => 'feature-card',
        'site' => get_current_blog_id(),
    ],
    10,
    2
);

Der Kontextwert muss serialisierbar und für gleichwertige Anfragen stabil sein. Tailwind speichert den letzten gültigen CSS in einem kontextspezifischen Namespace, damit eine Vorschau nicht den Ersatzwert CSS einer anderen Vorschau erhält.

Generierte Assets

Markiere übernommene oder schreibgeschützte Einträge in Herkunftsinformationen oder Metadaten mit inherited: true, readOnly: true oder writable: false. Blockstudio schreibt kompilierte Assets dann in einen kontextspezifischen Bereich generated unterhalb des konfigurierten Cache-Stammverzeichnisses Blockstudio statt neben der übergeordneten Quelle. Generierte Assets, Tailwind-Ausgabe, Render-Dokumente und statische Prerenders verwenden dadurch dieselbe beschreibbare Host-Grenze.

Zwei Filter unterstützen benutzerdefinierte Laufzeit-Routen:

PHP
add_filter(
    'blockstudio/generated_output/path',
    function (string $path, string $source, string $scope, array $metadata) {
        return $path;
    },
    10,
    4
);

add_filter(
    'blockstudio/files/url',
    function (string $url, string $path, string $scope) {
        return $url;
    },
    10,
    3
);

Verwende den Filter URL, wenn ausgewählte Dateien außerhalb von wp-content liegen oder über einen Laufzeit-Endpunkt bereitgestellt werden.