Σύνθεση προτύπων με ετικέτες block
Όταν ένα έργο έχει μερικά block, τα πρότυπα αρχίζουν να χρειάζονται το ένα το άλλο. Ένα block χαρακτηριστικών θέλει να εμφανίσει τρεις κάρτες. Μια σελίδα προορισμού χρειάζεται μια ενότητα με ένα κουμπί μέσα της. Μπορείτε να καλέσετε το bs_render_block() για καθένα, αλλά ένα πρότυπο γεμάτο κλήσεις PHP με ένθετους πίνακες είναι δυσανάγνωστο και ακόμη δυσκολότερο να εμφωλευτεί.
Οι ετικέτες block σάς επιτρέπουν να γράφετε ένα block στο σημείο όπου ανήκει η έξοδός του, ως ετικέτα HTML:
<bs:acme-card title="Fast" text="Rendered on the server." />
Η ίδια ετικέτα σημαίνει δύο διαφορετικά πράγματα, ανάλογα με το πού γράφεται. Σε πρότυπο block ή στο περιεχόμενο μιας ανάρτησης, αντικαθίσταται από την αποδοσμένη HTML του block. Σε πηγή σελίδας, μοτίβου ή Site Template, μετατρέπεται σε πραγματικό block WordPress που εμφανίζεται στο πρόγραμμα επεξεργασίας. Αυτός ο οδηγός δημιουργεί μερικά block, τα συνθέτει και με τους δύο τρόπους, προσθέτει πρόθεμα έργου για συντομότερα ονόματα και έπειτα δείχνει πώς να μετατρέψετε αυτές τις συντομογραφίες ξανά στη φορητή γραφή.
Τα block
Αρκούν τρία μικρά block. Μια κάρτα με δύο πεδία:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/card",
"title": "Card",
"blockstudio": {
"attributes": [
{ "id": "title", "type": "text", "label": "Title", "default": "" },
{ "id": "text", "type": "textarea", "label": "Text", "default": "" }
]
}
}
<article useBlockProps class="acme-card">
<h3><?php echo esc_html( $a['title'] ); ?></h3>
<p><?php echo esc_html( $a['text'] ); ?></p>
</article>
Μια ενότητα που περιβάλλει ό,τι τοποθετείται μέσα της, με πεδίο heading δηλωμένο με τον ίδιο τρόπο όπως της κάρτας:
<section useBlockProps class="acme-section">
<h2><?php echo esc_html( $a['heading'] ); ?></h2>
<InnerBlocks />
</section>
Και ένα κουμπί σε δεύτερο χώρο ονομάτων, acme-ui/button, με πεδία label και href:
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>
Ετικέτες μέσα σε πρότυπο block
Τα πρότυπα block αποδίδουν αυτόματα τις ετικέτες. Δεν απαιτείται ρύθμιση. Ένα block χαρακτηριστικών μπορεί να εμφανίσει απευθείας δύο κάρτες και ένα διαχωριστικό core:
<div useBlockProps class="acme-features">
<bs:acme-card title="Fast" text="Rendered on the server." />
<block name="acme/card" title="Typed" text="Fields come from block.json." />
<block name="core/separator" />
</div>
Η απόδοση του acme/features παράγει:
<!--blockstudio/acme/features--><div class="acme-features wp-block-acme-features">
<!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
<h3>Fast</h3>
<p>Rendered on the server.</p>
</article>
<!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
<h3>Typed</h3>
<p>Fields come from block.json.</p>
</article>
<hr class="wp-block-separator has-alpha-channel-opacity">
</div>
Κάθε μπλοκ Blockstudio στην έξοδο προηγείται από ένα σχόλιο <!--blockstudio/namespace/slug-->. Το buffer σελίδας το αφαιρεί από την απόκριση· για έξοδο που παρακάμπτει το buffer, χρησιμοποιήστε bs_strip_render_markers().
Οι δύο συντάξεις είναι ισοδύναμες. Το <bs:acme-card> κωδικοποιεί το όνομα του μπλοκ στην ετικέτα, ενώ το <block name="acme/card"> το περνά ως χαρακτηριστικό. Κάθε άλλο χαρακτηριστικό γίνεται τιμή πεδίου, επομένως το title φτάνει στο πρότυπο κάρτας ως $a['title']. Λειτουργούν και τα βασικά μπλοκ, τα οποία αποδίδονται μέσω του WordPress με τους ενσωματωμένους αποδοτές μπλοκ.
Ζεύγη ετικετών και εσωτερικό περιεχόμενο
Μια ετικέτα σε ζεύγος περνά τα παιδιά της στο block. Για ένα block Blockstudio, αυτά συμπληρώνουν το <InnerBlocks />, ενώ οι ένθετες ετικέτες αποδίδονται πρώτα:
<bs:acme-section heading="Why Acme">
<bs:acme-card title="Fast" text="Rendered on the server." />
<bs:acme-ui-button label="Get started" href="/start" />
</bs:acme-section>
<!--blockstudio/acme/section--><section class="acme-section wp-block-acme-section">
<h2>Why Acme</h2>
<div>
<!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
<h3>Fast</h3>
<p>Rendered on the server.</p>
</article>
<!--blockstudio/acme-ui/button--><a class="acme-button wp-block-acme-ui-button" href="/start">Get started</a>
</div>
</section>
Πώς το όνομα μιας ετικέτας γίνεται όνομα block
Το όνομα μιας ετικέτας <bs:> δεν έχει κάθετο, επομένως το Blockstudio αναζητά ένα. Αντικαθιστά κάθε παύλα με κάθετο, με τη σειρά από αριστερά προς τα δεξιά, και χρησιμοποιεί τον πρώτο υποψήφιο που είναι καταχωρισμένος. Το <bs:acme-card> επιλύεται ως acme/card με την πρώτη προσπάθεια. Το <bs:acme-ui-button> δοκιμάζει το acme/ui-button, δεν βρίσκει τίποτα και έπειτα επιλύεται ως acme-ui/button. Οι χώροι ονομάτων που περιέχουν παύλες λειτουργούν επομένως χωρίς ρύθμιση, αρκεί να μην υπάρχουν και οι δύο υποψήφιοι.
Συντομότερα ονόματα με προθέματα
Το <bs:acme-ui-button> είναι ακριβές αλλά μακρύ. Ένα πρόθεμα έργου αντιστοιχίζει ένα σύντομο πρόθεμα ετικέτας σε έναν ή περισσότερους χώρους ονομάτων. Ρυθμίστε το στο blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"blockTags": {
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
}
}
}
Ή καταχωρίστε την ίδια αντιστοίχιση από το PHP:
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
$prefixes['acme'] = array( 'acme' );
$prefixes['ui'] = array( 'acme-ui' );
return $prefixes;
} );
Τώρα το <acme-card> επιλύεται ως acme/card και το <ui-button> ως acme-ui/button. Όταν ένα πρόθεμα περιλαμβάνει πολλούς χώρους ονομάτων, δοκιμάζονται με τη σειρά και υπερισχύει το πρώτο καταχωρισμένο block. Έτσι, ένα block του έργου μπορεί να υπερισχύσει ενός block βιβλιοθήκης με το ίδιο slug.
Τα προθέματα συνδυάζονται επίσης. Το <acme-ui-button> δοκιμάζει πρώτα το acme/ui-button. Αυτό το block δεν υπάρχει και το υπόλοιπο της ετικέτας, ui-button, είναι από μόνο του καταχωρισμένη ετικέτα προθέματος, οπότε η επίλυση καταλήγει στο acme-ui/button. Μια άμεση αντιστοίχιση υπερισχύει πάντα της ένθετης.
<bs:acme-section heading="Why Acme">
<acme-card title="Fast" text="Rendered on the server." />
<acme-ui-button label="Get started" href="/start" />
</bs:acme-section>
Αυτό αποδίδει ακριβώς το ίδιο HTML με την κανονική έκδοση παραπάνω.
Ισχύουν μερικοί κανόνες για τα προθέματα:
- Ένα πρόθεμα αποτελείται από πεζά γράμματα και αριθμούς, αρχίζει με γράμμα και δεν περιέχει παύλες.
- Μια ετικέτα με πρόθεμα που δεν επιλύεται σε καταχωρισμένο block παραμένει αμετάβλητη στην έξοδο, επομένως το
<acme-missing title="x" />παραμένει όπως γράφτηκε. - Τα ακριβή ψευδώνυμα από το φίλτρο
blockstudio/block_tags/tag_aliasesέχουν προτεραιότητα έναντι των προθεμάτων. Ένα ψευδώνυμο αντιστοιχίζει μία ετικέτα με παύλες σε ένα block. Για παράδειγμα, το$aliases['acme-cta'] = 'acme-ui/button';κάνει το<acme-cta>να αποδίδει το κουμπί.
Οι ετικέτες προθέματος και ψευδωνύμου αποδίδονται στα πρότυπα block μαζί με τις ετικέτες <bs:> και <block> από την έκδοση 7.5 του Blockstudio.
Χαρακτηριστικά
Τα χαρακτηριστικά που ταιριάζουν με ένα ID πεδίου γίνονται τιμές πεδίων. Δύο προθέματα κάνουν κάτι άλλο:
- Τα χαρακτηριστικά
data-*αντιγράφονται στο ριζικό στοιχείο του αποδοσμένου block. - Τα χαρακτηριστικά
html-*αντιγράφονται στο ριζικό στοιχείο με αφαιρεμένο το πρόθεμα, επομένως τοhtml-id="intro"γίνεταιid="intro".
<bs:acme-card title="Hi" text="There" data-track="card" html-id="intro" html-class="featured" />
<article data-track="card" id="intro" class="featured">
<h3>Hi</h3>
<p>There</p>
</article>
Το html-class ορίζει το χαρακτηριστικό, δεν προσθέτει τιμές σε αυτό: οι κλάσεις acme-card wp-block-acme-card του ίδιου του block αφαιρούνται. Αν ο καλών θέλει να προσθέσει κλάσεις σε ένα block, δηλώστε ένα πεδίο γι’ αυτές και συγχωνεύστε το στο πρότυπο.
Κάθε άλλο χαρακτηριστικό που δεν είναι δηλωμένο πεδίο απορρίπτεται. Ένα απλό class="wide" στο <bs:acme-card> αποδίδει την κάρτα χωρίς αυτό. Η έκδοση 7.7 του Blockstudio αναφέρει τέτοια χαρακτηριστικά με ειδοποίηση _doing_it_wrong() όταν είναι ενεργό το WP_DEBUG.
Οι ίδιες ετικέτες σε πηγές σελίδων
Σε σελίδες βασισμένες σε αρχεία, μοτίβα και Site Templates, οι ετικέτες δεν αποδίδονται. Μετατρέπονται σε block κατά την ανάλυση της πηγής, ώστε να εμφανίζονται στο πρόγραμμα επεξεργασίας. Αυτή η πηγή σελίδας:
<bs:acme-section heading="Why Acme">
<p>Everything below is a real block.</p>
<acme-card title="Fast" text="Rendered on the server." />
<acme-ui-button label="Get started" href="/start" />
</bs:acme-section>
αναλύεται στην εξής σήμανση block (έχουν προστεθεί αλλαγές γραμμής για ευκολότερη ανάγνωση):
<!-- wp:acme/section {"blockstudio":{"attributes":{"heading":"Why Acme"}}} -->
<!-- wp:paragraph --><p>Everything below is a real block.</p><!-- /wp:paragraph -->
<!-- wp:acme/card {"blockstudio":{"attributes":{"title":"Fast","text":"Rendered on the server."}}} /-->
<!-- wp:acme-ui/button {"blockstudio":{"attributes":{"label":"Get started","href":"/start"}}} /-->
<!-- /wp:acme/section -->
Οι τιμές πεδίων τοποθετούνται κάτω από το blockstudio.attributes, όπου τις αποθηκεύουν τα block Blockstudio, και η παράγραφος μαζί με τα δύο εσωτερικά block γίνονται εσωτερικά block της ενότητας. Τα προθέματα και τα ψευδώνυμα επιλύονται εδώ ακριβώς όπως στα πρότυπα.
Ετικέτες στο περιεχόμενο αναρτήσεων
Το περιεχόμενο που γράφεται στο πρόγραμμα επεξεργασίας ή αποθηκεύεται στα widget δεν σαρώνεται από προεπιλογή. Ενεργοποιήστε την απόδοση σε επίπεδο σελίδας στο blockstudio.json:
{
"blockTags": {
"enabled": true
}
}
Έπειτα, οι ετικέτες στα the_content και widget_text αποδίδονται με προτεραιότητα 5. Η ίδια ρύθμιση καταχωρίζει ένα φίλτρο για την απόδοση ετικετών σε οποιαδήποτε συμβολοσειρά:
$html = apply_filters( 'blockstudio/block_tags/render', $content );
Περιορίστε τις ετικέτες που μπορούν να αποδοθούν με μοτίβα allow και deny, τα οποία δέχονται χαρακτήρες μπαλαντέρ fnmatch() και εφαρμόζονται σε κάθε σύνταξη και στις δύο λειτουργίες απόδοσης:
{
"blockTags": {
"enabled": true,
"deny": ["acme-ui/*"]
}
}
Με αυτόν τον κανόνα, τα <acme-ui-button> και <bs:acme-ui-button> παραμένουν στην έξοδο χωρίς απόδοση. Το deny υπερισχύει του allow. Τα φίλτρα blockstudio/block_tags/allow και blockstudio/block_tags/deny αλλάζουν τις ίδιες λίστες από το PHP.
Η ανάλυση ελέγχει την κανονική γραφή
Η επέκταση PHPStan επικυρώνει ετικέτες block σε πρότυπα PHP, Twig και Blade. Ένα ανορθόγραφο πεδίο ή όνομα block αναφέρεται μαζί με το block στο οποίο επιλύθηκε:
3 Block tag "acme/card" has unknown attribute "txt" in index.php
🪪 blockstudio.blockTag.attribute
4 Block tag references unknown block "acme/cards" in index.php
🪪 blockstudio.blockTag.unknown
Στην έκδοση 7.6 αυτό καλύπτει τις ετικέτες <bs:> και <block>. Μια ετικέτα προθέματος όπως το <acme-card txt="..."> δεν ελέγχεται. Η έκδοση 7.7 του Blockstudio επεκτείνει τον κανόνα στις ετικέτες προθέματος, στις πηγές σελίδων και στα αντιστοιχισμένα στοιχεία HTML, ενώ η υπόδειξή της παραθέτει τα καθολικά χαρακτηριστικά που μπορεί να προωθήσει μια ετικέτα.
Μετατροπή συντομογραφιών στην κανονική γραφή
Οι ετικέτες προθέματος και ψευδωνύμου εξυπηρετούν το έργο. Επιλύονται μόνο εκεί όπου φορτώνονται τα φίλτρα και οι ρυθμίσεις του έργου, επομένως μια αντιγραφή προτύπου σε άλλο έργο, βιβλιοθήκη block ή περιβάλλον κώδικα ενός coding agent χάνει το νόημά της. Το <bs:namespace-slug> καταγράφει το πραγματικό όνομα block και επιλύεται παντού, γι’ αυτό τα παραδείγματα, τα διαγνωστικά και η παραγόμενη έξοδος του ίδιου του Blockstudio χρησιμοποιούν αυτή τη γραφή.
Μια αυτόνομη εντολή ξαναγράφει τις συντομογραφίες σε αυτή τη γραφή. Ας πάρουμε ένα έργο του οποίου οι πηγές εξακολουθούν να χρησιμοποιούν τις σύντομες μορφές, μαζί με ένα ψευδώνυμο, μια ετικέτα για block που δεν υπάρχει πια και ένα παράδειγμα μέσα σε δείγμα κώδικα:
<div useBlockProps class="acme-features">
<acme-card title="Fast" text="Rendered on the server." />
<acme-ui-button label="Get started" href="/start" />
</div>
<acme-section heading="Why Acme">
<acme-cta label="Talk to us" href="/contact" />
<acme-quote text="Missing block" />
</acme-section>
<pre><code><acme-card /> <acme-card title="Example" /></code></pre>
Η εντολή δεν φορτώνει το WordPress, επομένως δέχεται τις ρυθμίσεις του έργου ως αρχεία JSON που διατηρούνται έξω από το δέντρο που σαρώνεται:
{ "acme": ["acme"], "ui": ["acme-ui"] }
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
{ "acme-cta": "acme-ui/button" }
Ξεκινήστε με δοκιμαστική εκτέλεση, που είναι και η προεπιλογή:
php vendor/blockstudio/blockstudio/bin/migrate-block-tags.php \
--root="$PWD" \
--prefix-map=/tmp/acme-tags/prefixes.json \
--known-blocks=/tmp/acme-tags/blocks.json \
--aliases=/tmp/acme-tags/aliases.json \
--report=/tmp/acme-tags/report.json \
--dry-run
Report: /tmp/acme-tags/report.json
Dry run: 2 files, 2 changed, 5 replacements, 1 unknown, 0 ambiguous, 1 manual.
Η αναφορά παραθέτει κάθε αντιστοίχιση που θα εφαρμοστεί και κάθε περίπτωση για την οποία δεν θα γίνει εικασία:
{
"mappings": [
{ "legacy": "acme-card", "canonical": "bs:acme-card", "block": "acme/card", "occurrences": 1 },
{ "legacy": "acme-cta", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 },
{ "legacy": "acme-section", "canonical": "bs:acme-section", "block": "acme/section", "occurrences": 2 },
{ "legacy": "acme-ui-button", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 }
],
"unknown": [
{ "path": "pages/home/index.php", "line": 3, "column": 4, "tag": "acme-quote", "reason": "no-known-block" }
],
"manual": [
{ "path": "pages/home/index.php", "line": 5, "column": 33, "tag": "acme-card", "reason": "code-sample" }
]
}
Η αναφορά εμφανίζεται περικομμένη εδώ. Καταγράφει επίσης τις ρυθμίσεις και τα hash κάθε αρχείου πριν και μετά. Οι ετικέτες ανοίγματος και κλεισίματος της ενότητας μετρούν ως δύο εμφανίσεις. Το acme-quote ταιριάζει με το πρόθεμα acme, αλλά δεν ονομάζει γνωστό block, επομένως είναι άγνωστο. Το acme-card μέσα στο <pre><code> είναι παράδειγμα, όχι σήμανση, οπότε αναφέρεται για μη αυτόματο έλεγχο και δεν ξαναγράφεται ποτέ. Το ίδιο ισχύει για τα σχόλια HTML και τον ενσωματωμένο κώδικα.
Η εφαρμογή των αλλαγών απορρίπτεται όσο υπάρχουν άγνωστες, αμφίσημες ή δυναμικές ετικέτες:
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.
Η εντολή τερματίζει με 2. Διορθώστε την άγνωστη ετικέτα, εδώ αφαιρώντας την, και εκτελέστε με --apply αντί για --dry-run:
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.
Αλλάζουν μόνο τα ονόματα των ετικετών. Τα χαρακτηριστικά διατηρούνται byte προς byte:
<bs:acme-section heading="Why Acme">
<bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>
Αν εκτελέσετε ξανά τη δοκιμαστική εκτέλεση στο αποτέλεσμα, αναφέρει το 0 changed, 0 replacements. Τα προθέματα μπορούν να παραμείνουν καταχωρισμένα στη συνέχεια, ώστε να μη διακοπεί τίποτα όσο άλλοι κλάδοι εξακολουθούν να χρησιμοποιούν τη σύντομη μορφή.
Επόμενα βήματα
- Απόδοση: πλήρης σύνταξη ετικετών, προσαρμοσμένοι αποδότες και ο αναλυτής.
- Ρυθμίσεις: κάθε επιλογή του
blockTags. - Δημιουργία σελίδων βασισμένων σε αρχεία: πηγές σελίδων όπου οι ετικέτες γίνονται επεξεργάσιμα block.
- Μεταφορά ετικετών block: όλες οι επιλογές της εντολής μεταφοράς.
- Έλεγχος προτύπων με PHPStan: εκτέλεση της ανάλυσης που επικυρώνει τις ετικέτες.