Halaman & Pola
Blockstudio memungkinkan Anda mendefinisikan halaman WordPress, pola blok, dan templat Site Editor sebagai file di tema Anda. Tulis templat seperti HTML, lalu parser Blockstudio mengonversinya menjadi blok WordPress bawaan.
- Halaman disinkronkan ke basis data sebagai postingan WordPress, sehingga templat file dan konten halaman Anda tetap selaras.
- Pola didaftarkan dalam memori melalui
register_block_pattern(), dan tersedia di penyisip blok agar pengguna dapat menempatkannya di mana saja. - Templat Situs menyediakan sumber
wp_templatedanwp_template_partberbasis file untuk Site Editor WordPress.
Ketiga fitur menggunakan parser HTML dan sintaks blok yang sama.
Membangun Halaman Berbasis File
Panduan praktis tentang templat halaman berbasis file, sinkronisasi, dan penguncian.
Struktur Folder
theme/
├── pages/
│ ├── about/
│ │ ├── page.json
│ │ └── index.php
│ └── contact/
│ ├── page.json
│ └── index.twig
├── patterns/
├── hero/
│ ├── pattern.json
│ └── index.php
└── cta/
├── pattern.json
└── index.blade.php
├── templates/
└── front-page/
├── template.json
└── index.php
└── parts/
└── header/
├── part.json
└── index.php
Setiap subfolder berisi file konfigurasi JSON (page.json, pattern.json, template.json, atau part.json) dan file templat.
Mesin Templat
Templat dapat ditulis sebagai markup biasa dalam index.php, atau menggunakan Twig maupun Blade:
| File | Mesin | Persyaratan |
|---|---|---|
index.php |
Tidak ada (dibaca apa adanya, kode PHP tidak dieksekusi) | Tidak ada |
index.twig |
Twig | Timber |
index.blade.php |
Blade | illuminate/view |
Jika ada beberapa file templat, urutan prioritasnya adalah: index.php > index.blade.php > index.twig.
Karena templat dikompilasi saat inisialisasi (sebelum konteks permintaan apa pun tersedia), templat Twig dan Blade tidak dapat mengakses variabel dinamis. Templat ini berguna untuk fungsi bawaan dan filter seperti {{ "text"|upper }} atau {{ strtoupper("text") }}.
Pemetaan HTML ke Blok
Elemen HTML standar otomatis dikonversi menjadi blok WordPress yang sesuai.
Teks
| HTML | Blok |
|---|---|
<p> |
core/paragraph |
<h1> – <h6> |
core/heading |
<ul> |
core/list (tanpa urutan) |
<ol> |
core/list (berurutan) |
<li> |
core/list-item |
<blockquote> |
core/quote |
<code> |
core/code |
<pre> |
core/preformatted |
Struktur daftar tetap dipertahankan. <ul> atau <ol> di dalam <li> menjadi blok dalam core/list dari core/list-item tersebut, sesuai bentuk yang disimpan editor, sehingga daftar dapat bertingkat sedalam apa pun. class pada daftar atau item menjadi className-nya, yang digunakan untuk menetapkan gaya blok seperti is-style-checks dari file halaman; <block name="core/list" className="..."> melakukan hal yang sama.
Media
| HTML | Blok |
|---|---|
<img> |
core/image |
<figure> |
core/image (dengan keterangan) |
<audio> |
core/audio |
<video> |
core/video |
Tata Letak
| HTML | Blok |
|---|---|
<div>, <section> |
core/group |
<main>, <header>, <footer>, <article>, <aside> |
core/group yang mempertahankan elemen sebagai tagName-nya |
<hr> |
core/separator |
<details> |
core/details |
<table> |
core/table |
Sintaks Blok
Untuk blok yang tidak memiliki padanan HTML langsung, gunakan elemen <block>:
<block name="core/cover" url="https://example.com/hero.jpg">
<h1>Welcome</h1>
<p>Content inside the cover block.</p>
</block>
Blok Inti
<!-- Pullquote -->
<block name="core/pullquote">
<p>An important quote.</p>
</block>
<!-- Verse -->
<block name="core/verse">Roses are red,
Violets are blue.</block>
<!-- Cover -->
<block name="core/cover" url="https://example.com/image.jpg">
<h2>Cover Title</h2>
</block>
<!-- Embed -->
<block name="core/embed" url="https://youtube.com/watch?v=..." providerNameSlug="youtube" />
<!-- Spacer -->
<block name="core/spacer" height="50px" />
<!-- Gallery -->
<block name="core/gallery">
<img src="https://example.com/1.jpg" alt="Image 1" />
<img src="https://example.com/2.jpg" alt="Image 2" />
</block>
<!-- Columns -->
<block name="core/columns">
<block name="core/column">
<h3>Column 1</h3>
</block>
<block name="core/column">
<h3>Column 2</h3>
</block>
</block>
<!-- Buttons -->
<block name="core/buttons">
<block name="core/button" url="/get-started">Get Started</block>
</block>
<!-- Row (flex layout) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
<p>Item 1</p>
<p>Item 2</p>
</block>
Blok Kustom
Sintaks yang sama berlaku untuk semua blok terdaftar:
<block name="blockstudio/section">
<h1>Welcome</h1>
</block>
<block name="acf/hero" title="Hero Title" background="dark">
<p>Inner content becomes InnerBlocks.</p>
</block>
Atribut
Atribut HTML pada elemen <block> diteruskan sebagai atribut blok. Nilai JSON didukung:
<block name="core/heading" level="3">Custom Heading</block>
<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
<p>Stacked content.</p>
</block>
<img src="https://example.com/photo.jpg" alt="Photo" width="800" height="400" />
Nilai atribut didekodekan satu kali, seperti saat dibaca oleh browser, sehingga
data-animate="[&>span]:fade" dan data-animate="[&>span]:fade" menyimpan
nilai yang sama.
Pada elemen yang dipetakan ke blok Blockstudio, setiap atribut disimpan bersama blok tersebut. Field yang dideklarasikan diteruskan ke templat; atribut global yang tidak dideklarasikan oleh blok (id, style, role, title, lang, dir, hidden,
tabindex, aria-*, dan data-*) ditempatkan pada elemen akar blok saat dirender, sama seperti pada tag blok. Dalam sumber halaman dan pola, awalan html- hanya menamai salah satu atribut global tersebut, sehingga html-role="note" diteruskan sebagai role, sedangkan penangan event seperti html-onclick tidak pernah dirender. Yang lainnya, termasuk class yang tidak dideklarasikan, tetap berada dalam konten postingan tanpa diteruskan ke halaman, dan wp bs pages sync melaporkannya untuk setiap halaman yang diurainya.
Perender Blok Kustom
Parser HTML menggunakan arsitektur berbasis registry. Tambahkan builder untuk blok kustom dengan blockstudio/block_tags/builders:
add_filter( 'blockstudio/block_tags/builders', function( $builders, $parser ) {
$builders['acf/hero'] = function( array $attrs, string $inner_content ) {
$inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks( $inner_content );
return array(
'blockName' => 'acf/hero',
'attrs' => $attrs,
'innerBlocks' => $inner_blocks,
'innerHTML' => '',
'innerContent' => array_fill( 0, count( $inner_blocks ), null ),
);
};
return $builders;
}, 10, 2 );
Lalu gunakan di templat mana pun:
<block name="acf/hero" background="dark">
<h1>Welcome</h1>
</block>
Anda juga dapat mengganti cara blok inti dirender:
add_filter( 'blockstudio/parser/renderers', function( $renderers, $parser ) {
$renderers['core/paragraph'] = function( array $attrs, string $inner_content ) {
$content = trim( $inner_content );
$attrs['align'] = $attrs['align'] ?? 'center';
return array(
'blockName' => 'core/paragraph',
'attrs' => $attrs,
'innerBlocks' => array(),
'innerHTML' => '<p class="has-text-align-center">' . $content . '</p>',
'innerContent' => array( '<p class="has-text-align-center">' . $content . '</p>' ),
);
};
return $renderers;
}, 10, 2 );
Callback builder menerima atribut yang telah diurai dan konten dalam mentah. Callback harus mengembalikan array blok WordPress. Lihat Perender kustom untuk mengetahui urutan filter lengkap dan contoh kontainer.
Signature Fungsi Builder
/**
* @param array $attrs Parsed element or block-tag attributes.
* @param string $inner_content Raw inner content.
* @return array WordPress block array.
*/
function my_builder( array $attrs, string $inner_content ): array {}
Pemetaan Elemen
Secara default, elemen HTML standar seperti <h1>, <p>, dan <img> dipetakan ke blok WordPress inti. Anda dapat mengganti pemetaan ini agar elemen HTML mana pun mengarah ke blok lain menggunakan filter blockstudio/parser/element_mapping:
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
$mapping['h1'] = 'custom/heading';
$mapping['h2'] = 'custom/heading';
$mapping['p'] = 'custom/paragraph';
$mapping['img'] = 'custom/image';
return $mapping;
}, 10, 2 );
Dengan filter ini aktif, setiap <h1> dalam templat Anda akan menghasilkan blok custom/heading, bukan core/heading. Atribut elemen diteruskan ke blok tujuan. Jika perender terdaftar untuk nama blok tujuan, perender itu akan digunakan. Jika tidak, struktur blok generik akan dibuat.
Ini berguna ketika tema atau plugin Anda menyediakan jenis blok kustom yang harus menggantikan blok bawaan di semua templat halaman dan pola.
Untuk pemetaan <p> sederhana, Blockstudio dapat mengarahkan HTML dalam langsung ke atribut richtext content dari blok Blockstudio non-inti yang terdaftar. Blok tujuan harus mendeklarasikan atribut dengan id: "content" dan type: "richtext".
Pemformatan sebaris (a, b, br, code, del, em, i, img, ins,
mark, s, small, span, strong, sub, sup, u) tetap berada dalam nilai yang diarahkan meskipun tag yang sama dipetakan ke elemen, seperti code dan img secara default. Paragraf yang hanya memiliki gambar sebagai anak akan menjadi blok tujuan pemetaan <img>, sebagaimana Markdown menghasilkannya untuk gambar mandiri. Tag blok bertingkat dan HTML tingkat blok terus diurai sebagai blok dalam.
Nilai pemetaan juga dapat berupa callable ketika blok tujuan bergantung pada atribut elemen:
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
$mapping['div'] = function( array $attrs ) {
if ( isset( $attrs['width'] ) ) {
return 'theme/row';
}
if ( isset( $attrs['gap'] ) ) {
return 'theme/flow';
}
return 'theme/div';
};
return $mapping;
} );
Blok kustom yang dipetakan dari elemen kontainer seperti <section> dan <div> mengurai anak HTML bertingkat secara rekursif, sehingga judul, gambar, tag blok, dan paragraf di dalamnya menjadi blok anak bawaan.
Contoh Lengkap
Templat halaman lengkap yang menggabungkan berbagai jenis blok:
<div>
<h1>Welcome to Our Site</h1>
<p>This is an <strong>introduction</strong> with <em>formatting</em>.</p>
<block name="core/columns">
<block name="core/column">
<h3>Feature One</h3>
<p>First feature description.</p>
</block>
<block name="core/column">
<h3>Feature Two</h3>
<p>Second feature description.</p>
</block>
</block>
<block name="core/cover" url="https://example.com/hero.jpg">
<h2>Our Mission</h2>
<p>Building amazing things together.</p>
</block>
<details>
<summary>FAQ</summary>
<p>Answers to common questions.</p>
</details>
<block name="core/buttons">
<block name="core/button" url="/contact">Contact Us</block>
<block name="core/button" url="/learn-more">Learn More</block>
</block>
</div>