İçeriğe geç

Sayfalar ve Kalıplar

Blockstudio, temanızda WordPress sayfaları, blok kalıplarını ve Site Düzenleyicisi şablonlarını dosya olarak tanımlamanızı sağlar. HTML benzeri şablonlar yazın; Blockstudio ayrıştırıcısı bunları yerel WordPress bloklarına dönüştürür.

  • Sayfalar, dosya şablonlarınızı ve sayfa içeriğinizi eşzamanlı tutarak veritabanına WordPress gönderileri olarak eşitlenir.
  • Kalıplar, register_block_pattern() aracılığıyla belleğe kaydedilir ve kullanıcıların istedikleri yere ekleyebilmesi için blok ekleyicide kullanılabilir.
  • Site Şablonları, WordPress Site Düzenleyicisi için dosya tabanlı wp_template ve wp_template_part kaynakları sağlar.

Üç özelliğin tümü aynı HTML ayrıştırıcısını ve blok söz dizimini kullanır.

Dosya Tabanlı Sayfalar Oluşturma

Dosya tabanlı sayfa şablonları, eşitleme ve kilitleme hakkında uygulamalı bir rehber.

Klasör Yapısı

Kod
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

Her alt klasörde bir JSON yapılandırma dosyası (page.json, pattern.json, template.json veya part.json) ve bir şablon dosyası bulunur.

Şablon Motorları

Şablonlar index.php içinde düz işaretleme olarak ya da Twig veya Blade ile yazılabilir:

Dosya Motor Gereksinim
index.php Yok (olduğu gibi okunur, PHP kodu çalıştırılmaz) Yok
index.twig Twig Timber
index.blade.php Blade illuminate/view

Birden fazla şablon dosyası varsa öncelik sırası şöyledir: index.php > index.blade.php > index.twig.

Şablonlar başlatma sırasında (herhangi bir istek bağlamından önce) derlendiğinden, Twig ve Blade şablonları dinamik değişkenlere erişemez. {{ "text"|upper }} veya {{ strtoupper("text") }} gibi yerleşik işlevler ve filtreler için kullanışlıdırlar.

HTML Blok Eşlemesi

Standart HTML öğeleri otomatik olarak karşılık gelen WordPress bloklarına dönüştürülür.

Metin

HTML Blok
<p> core/paragraph
<h1> – <h6> core/heading
<ul> core/list (sırasız)
<ol> core/list (sıralı)
<li> core/list-item
<blockquote> core/quote
<code> core/code
<pre> core/preformatted

Listeler yapılarını korur. Bir <ul> veya <ol>, bir <li> içinde core/list olduğunda, düzenleyicinin kaydettiği biçimle uyumlu olarak o core/list-item öğesinin iç bloğuna dönüşür; böylece listeler her derinlikte iç içe geçebilir. Liste veya öğe üzerindeki bir class, öğenin className değerine dönüşür; böylece sayfa dosyasından is-style-checks gibi bir blok stili ayarlanabilir; <block name="core/list" className="..."> de aynı işi yapar.

Medya

HTML Blok
<img> core/image
<figure> core/image (altyazılı)
<audio> core/audio
<video> core/video

Yerleşim

HTML Blok
<div>, <section> core/group
<main>, <header>, <footer>, <article>, <aside> Öğeyi kendi tagName olarak tutan core/group
<hr> core/separator
<details> core/details
<table> core/table

Blok Söz Dizimi

Doğrudan bir HTML karşılığı olmayan bloklar için <block> öğesini kullanın:

HTML
<block name="core/cover" url="https://example.com/hero.jpg">
  <h1>Welcome</h1>
  <p>Content inside the cover block.</p>
</block>

Çekirdek Bloklar

HTML
<!-- 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>

Özel Bloklar

Aynı söz dizimi, kayıtlı tüm bloklarda çalışır:

HTML
<block name="blockstudio/section">
  <h1>Welcome</h1>
</block>

<block name="acf/hero" title="Hero Title" background="dark">
  <p>Inner content becomes InnerBlocks.</p>
</block>

Öznitelikler

HTML öznitelikleri, <block> öğelerine blok öznitelikleri olarak aktarılır. JSON değerleri desteklenir:

HTML
<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" />

Öznitelik değerleri, tarayıcının okuduğu gibi bir kez çözülür; böylece data-animate="[&amp;>span]:fade" ve data-animate="[&>span]:fade" aynı değeri saklar.

Blockstudio bloğuna eşlenen bir öğedeki her öznitelik blokla birlikte saklanır. Tanımlı alanlar şablona ulaşır; bloğun tanımlamadığı genel öznitelikler (id, style, role, title, lang, dir, hidden, tabindex, aria-* ve data-*), oluşturulurken bloğun kök öğesine eklenir; blok etiketlerinde olduğu gibi. Sayfa ve kalıp kaynaklarında html- öneki yalnızca bu genel özniteliklerden birini belirtir; bu nedenle html-role="note", role olarak aktarılır; html-onclick gibi olay işleyicileri ise hiçbir zaman oluşturulmaz. Tanımlanmamış bir class dahil geri kalan her şey, sayfaya ulaşmadan gönderi içeriğinde kalır ve wp bs pages sync ayrıştırdığı her sayfa için bunu bildirir.

Özel Blok Oluşturucular

HTML ayrıştırıcısı kayıt tabanlı bir mimari kullanır. blockstudio/block_tags/builders ile özel bir blok için oluşturucu ekleyin:

PHP
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 );

Ardından bunu istediğiniz şablonda kullanın:

HTML
<block name="acf/hero" background="dark">
  <h1>Welcome</h1>
</block>

Çekirdek blokların nasıl oluşturulduğunu da geçersiz kılabilirsiniz:

PHP
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 );

Oluşturucu geri çağrıları, ayrıştırılmış öznitelikleri ve ham içeriği alır. Bir WordPress blok dizisi döndürmelidir. Filtre sırasının tamamı ve kapsayıcı örneği için Özel oluşturucular bölümüne bakın.

Oluşturucu İşlevinin İmzası

PHP
/**
 * @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 {}

Öğe Eşleme

Varsayılan olarak <h1>, <p> ve <img> gibi standart HTML öğeleri çekirdek WordPress bloklarıyla eşlenir. Bu eşlemeyi geçersiz kılmak için blockstudio/parser/element_mapping filtresiyle istediğiniz herhangi bir HTML öğesini farklı bir bloğa yönlendirebilirsiniz:

PHP
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 );

Bu filtre etkin olduğunda şablonlarınızdaki her <h1>, core/heading yerine bir custom/heading bloğu oluşturur. Öğenin öznitelikleri hedef bloğa aktarılır. Hedef blok adı için bir oluşturucu kayıtlıysa o kullanılır; aksi takdirde genel bir blok yapısı oluşturulur.

Temanız veya eklentiniz tüm sayfa ve kalıp şablonlarında varsayılanların yerine geçmesi gereken özel blok türleri sağlıyorsa bu yöntem kullanışlıdır.

Basit <p> eşlemelerinde Blockstudio, içteki HTML içeriğini doğrudan kayıtlı, çekirdek olmayan bir Blockstudio bloğunun content richtext özniteliğine yönlendirebilir. Hedef blok, id: "content" ve type: "richtext" içeren bir öznitelik tanımlamalıdır. Satır içi biçimlendirme (a, b, br, code, del, em, i, img, ins, mark, s, small, span, strong, sub, sup, u), aynı etiket varsayılan olarak code ve img öğeleriyle eşlense bile yönlendirilen değerde kalır. Tek alt öğesi görsel olan bir paragraf, <img> eşlemesinin hedeflediği bloğa dönüşür; bağımsız bir görsel için Markdown bunu üretir. İç içe blok etiketleri ve blok düzeyindeki HTML, iç bloklar olarak ayrıştırılmaya devam eder.

Eşleme değerleri, hedef bloğun öğe özniteliklerine bağlı olduğu durumlarda çağrılabilir işlevler de olabilir:

PHP
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;
} );

<section> ve <div> gibi kapsayıcı öğelerden eşlenen özel bloklar, iç içe HTML alt öğelerini yinelemeli olarak ayrıştırır; böylece iç başlıklar, görseller, blok etiketleri ve paragraflar yerel alt bloklara dönüşür.

Tam Örnek

Birden fazla blok türünü bir araya getiren eksiksiz bir sayfa şablonu:

HTML
<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>