Απόδοση χαρακτηριστικών
Μέσα στα αρχεία προτύπων, μπορείτε να αποκτήσετε πρόσβαση σε όλα τα χαρακτηριστικά χρησιμοποιώντας τις μεταβλητές $attributes ή $a και το αντίστοιχο αναγνωριστικό του πεδίου.
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
Εγγραφή χαρακτηριστικών μέσω προγραμματισμού
Ο επεξεργαστής τοποθετεί τις αποθηκευμένες τιμές κάτω από το blockstudio.attributes. Οτιδήποτε εγγράφει ένα block εκτός του επεξεργαστή, όπως το REST API, το WP-CLI, μια μετεγκατάσταση περιεχομένου ή ένας διακομιστής MCP, ανιχνεύει το block από τα χαρακτηριστικά που καταχωρίζει το Blockstudio στο WP_Block_Type και τα εγγράφει στο ανώτερο επίπεδο. Και οι δύο μορφές αποδίδονται:
// Top level, as a programmatic writer produces it.
echo do_blocks( '<!-- wp:acme/hero {"visual_type":"media"} /-->' );
// Nested, as the editor saves it.
echo do_blocks( '<!-- wp:acme/hero {"blockstudio":{"attributes":{"visual_type":"media"}}} /-->' );
Αναγνωρίζονται μόνο τα αναγνωριστικά που δηλώνει το block στο ανώτερο επίπεδο, επομένως τα ίδια τα χαρακτηριστικά του WordPress, όπως τα anchor, className, lock, metadata και style, δεν υιοθετούνται ποτέ ως τιμές πεδίων. Αν το ίδιο αναγνωριστικό εμφανίζεται και στις δύο θέσεις, υπερισχύει η ένθετη τιμή.
Ανάγνωση χαρακτηριστικών μέσω προγραμματισμού
Ο κώδικας που εκτελείται εκτός του προτύπου, όπως τα δομημένα δεδομένα στο save_post, οι εξαγωγές, η ευρετηρίαση αναζήτησης ή ένα φίλτρο render_block, συχνά χρειάζεται τις τιμές ενός αποθηκευμένου μπλοκ όπως τις βλέπει το πρότυπο. Το bs_block_values() τις επιστρέφει χωρίς να αποδώσει το μπλοκ. Καλέστε το μετά την καταχώριση του μπλοκ (init ή αργότερα), με τον πλήρη πίνακα attrs από το parse_blocks():
foreach (parse_blocks($post->post_content) as $block) {
if ($block['blockName'] === null) {
continue;
}
$a = bs_block_values($block['blockName'], $block['attrs']);
if ($a === null) {
// Not a Blockstudio block, and no extension applies.
continue;
}
echo esc_html($a['title'] ?? '');
}
Το αποτέλεσμα είναι ο πίνακας $a του προτύπου, με κλειδί το αναγνωριστικό κάθε πεδίου:
- Εφαρμόζονται οι προεπιλεγμένες τιμές πεδίων, ενώ ένας επαναλήπτης με
minπεριλαμβάνει τις αρχικές γραμμές του. - Οι τιμές ανώτατου επιπέδου συγχωνεύονται με το
blockstudio.attributes, και υπερισχύει η ένθετη τιμή. Διαβάζονται μόνο τα δηλωμένα αναγνωριστικά από το ανώτατο επίπεδο, ενώ το WordPress απορρίπτει μια τιμή ανώτατου επιπέδου που δεν ταιριάζει με τον καταχωρισμένο τύπο του πεδίου, για παράδειγμα μια συμβολοσειρά επιλογής, όπως ακριβώς και κατά την απόδοση. - Περιλαμβάνονται τα πεδία των αντίστοιχων επεκτάσεων, μαζί με τις προεπιλεγμένες τιμές τους. Μια επέκταση ενός βασικού μπλοκ ή μπλοκ τρίτου μέρους διαβάζει μόνο το
blockstudio.attributes, όπως και κατά την απόδοση. - Εφαρμόζονται οι μορφές επιστροφής: έτσι, μια λίστα επιλογών με
returnFormatίσο μεlabelεπιστρέφει την ετικέτα, ενώ ένα πεδίο αρχείων επιστρέφει τα δεδομένα του συνημμένου. - Τα απενεργοποιημένα και κενά πεδία είναι
false, όπως και στο πρότυπο.
Το null σημαίνει ότι ούτε το μπλοκ ούτε κάποια επέκταση διαχειρίζεται από το Blockstudio. Ένα μπλοκ Blockstudio χωρίς πεδία επιστρέφει [].
Η συνάρτηση εκτελεί τον ίδιο μετασχηματισμό με την απόδοση, επομένως έχει τις ίδιες παρενέργειες: τα πεδία αρχείων αναζητούν τα συνημμένα, ένα πεδίο μπλοκ που δεν επιστρέφει το data αποδίδει το μπλοκ στο οποίο αναφέρεται και το φίλτρο blockstudio/blocks/attributes/render εκτελείται για κάθε τιμή. Δεν αποδίδει το πρότυπο του ίδιου του μπλοκ και δεν επιλύει τα innerBlocks· πρέπει να τα διασχίσετε εσείς. Ένα πεδίο κώδικα διατηρεί ένα αυτόματα δημιουργημένο αναγνωριστικό %selector%, το οποίο διαφέρει σε κάθε κλήση.
Η επίλυση χρησιμοποιεί το τρέχον περιβάλλον WordPress. Δεν δημιουργούνται μεταδεδομένα που αφορούν μόνο την απόδοση, όπως οι μετρητές μπλοκ και το innerBlocks· τα φίλτρα απόδοσης χαρακτηριστικών λαμβάνουν το όνομα του μπλοκ και όχι τα μεταδεδομένα ενός πλήρως αποδοσμένου μπλοκ.
Δεν υπάρχει επιλογή για ανάγνωση των αποθηκευμένων τιμών χωρίς τον μετασχηματισμό. Για αυτές, διαβάστε απευθείας τον πίνακα attrs ή χρησιμοποιήστε το bs_validate_block() για να τις ελέγξετε.
Κενές τιμές
Οι τιμές χαρακτηριστικών επιστρέφουν false αν το πεδίο είναι κενό ή δεν έχει επιλεγεί κάποια επιλογή.
PHP
<?php if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
Twig
{% if a.message %}
<h1>{{ a.message }}</h1>
{% endif %}
Σύνθετοι τύποι
Αρχεία
Από προεπιλογή (χωρίς returnFormat ή με "returnFormat": "object"), το πεδίο αρχείων επιστρέφει έναν πίνακα με τα δεδομένα του συνημμένου. Με το "multiple": true επιστρέφει μια λίστα τέτοιων πινάκων. Ένα αρχείο του οποίου το συνημμένο δεν υπάρχει πλέον παραλείπεται false.
| Κλειδί | Περιγραφή |
|---|---|
ID |
Το αναγνωριστικό του συνημμένου. |
title |
Ο τίτλος του συνημμένου. |
alt |
Το εναλλακτικό κείμενο. Αν είναι κενό, χρησιμοποιείται ο τίτλος του συνημμένου. |
caption |
Η λεζάντα. |
description |
Η περιγραφή. |
href |
Ο μόνιμος σύνδεσμος της σελίδας του συνημμένου. |
url |
Το URL του αρχείου. Με το αναπτυσσόμενο μενού μεγέθους ("size": true), το URL του επιλεγμένου μεγέθους. |
sizes |
Το URL και οι διαστάσεις κάθε καταχωρισμένου μεγέθους εικόνας· δείτε παρακάτω. |
PHP
<?php if ($a['image']) :
$image = $a['image'];
$sizes = $image['sizes'] ?? [];
?>
<img
src="<?php echo esc_url($sizes['large'] ?? $image['url']); ?>"
alt="<?php echo esc_attr($image['alt']); ?>"
<?php if (isset($sizes['large-width'], $sizes['large-height'])) : ?>
width="<?php echo esc_attr($sizes['large-width']); ?>"
height="<?php echo esc_attr($sizes['large-height']); ?>"
<?php endif; ?>
/>
<?php endif; ?>
Twig
{% if a.image %}
<img
src="{{ (a.image.sizes.large ?? a.image.url)|e('html_attr') }}"
alt="{{ a.image.alt|e('html_attr') }}"
{% if a.image.sizes['large-width'] is defined and a.image.sizes['large-height'] is defined %}
width="{{ a.image.sizes['large-width']|e('html_attr') }}"
height="{{ a.image.sizes['large-height']|e('html_attr') }}"
{% endif %}
/>
{% endif %}
Το sizes έχει μία καταχώριση για κάθε καταχωρισμένο μέγεθος εικόνας, καθώς και το full: το URL κάτω από το όνομα του μεγέθους και τις διαστάσεις κάτω από τα <size>-width και <size>-height. Αν για ένα συνημμένο δεν έχει δημιουργηθεί μέγεθος WordPress, χρησιμοποιείται το αρχικό αρχείο μαζί με τις διαστάσεις του. Αν το WordPress δεν μπορεί να επιλύσει μια εικόνα ή προεπισκόπηση, το κλειδί sizes απουσιάζει. Για παράδειγμα, ένα PDF χωρίς δημιουργημένη προεπισκόπηση δεν έχει sizes, αλλά ένα PDF με μεταδεδομένα προεπισκόπησης μπορεί να έχει μεγέθη εικόνας. Το sizes είναι null όταν δεν έχουν καταχωριστεί μεγέθη εικόνας ή όταν το φίλτρο files/sizes απενεργοποιεί τα μεγέθη. Αυτό το φίλτρο μπορεί επίσης να μικρύνει τον χάρτη, επομένως ελέγξτε ότι υπάρχει ένα μέγεθος πριν διαβάσετε τις διαστάσεις του, όπως στα παραπάνω παραδείγματα.
Το αντικείμενο δεν έχει κλειδιά width, height, mime, type ή size. Διαβάστε τις διαστάσεις από το sizes ή χρησιμοποιήστε το ID με συναρτήσεις όπως wp_get_attachment_image() και get_post_mime_type().
Μορφές επιστροφής
Το returnFormat αλλάζει την τιμή που επιστρέφει το πεδίο:
returnFormat |
Τιμή |
|---|---|
"object" (προεπιλογή) |
Ο πίνακας που περιγράφεται παραπάνω. |
"id" |
Το αναγνωριστικό του συνημμένου όπως αποθηκεύτηκε ή λίστα αναγνωριστικών με το "multiple": true. |
"url" |
Το URL ως συμβολοσειρά ή λίστα URL με το "multiple": true. Για τις εικόνες χρησιμοποιείται το μέγεθος που ορίζεται με το returnSize (προεπιλογή full), ενώ για τα άλλα αρχεία χρησιμοποιείται το URL του αρχείου. |
Σύνδεσμος
Το πεδίο συνδέσμου επιστρέφει ένα αντικείμενο με το URL και τα χαρακτηριστικά:
PHP
<?php if ($a['link']) : ?>
<a
href="<?php echo $a['link']['url']; ?>"
target="<?php echo $a['link']['target']; ?>"
>
<?php echo $a['link']['title']; ?>
</a>
<?php endif; ?>
Twig
{% if a.link %}
<a href="{{ a.link.url }}" target="{{ a.link.target }}">
{{ a.link.title }}
</a>
{% endif %}
Εικονίδιο
Το πεδίο εικονιδίου επιστρέφει ένα αντικείμενο με τα κλειδιά set, subSet και icon. Χρησιμοποιήστε τις βοηθητικές συναρτήσεις bs_render_icon() και bs_icon() για να εμφανίσετε το SVG:
PHP
<?php if ($a['icon']) : ?>
<div class="icon">
<?php bs_render_icon($a['icon']); ?>
</div>
<?php endif; ?>
Twig
{% if a.icon %}
<div class="icon">
{{ bs_icon(a.icon) }}
</div>
{% endif %}
Το bs_render_icon() εκτυπώνει απευθείας το SVG. Το bs_icon() το επιστρέφει ως συμβολοσειρά.
Χαρακτηριστικά
Ο τύπος πεδίου χαρακτηριστικών επιστρέφει έναν πίνακα ζευγών {attribute, value} για απόδοση ως χαρακτηριστικά HTML. Χρησιμοποιήστε το bs_render_data_attributes() για να τα εμφανίσετε:
PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
Content
</div>
Twig
<div {{ fn('bs_render_data_attributes', a.attributes) }}>
Content
</div>
Το bs_render_data_attributes() εκτυπώνει απευθείας τα χαρακτηριστικά. Το bs_data_attributes() επιστρέφει τη συμβολοσειρά.
Ομάδα
Τα πεδία ομάδας προσθέτουν το όνομα της ομάδας ως πρόθεμα στα αναγνωριστικά των θυγατρικών χαρακτηριστικών. Χρησιμοποιήστε το bs_get_group() για να εξαγάγετε τα πεδία της ομάδας σε έναν καθαρό πίνακα:
PHP
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>
Twig
{% set group = fn('bs_get_group', a, 'settings') %}
<h1>{{ group.title }}</h1>
<p>{{ group.description }}</p>
Αυτό αφαιρεί το πρόθεμα της ομάδας από τα κλειδιά χαρακτηριστικών. Για παράδειγμα, το $a['settings_title'] γίνεται $group['title'].
Η βοηθητική συνάρτηση λειτουργεί επίσης όταν η ομάδα προέρχεται από επαναχρησιμοποιημένο προσαρμοσμένο πεδίο:
{
"name": "section-header",
"attributes": [
{
"id": "section-header",
"type": "group",
"attributes": [
{ "id": "kicker", "type": "text" },
{ "id": "title", "type": "text" }
]
}
]
}
{
"blockstudio": {
"attributes": [
{ "type": "custom/section-header" }
]
}
}
{% set sectionHeader = fn('bs_get_group', a, 'section-header') %}
<p>{{ sectionHeader.kicker }}</p>
<h2>{{ sectionHeader.title }}</h2>
Επαναλήπτης
Επαναλάβετε τα στοιχεία του επαναλήπτη:
PHP
<?php foreach ($a['items'] as $item) : ?>
<div class="item">
<h3><?php echo $item['title']; ?></h3>
<p><?php echo $item['description']; ?></p>
</div>
<?php endforeach; ?>
Twig
{% for item in a.items %}
<div class="item">
<h3>{{ item.title }}</h3>
<p>{{ item.description }}</p>
</div>
{% endfor %}