İçeriğe geç

Paketle Gelen UI ile Bir Uygulama Ekranı Oluşturma

Çoğu WordPress projesinde eninde sonunda sayfadan çok uygulamaya benzeyen bir ekrana ihtiyaç duyulur: kayıtların listesi, form açan bir düğme ve kayıt başarılı olduğunda gösterilen bir bildirim. Genellikle bunun için temanın yanında sürdürülen bir JavaScript çerçevesi, bir dizi REST denetleyicisi ve bir bileşen kitaplığı kullanılır.

Blockstudio bu parçaların her birini zaten içerir. db.php bir blok deposu, doğrulama ve CRUD uç noktaları sağlar. rpc.php özel sunucu eylemleri ekler. paketle gelen UI bileşenleri iletişim penceresini, form alanlarını, düğmeleri, rozetleri ve kısa bildirimleri sağlar. Bir Interactivity API deposu bunları birbirine bağlar. Bu kılavuz, tek bir blok klasöründe baştan sona bir ekran oluşturur:

  • Sunucuda oluşturulan ve istemcide eşit tutulan bir proje tablosu.
  • Şemaya göre doğrulama yapan formlı bir Yeni proje iletişim penceresi.
  • İyimser güncelleme ve geri alma ile bir RPC işlevini çağıran Arşivle ve Geri yükle düğmeleri.
  • Veri API’sini doğrudan kullanan Sil düğmeleri.
  • Başarılı bir oluşturma sonrasında bir kısa bildirim; bir değişiklik kaydedilmediğinde ise başka bir kısa bildirim.

Başlamadan önce

Paketle gelen bileşenler isteğe bağlıdır. Bunları blockstudio.json içinde etkinleştirin:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "ui": {
    "enabled": true
  }
}

Ekran tek bir blokta bulunur:

Kod
acme/
└── blockstudio/
    └── projects/
        ├── block.json
        ├── db.php
        ├── rpc.php
        ├── index.php
        ├── script.inline.js
        └── style.inline.css

1. Adım: Veri modeli

PHP
<?php
return [
    'storage'    => 'sqlite',
    'capability' => [
        'create' => 'edit_posts',
        'read'   => 'edit_posts',
        'update' => 'edit_posts',
        'delete' => 'edit_posts',
    ],
    'fields'     => [
        'name'   => [
            'type'      => 'string',
            'required'  => true,
            'minLength' => 2,
            'maxLength' => 80,
        ],
        'owner'  => [
            'type'     => 'string',
            'format'   => 'email',
            'required' => true,
        ],
        'status' => [
            'type'     => 'string',
            'enum'     => ['active', 'archived'],
            'required' => true,
        ],
    ],
];

Her işlem edit_posts yeteneğini gerektirir; bu nedenle oturum açmamış bir isteğe uç noktalar 401 yanıtı verir ve verileri yalnızca editörler ve üstündekiler değiştirebilir. SQLite deposu, kayıtları kodun yanındaki projects/db/default.sqlite içinde tutar.

status, bir default taşımak yerine required niteliğindedir. SQLite ve tablo depolama kullanıldığında şema, oluşturma sırasında eksik bir değeri doldurmaz; bu yüzden status olmadan oluşturulan bir kayıt boş değerle saklanır. Alanı zorunlu kılmak ve formdan göndermek her satırın geçerli kalmasını sağlar.

Komut satırından birkaç kayıt ekleyin:

Kabuk
wp bs db create acme/projects --name="Website relaunch" --owner=ana@example.com --status=active
wp bs db create acme/projects --name="Q3 report" --owner=ben@example.com --status=archived
wp bs db list acme/projects
Kod
Success: Record created (ID: 1).
Success: Record created (ID: 2).
id	name	owner	status	created_at	updated_at
2	Q3 report	ben@example.com	archived	...
1	Website relaunch	ana@example.com	active	...

Liste en yeni kayıt başta olacak şekilde döner; tablo da bu sırayı kullanır.

2. Adım: Sunucu eylemi

Kullanıcı açısından arşivleme basit bir alan düzenlemesi değildir; bu nedenle ona adlandırılmış bir işlev verilir:

PHP
<?php
use Blockstudio\Db;

return [
    'set_status' => [
        'callback'   => function (array $params) {
            $id     = (int) ($params['id'] ?? 0);
            $status = (string) ($params['status'] ?? '');
            $db     = Db::get('acme/projects');

            if (!$db->get_record($id)) {
                return new \WP_Error('not_found', 'Project not found.', ['status' => 404]);
            }

            return $db->update($id, ['status' => $status]);
        },
        'capability' => 'edit_posts',
    ],
];

Db::update() şemaya göre doğrulama yapar; bu nedenle db.php içindeki enum değeri korumaya devam eder. Bilinmeyen bir durumla işlev çağrıldığında, veri API ile aynı biçimde hata döner:

JSON
{"code":"blockstudio_db_validation","message":"Validation failed.","data":{"status":400,"errors":{"status":["Must be one of: active, archived."]}}}

İşlev komut satırından da çağrılabilir:

Kabuk
wp bs rpc call acme/projects set_status --id=2 --status=active
Kod
{
    "id": 2,
    "name": "Q3 report",
    "owner": "ben@example.com",
    "status": "active",
    ...
}

3. Adım: Blok tanımı

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/projects",
  "title": "Projects",
  "category": "widgets",
  "icon": "list-view",
  "supports": {
    "interactivity": true
  },
  "blockstudio": {
    "interactivity": {
      "enqueue": true
    }
  }
}

supports.interactivity, WordPress’in şablon yönergelerini sunucuda işlemesini sağlar; böylece herhangi bir JavaScript çalışmadan önce tablo satırları oluşturulur.

4. Adım: Şablon

PHP
<?php
$can_edit = current_user_can('edit_posts');
$projects = $can_edit ? \Blockstudio\Db::get('acme/projects')->list() : [];

wp_interactivity_state('acme/projects', [
    'projects'    => array_values($projects),
    'hasProjects' => !empty($projects),
    'notice'      => '',
    'isArchived'  => function () {
        $context = wp_interactivity_get_context();

        return 'archived' === ($context['project']['status'] ?? '');
    },
]);
?>
<div
    useBlockProps
    class="projects"
    data-wp-interactive="acme/projects"
    data-wp-on-document--formsuccess="actions.created"
>
<?php if (!$can_edit) : ?>
    <p>Sign in with an editor account to manage projects.</p>
<?php else : ?>
    <div class="projects__bar">
        <bs:bsui-text content="Projects" variant="title" tag="h2" />
        <bs:bsui-dialog>
            <bs:bsui-dialog-trigger trigger_label="New project" />
            <bs:bsui-dialog-backdrop />
            <bs:bsui-dialog-popup>
                <bs:bsui-dialog-header>
                    <bs:bsui-dialog-title content="New project" />
                    <bs:bsui-dialog-description content="Projects start out active." />
                </bs:bsui-dialog-header>
                <bs:bsui-dialog-content>
                    <bs:bsui-form block="acme/projects">
                        <bs:bsui-field name="name">
                            <bs:bsui-field-label text="Name" />
                            <bs:bsui-input name="name" placeholder="Spring campaign" required="true" />
                            <bs:bsui-field-error />
                        </bs:bsui-field>
                        <bs:bsui-field name="owner">
                            <bs:bsui-field-label text="Owner email" />
                            <bs:bsui-input name="owner" type="email" placeholder="owner@example.com" required="true" />
                            <bs:bsui-field-error />
                        </bs:bsui-field>
                        <input type="hidden" name="status" value="active" />
                        <bs:bsui-space size="2" />
                        <bs:bsui-button label="Create project" />
                    </bs:bsui-form>
                </bs:bsui-dialog-content>
                <bs:bsui-dialog-footer>
                    <bs:bsui-dialog-close label="Cancel" />
                </bs:bsui-dialog-footer>
            </bs:bsui-dialog-popup>
        </bs:bsui-dialog>
    </div>

    <table class="projects__table">
        <thead>
            <tr>
                <th scope="col">Name</th>
                <th scope="col">Owner</th>
                <th scope="col">Status</th>
                <th scope="col">Actions</th>
            </tr>
        </thead>
        <tbody>
            <template data-wp-each--project="state.projects" data-wp-each-key="context.project.id">
                <tr>
                    <td data-wp-text="context.project.name"></td>
                    <td data-wp-text="context.project.owner"></td>
                    <td>
                        <span data-wp-bind--hidden="state.isArchived"><bs:bsui-badge label="Active" variant="success" /></span>
                        <span data-wp-bind--hidden="!state.isArchived"><bs:bsui-badge label="Archived" variant="secondary" /></span>
                    </td>
                    <td class="projects__actions">
                        <span data-wp-on--click="actions.toggleArchived">
                            <span data-wp-bind--hidden="state.isArchived"><bs:bsui-button label="Archive" variant="outline" size="sm" /></span>
                            <span data-wp-bind--hidden="!state.isArchived"><bs:bsui-button label="Restore" variant="outline" size="sm" /></span>
                        </span>
                        <span data-wp-on--click="actions.remove"><bs:bsui-button label="Delete" variant="ghost" size="sm" /></span>
                    </td>
                </tr>
            </template>
        </tbody>
    </table>

    <p class="projects__empty" data-wp-bind--hidden="state.hasProjects">No projects yet.</p>

    <div class="projects__toasts">
        <bs:bsui-toast-provider>
            <div data-wp-interactive="acme/projects" data-wp-bind--hidden="!state.isCreatedNotice" data-wp-on--click="actions.dismissNotice">
                <bs:bsui-toast message="Project created." />
            </div>
            <div data-wp-interactive="acme/projects" data-wp-bind--hidden="!state.isFailedNotice" data-wp-on--click="actions.dismissNotice">
                <bs:bsui-toast message="That change was not saved." />
            </div>
        </bs:bsui-toast-provider>
    </div>
<?php endif; ?>
</div>

Bu şablonun dört bölümü daha yakından incelenmeyi hak ediyor.

Sunucu durumu ilk çizimi hazırlar. wp_interactivity_state() kayıtları hem sunucu tarafındaki yönerge işlemcisine hem de istemci deposuna verir. data-wp-each şablonu sunucuda gerçek satırlara genişletilir; her kayıt için bir tr oluşturulur. isArchived bir kapatmadır: WordPress sunucu işleme sırasında her satır için bunu değerlendirir; wp_interactivity_get_context() ise o satırın bağlamını döndürür. Böylece arşivlenmiş satırlar, hidratasyondan önce doğru rozeti ve düğmeyi gösterir. Tarayıcıda aynı adlı depo alıcısı devreye girer. hasProjects da aynı nedenle yalın bir değerdir: bu olmadan sunucu, boş durum paragrafını gizleyip gizlemeyeceğini bilemez.

İletişim penceresi ve form sistem bileşenleridir. trigger_label, tetikleyicinin içindeki bsui/button öğesine aktarılır; bu, UI Bileşim bölümünde açıklanmıştır. bsui/form, block="acme/projects" ile birlikte alanlarını FormData kullanarak serileştirir ve bu bloğun oluşturma uç noktasına gönderir. Her bsui/field, girişinin adını taşır; böylece şemadan gelen alan bazlı hatalar doğru denetimin altında görünür. Boş form gönderildiğinde Ad alanının altında “En az 2 karakter olmalıdır.”, Sorumlu e-posta alanının altında “Geçerli bir e-posta adresi olmalıdır.” ve formun altında “Doğrulama başarısız oldu.” görünür. Gizli status girdisi form verileriyle birlikte gönderilir; yeni projelerin zorunlu alanı karşılaması bu sayede sağlanır.

Tablo kendi işaretlemenizdir. bsui/table, şablonda tanımlanan satırlar için uygundur: başlık hücreleri mevcut tr öğelerini taşıyarak sıralama yapar; bu da satırların denetimini data-wp-each ile paylaşmasına yol açar. Blockstudio 7.7 öncesinde, parçaları ayrıca div öğesini doğrudan table, thead, tbody ve tr içine yerleştiriyordu; tarayıcılar da bu öğeyi tablonun dışına taşıyordu. Bir depodan gelen satırlar için table öğesini kendiniz yazın ve sistem bileşenlerini hücrelerin içinde tutun. Satır şablonundaki rozetler ve düğmeler sıradan bsui/badge ve bsui/button etiketleridir. Her düğme, tıklama yönergesini taşıyan bir span içinde yer alır; böylece düğme sistem düğmesi olarak kalırken eylem de deponuza ait olur.

Kısa bildirim görseldir. bsui/toast-provider kibar bir canlı bölge, bsui/toast ise kapat düğmeli bir durum mesajı oluşturur. Sağlayıcı kendisini ekranda konumlandırmaz ve kapat düğmesi işaretlemeden oluşturulmuş bir kısa bildirimi gizlemez. Bu nedenle ekran ikisini de yapar: position: fixed içeren bir sarmalayıcı bölgeyi konumlandırır; her kısa bildirim de hidden bağlaması ve tıklama işleyicisi ekranın deposuna ait olan bir div içinde yer alır. Kapat düğmesine tıklama, div öğesine kadar yayılır.

5. Adım: Depo

JavaScript
import { store, getContext } from '@wordpress/interactivity';

const BLOCK = 'acme/projects';
let noticeTimer;

// bs.fn() and bs.db() resolve with the error body on a failed request.
// Throwing here is what lets bs.mutate() roll the optimistic change back.
const ok = (request) =>
    request.then((result) => {
        if (result?.code) {
            throw result;
        }
        return result;
    });

const notify = (notice) => {
    state.notice = notice;
    clearTimeout(noticeTimer);
    noticeTimer = setTimeout(() => {
        state.notice = '';
    }, 4000);
};

const { state } = store(BLOCK, {
    state: {
        get hasProjects() {
            return state.projects.length > 0;
        },
        get isArchived() {
            return getContext().project.status === 'archived';
        },
        get isCreatedNotice() {
            return state.notice === 'created';
        },
        get isFailedNotice() {
            return state.notice === 'failed';
        },
    },
    actions: {
        created(event) {
            const record = event.detail;
            if (!record?.id || !('owner' in record)) {
                return;
            }

            event.preventDefault();
            state.projects = [record, ...state.projects];
            store('bsui/dialog').actions.close();
            notify('created');
        },
        dismissNotice() {
            state.notice = '';
        },
        *toggleArchived() {
            const project = getContext().project;
            const status = project.status === 'archived' ? 'active' : 'archived';

            try {
                yield bs.mutate({
                    fn: () => ok(bs.fn('set_status', { id: project.id, status }, BLOCK)),
                    state,
                    key: 'projects',
                    action: 'update',
                    id: project.id,
                    optimistic: { status },
                });
            } catch (error) {
                notify('failed');
            }
        },
        *remove() {
            const project = getContext().project;

            try {
                yield bs.mutate({
                    fn: () => ok(bs.db(BLOCK).delete(project.id)),
                    state,
                    key: 'projects',
                    action: 'delete',
                    id: project.id,
                });
            } catch (error) {
                notify('failed');
            }
        },
    },
});

Forma tepki verme. Kayıt başarıyla kaydedildiğinde bsui/form, yayılan, iptal edilebilen ve oluşturulan kaydı event.detail içinde taşıyan bir formsuccess olayı gönderir. Kayıt başarısız olursa hata gövdesiyle formerror gönderilir. Dinleyici, ekranın kök öğesi yerine belgeye (data-wp-on-document--formsuccess) eklenir; çünkü açık iletişim penceresi açılır penceresi document.body öğesine taşınır ve bu nedenle olayları artık blok üzerinden yayılmaz. owner denetimi, aynı sayfadaki diğer formlardan gelen olayları atlar.

event.preventDefault() çağrısı, formun alanlarını başarı mesajıyla değiştirmesini engeller; form yine de sıfırlanır. Ardından eylem kaydı başa ekler, iletişim penceresini bsui/dialog deposunun close eylemiyle kapatır ve kısa bildirimi gösterir. close en üstteki açık iletişim penceresini kapatıp odağı tetikleyicisine döndürür; bu nedenle kayıt oluşturulduktan sonra klavye odağı Yeni proje düğmesine geri gelir.

Hatalarda geri alma. bs.mutate() iyimser değişikliği hemen uygular ve fn tarafından döndürülen vaat reddedildiğinde önceki değerleri geri yükler. bs.fn() ve bs.db(), HTTP hatalarında reddetmez: RPC işlevinden gelen bir WP_Error, doğrulama hatası ya da eksik kayıt, tümü hata gövdesiyle sonuçlanır. ok() yardımcı işlevi, code içeren sonucu reddetmeye dönüştürür; böylece satır eski hâline döner ve hata bildirimi görünür. Bu olmazsa başarısız bir güncelleme hata gövdesini satırla birleştirir, başarısız bir silme ise satırı silinmiş durumda bırakır.

Bloğu adlandırma. Blockstudio satır içi betikleri <script type="module"> olarak yazdırır; modül betiklerinin document.currentScript değeri olmadığından bs.fn() hangi bloğun çağrı yaptığını belirleyemez. Depoda olduğu gibi blok adını üçüncü bağımsız değişken olarak iletin: BLOCK.

6. Adım: Ekranı bir sayfaya yerleştirme

Dosya tabanlı bir sayfa, bloğu etiketiyle yerleştirir:

JSON
{
  "$schema": "https://blockstudio.dev/schema/page",
  "name": "projects",
  "title": "Projects",
  "slug": "projects",
  "postStatus": "private"
}
PHP
<h1>Projects</h1>
<bs:acme-projects />

Ayrıştırıcı etiketi yerel bir bloğa dönüştürür:

HTML
<!-- wp:heading {"level":1} --><h1 class="wp-block-heading">Projects</h1><!-- /wp:heading --><!-- wp:acme/projects /-->

Sayfayı oluşturmak için wp bs pages sync komutunu çalıştırın. postStatus: "private", yalnızca oturum açma mesajını görecek olan anonim ziyaretçilere sayfanın gösterilmesini engeller.

Ekranın çalışma zamanında yaptıkları

Sayfa editör olarak açıkken:

  1. Tablo iki satır da işlenmiş olarak gelir; arşivlenen satırda Arşivlendi rozeti ve bir Geri yükle düğmesi görünür.
  2. Yeni proje iletişim penceresini açar. Açılır pencere ve arka plan document.body öğesine taşınır, odak Ad alanına gelir ve Escape veya İptal pencereyi kapatır.
  3. Geçerli değerler gönderildiğinde /wp-json/blockstudio/v1/db/acme-projects/default‘ye tek bir POST gönderilir. İletişim penceresi kapanır, yeni satır en üstte görünür ve köşede dört saniye boyunca "Proje oluşturuldu." mesajı gösterilir.
  4. Arşivle, rozeti hemen değiştirir ve /wp-json/blockstudio/v1/fn/acme/projects/set_status üzerinden set_status gönderir. Bu sırada kayıt başka bir yerde silindiyse işlev 404 hatasını döndürür, satır Etkin durumuna geri döner ve "Bu değişiklik kaydedilmedi." mesajı görünür.
  5. Sil, satırı hemen kaldırır. Son kayıt silindiğinde "Henüz proje yok." mesajı görünür.

Stil

Ekranın kendi CSS dosyası kitaplık belirteçlerini okur; böylece tablo çevresindeki bileşenlerle uyumlu görünür ve --bs-ui-* özelliklerindeki tema değişikliklerini izler:

CSS
.projects__table {
    width: 100%;
    border-collapse: collapse;
    font-size: var(--bs-ui-font-size);
}

.projects__table th,
.projects__table td {
    padding: var(--bs-ui-space-2) var(--bs-ui-space-3);
    border-bottom: 1px solid var(--bs-ui-border);
    text-align: left;
}

/* ... */

.projects__toasts {
    position: fixed;
    right: var(--bs-ui-space-4);
    bottom: var(--bs-ui-space-4);
    z-index: 40;
}

z-index içindeki 40 değeri, kısa bildirim bölgesini 50 konumunda duran iletişim penceresinin arka planının altında tutar. Tüm ekranın temasını değiştirmek için stil bölümünde açıklandığı gibi belirteçleri geçersiz kılın; bileşenler ve tablo da buna uyar.

Sonraki adımlar

  • UI Bileşenleri: tasarım sistemi, belirteçler ve tüm bileşen kümesi.
  • UI Bileşim: bileşik aileler, tetikleyici aktarımı ve iletişim penceresinin katmanlama modeli.
  • Veritabanı: depolama modları, erişim denetimi, bs.db() ve bs.mutate().
  • RPC: erişim denetimi, HTTP yöntemleri ve bloklar arası çağrılar.
  • Tam Yığın Blokları: aynı yapı taşlarının bir yapılacaklar uygulamasında ve bülten kaydında kullanımı.