Ugrás a tartalomhoz

Blokkregiszter közzététele itt: GitHub

Miután elkészített néhány jó blokkot, a következő projektben is használni szeretné őket. A mappák kézi másolása a témák között addig működik, amíg a másolatok el nem térnek, és senki sem emlékszik, melyik témában van a javított változat. Minden blokk saját builddel rendelkező csomagba foglalása túl sok formaság egy olyan mappáért, amely egy block.json fájlt és egy sablont tartalmaz.

A blokkregiszter a kettő között helyezkedik el. Ez egy registry.json fájl és blokkmappák gyűjteménye, amelyet egyszerű HTTP protokollon szolgálnak ki. A felhasználók egy CLI parancsot futtatnak, a blokk forrása bekerül a témájukba, és onnantól ők kezelik ezt a másolatot. Egy GitHub-tároló elegendő a regiszter tárolására, mivel az GitHub minden nyilvános tároló fájljait elérhetővé teszi nyers URL-címen.

Ez az útmutató létrehoz egy acme nevű regisztert négy blokkal, közzéteszi a acme/acme-blocks tárolóból, telepíti belőle a blokkokat egy témába, majd egy git címkével rögzít egy kiadást.

Az npm webhelyen található blockstudio csomag verziója 0.0.1. Ez a kiadás helyőrző: egyetlen parancsa, az add, kiírja ezt: Adding block: <name>, majd bármi letöltése nélkül kilép. Az útmutatóban szereplő parancsok és kimenetek a Blockstudio tároló CLI regiszteréből származnak (packages/registry), amely az az CLI, amelyet a Regiszter dokumentációja ismertet.

Hogyan illeszkednek egymáshoz az elemek

Két fájlt kell ismernie:

  • Az registry.json fájlt a blokk szerzője teszi közzé. Felsorolja a blokkokat, az egyes blokkok fájljait és a letöltésükhöz használt baseUrl címet.
  • Az blocks.json fájl a felhasználó témájában vagy bővítményében található. Megadja a használandó regisztereket és azt a könyvtárat, ahová a blokkok települnek.

Blokk telepítésekor az CLI lekéri az blocks.json fájlban szereplő összes regisztert, megkeresi a blokkot, feloldja a függőségeit, letölti a felsorolt fájlokat innen: {baseUrl}/{block}/{file}, majd ide írja őket: {directory}/{block}/{file}. Semmit sem alakít át, így a lemezen lévő fájlok pontosan megegyeznek a tárolóban lévőkkel.

1. lépés: A tároló felépítése

Hozzon létre egy tárolót, amelynek gyökerében egy registry.json fájl található, az blocks/ mappában pedig minden blokknak saját mappája van:

Kód
acme-blocks/
  registry.json
  blocks/
    hero/
      block.json
      index.php
    card/
      block.json
      index.php
      style.scss
    tabs/
      block.json
      index.php
      style.scss
    tab-item/
      block.json
      index.php

A mappa neve a blokk regiszterbeli neve lesz, és a felhasználó témájában is ez lesz a mappanév. Egyezzen meg pontosan a block.json blokknevének második felével (az acme/hero helye: hero/), így könnyű lesz felismerni a telepített mappát.

2. lépés: A blokkok megírása

Minden mappa egy hagyományos Blockstudio blokkot tartalmaz. A hero blokk egy mezővel rendelkezik:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/hero",
  "title": "Hero",
  "category": "design",
  "blockstudio": {
    "attributes": [
      {
        "id": "heading",
        "type": "text",
        "label": "Heading",
        "default": "Build faster"
      }
    ]
  }
}
PHP
<section useBlockProps class="acme-hero">
  <h1><?php echo esc_html( $a['heading'] ); ?></h1>
</section>

Az card ugyanazt a mintát követi, és hozzáad egy style.scss elemet. Az tabs rendereli az <InnerBlocks allowedBlocks='["acme/tab-item"]' /> elemet, az tab-item pedig deklarálja ezt: "parent": ["acme/tabs"], ezért az tabs nem használható az tab-item nélkül. A regiszter a következő lépésben fejezi ki ezt a kapcsolatot.

Ezek a blokkok nem függnek a regisztertől. Az CLI mappákat másol, így a @wordpress/create-block használatával készült vagy egyszerű PHP segítségével regisztrált blokk ugyanígy közzétehető.

3. lépés: Az registry.json megírása

Az registry.json felsorolja az összes blokkot és minden fájlt, amelyet az CLI-nek le kell töltenie:

JSON
{
  "$schema": "https://blockstudio.dev/schema/registry.json",
  "name": "acme",
  "description": "Acme block library.",
  "baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/main/blocks",
  "blocks": [
    {
      "name": "hero",
      "title": "Hero",
      "description": "Full-width hero section with a heading.",
      "category": "layout",
      "type": "blockstudio",
      "files": ["block.json", "index.php"]
    },
    {
      "name": "card",
      "title": "Card",
      "description": "Content card with a title.",
      "category": "components",
      "type": "blockstudio",
      "files": ["block.json", "index.php", "style.scss"]
    },
    {
      "name": "tabs",
      "title": "Tabs",
      "description": "Tabbed content with keyboard navigation.",
      "category": "layout",
      "type": "blockstudio",
      "dependencies": ["tab-item"],
      "files": ["block.json", "index.php", "style.scss"]
    },
    {
      "name": "tab-item",
      "title": "Tab Item",
      "description": "Single tab panel used inside Tabs.",
      "category": "layout",
      "type": "blockstudio",
      "files": ["block.json", "index.php"]
    }
  ]
}

Néhány szabály határozza meg, hogy ez a fájl működik-e:

  • A files explicit lista. A CLI pontosan ezeket az útvonalakat tölti le, és semmi mást. Nincs globbing, ezért egy új eszköz csak akkor kerül bele, ha itt hozzáadod. Az útvonalak alkönyvtárakat is tartalmazhatnak, amelyeket a rendszer telepítéskor létrehoz.
  • A baseUrl értékének abszolút URL-nek kell lennie. A CLI URL-ként ellenőrzi, és elutasítja a relatív értékeket. A blokkfájlok mindig a baseUrl helyről töltődnek le, soha nem onnan, ahová a registry.json fájlt betöltötték.
  • A dependencies ugyanabban a nyilvántartásban nevezik meg a blokkokat. A tabs hozzáadásakor először a tab-item települ. A hiányzó és körkörös függőségek hibaüzenettel megszakítják a telepítést.
  • A name kötelező, de nem jelenik meg. A parancsok és a kimenet azt a kulcsot használják, amelyet a fogyasztó a nyilvántartásnak a blocks.json fájlban megad; ennek nem kell egyeznie.
  • A type tájékoztató jellegű. Elfogadja a blockstudio, create-block vagy wordpress értéket, és nem változtat azon, hogy mit csinál a CLI.

A CLI minden lekéréskor ellenőrzi a teljes fájlt, és megadja az összes hibás mezőt, így az elírás még bármely fájl letöltése előtt kiderül. A $schema sor ugyanezeket az ellenőrzéseket biztosítja a szerkesztőben.

4. lépés: Közzététel nyers URL-eken keresztül

Véglegesítsd és küldd fel a tárházat a GitHub helyre. Egy nyilvános tárház minden fájlja ezután itt érhető el:

Kód
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>

A <ref> lehet ág, címke vagy commit SHA. Ennél a nyilvántartásnál két fontos URL van:

  • A nyilvántartás URL címe, amelyet a fogyasztók konfigurálnak: https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
  • A baseUrl helye a registry.json fájlban: https://raw.githubusercontent.com/acme/acme-blocks/main/blocks

Ezzel a baseUrl értékkel a hero index.php-je a következő helyről töltődik le: https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php. A nyers tárhely a fájl tartalmát adja vissza a GitHub HTML oldal helyett, erre van szüksége a CLI eszköznek. A hibás tulajdonos, tárház vagy ref már az első parancsnál 404 hibát okoz:

Kód
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json

5. lépés: Blokkok telepítése egy témába

A fogyasztó témájának gyökérkönyvtárában hozd létre ezt: blocks.json:

Shell
npx blockstudio init --yes
Kód
Created .../acme-theme/blocks.json

A init --yes egy üres registries objektumot ír ki. Add hozzá a nyilvántartást a kívánt parancsnévtér alatt:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
  }
}

Ha terminálban, --yes nélkül futtatod a init parancsot, ugyanezekre a kérdésekre interaktívan válaszolhatsz (blokk könyvtára, nyilvántartásnevek és URL-ek).

Ellenőrizd, hogy a nyilvántartás feloldható-e:

Shell
npx blockstudio list
Kód
acme (4 blocks)

  Name      Title     Category      Type
  hero      Hero      layout        blockstudio
  card      Card      components    blockstudio
  tabs      Tabs      layout        blockstudio
  tab-item  Tab Item  layout        blockstudio

A search kis- és nagybetűtől független részszövegre keres a nevekben, címekben és leírásokban:

Shell
npx blockstudio search tab
Kód
Results for "tab"

  acme/tabs - Tabs
    Tabbed content with keyboard navigation.
  acme/tab-item - Tab Item
    Single tab panel used inside Tabs.

Telepítés előnézetéhez használd a --dry-run parancsot. A függőség jelenik meg először, mert azt telepíti először:

Shell
npx blockstudio add acme/tabs --dry-run
Kód
Would install:
  tab-item (2 files)
  tabs (3 files)

Ezután végezd el a telepítést:

Shell
npx blockstudio add acme/tabs
Kód
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)

Most mindkét mappa a téma blockstudio könyvtárában található, pontosan úgy, ahogy a tárházban:

Kód
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss

Ha a blokk csak egy konfigurált nyilvántartásban szerepel, elhagyhatod a névteret, és egyszerre több blokkot is megadhatsz:

Shell
npx blockstudio add hero card
Kód
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)

A Blockstudio ugyanúgy megtalálja az új mappákat, mint a téma bármely más blokkját.

Telepített blokkok frissítése

A telepített fájlok másolatok. Semmi nem követi, melyik verziót telepítetted, és a CLI soha nem frissíti önállóan a blokkokat. Újabb verzió letöltéséhez add hozzá újra a blokkot. Terminál nélkül vagy CI-ben a meglévő mappa leállítja a parancsot:

Shell
npx blockstudio add tab-item
Kód
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.

Terminálban a CLI ehelyett rákérdez a felülírásra. A --dry-run felsorolja a lecserélendő mappákat, a --yes pedig lecseréli őket:

Shell
npx blockstudio add acme/tab-item --dry-run
Kód
Would overwrite tab-item
Would install:
  tab-item (2 files)

Felülíráskor a felsorolt fájlok a nyilvántartásban lévő verzióra cserélődnek, ezért előbb véglegesítsd a helyi módosításokat, majd a git diff paranccsal nézd át az eredményt.

Eltávolításhoz töröld a mappát a neve alapján:

Shell
npx blockstudio remove tabs --yes
Kód
Removed tabs

A remove a mappa nevét kéri, nem a namespace/block értékét. A függőségeket nem távolítja el, így a tab-item a tabs eltávolítása után is telepítve marad.

Verziókezelés git-hivatkozásokkal

A CLI nem tartalmaz verziómezőt vagy verziójelzőt. A letöltött tartalmat teljes egészében az URL-ek határozzák meg, a GitHub esetében pedig a URL-ben megadott ref jelöli a verziót. Ha a fogyasztó a main értékre mutat, azt kapja, amit a main a telepítés időpontjában tartalmaz.

Egy változatlan kiadás közzétételéhez a címkéhez tartozó registry.json-nak is a címkéről kell letöltenie. Címkézés előtt állítsd a baseUrl értékét a címkére:

JSON
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"

Ezután véglegesítsd, címkézd és küldd fel:

Shell
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0

Utána állítsd vissza a baseUrl értékét erre: main, majd véglegesítsd a módosítást, hogy az ág továbbra is az aktuális fájlokat szolgálja ki. Ha kihagyod az első lépést, a címkéhez rögzített fogyasztó a címkézett blokkok listáját kapja, de a fájlokat a main refből tölti le.

A fogyasztók úgy rögzítenek verziót, hogy a címkét használják a nyilvántartásuk URL értékeként:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
  }
}

Ebben a példában a v1.0.0 címkézése a tabs és tab-item létrehozása előtt történt, ezért a rögzített nyilvántartás csak az eredeti két blokkot kínálja:

Shell
npx blockstudio list
Kód
acme (2 blocks)

  Name  Title  Category      Type
  hero  Hero   layout        blockstudio
  card  Card   components    blockstudio
Shell
npx blockstudio add acme/tabs
Kód
Block "tabs" not found in registry "acme".

A nyilvántartás URL értéke commit SHA is lehet, de egy commit nem tartalmazhatja a saját SHA-ját a baseUrl fájlban. A SHA szerinti rögzítés ezért a blokkok listáját rögzíti, miközben a fájlok továbbra is attól a reftől érkeznek, amelyet az adott commit baseUrl értéke megad. Kiadásokhoz ezért inkább címkéket használj.

Amit érdemes észben tartani

  • Először minden nyilvántartás lekérése történik. A add betölti a blocks.json összes nyilvántartását, mielőtt bármit feloldana, ezért egy elérhetetlen nyilvántartás miatt a parancs akkor is hibával leáll, ha a acme/hero-ről van szó. Távolítsd el a már nem használt nyilvántartásokat.
  • Kétértelmű nevekhez névtér szükséges. Ha két nyilvántartásban is szerepel a hero, a terminálos munkamenet megkérdezi, melyiket használja; a --yes a blocks.json sorrendben az elsőt választja, a nem interaktív futtatás pedig Block "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero hibával leáll.
  • A privát tárházakhoz fejlécek szükségesek. A nyilvántartás bejegyzéséhez használd az objektumformátumot a url és headers mezővel. A fejlécértékek környezeti változókból beolvasott ${VAR} helyőrzőket fogadnak el, a CLI pedig a nyilvántartás lekérésekor és minden fájl letöltésekor is elküldi a fejléceket. A token beállításához lásd a GitHub tárhely útmutatóját.

Következő lépések