Przejdź do treści

Pierwsze kroki

Ten przewodnik pomoże Ci skonfigurować Blockstudio i utworzyć pierwszy niestandardowy blok.

Instalacja

Powłoka
composer require blockstudio/blockstudio

Blockstudio można zainstalować jako wtyczkę za pośrednictwem composer/installers lub dołączyć bezpośrednio do motywu. Wszystkie sposoby instalacji opisano w dokumentacji Composer.

Instalacje Composer otrzymują aktualizacje przez Composer. Wbudowany mechanizm aktualizacji GitHub jest automatycznie wyłączony.

Instalacja ręczna

Pobierz najnowsze wydanie z GitHub

Prześlij plik zip do katalogu wtyczek WordPress i aktywuj wtyczkę. Instalacje ręczne otrzymują automatyczne powiadomienia o aktualizacjach w panelu WordPress za pośrednictwem wbudowanego mechanizmu aktualizacji GitHub.

Obie metody instalacji dołączają prywatne kopie bibliotek Markdown, YAML i aktualizatora wraz z ich zależnościami. Nie korzystają z wersji dostarczanych przez inne wtyczki lub motywy ani ich nie zastępują. Jeśli Twoja aplikacja korzysta bezpośrednio z jednej z tych bibliotek, zainstaluj własną zależność Composer; dołączone kopie Blockstudio są wewnętrzne, a nie stanowią publicznego interfejsu PHP API.

Uwierzytelnione sprawdzanie aktualizacji

Instalacje ręczne domyślnie sprawdzają GitHub anonimowo. Kilka witryn korzystających z tego samego wychodzącego IP może wyczerpać anonimowy limit API GitHub i otrzymywać odpowiedzi HTTP 403 podczas sprawdzania aktualizacji. W 7.7.4 skonfiguruj osobisty token dostępu GitHub w wp-config.php, zanim załaduje się WordPress:

PHP
define('BLOCKSTUDIO_GITHUB_TOKEN', 'your-github-token');

Token wymaga dostępu wyłącznie do publicznych informacji o repozytorium. Nie przyznawaj uprawnień do zapisu. Przechowuj go w konfiguracji po stronie serwera, poza kontrolą wersji, a także poza blockstudio.json, atrybutami bloków i kodem frontendu. Aktualizator przekazuje go do dołączonego klienta GitHub w celu uwierzytelnionego sprawdzania i pobierania wydań. Żądania dotyczące niezwiązanych repozytoriów i innych hostów pobierania nie otrzymują tego tokenu.

W przypadku sekretów zarządzanych przez środowisko wtyczka MU może dostarczyć token lub zastąpić jego wartość:

PHP
<?php
add_filter('blockstudio/updater/token', function ($token) {
  return getenv('BLOCKSTUDIO_GITHUB_TOKEN') ?: $token;
});

Filtr jest uruchamiany, gdy Blockstudio inicjuje swój aktualizator, przed załadowaniem motywu. Zarejestruj go we wtyczce MU zamiast w functions.php. Zwrócenie pustego ciągu wyłącza uwierzytelnianie, nawet jeśli stała jest zdefiniowana. Puste wartości lub wartości inne niż ciągi znaków powodują anonimowe sprawdzanie. Tokeny są opcjonalne; bez tokenu dotychczasowe działanie aktualizacji pozostaje bez zmian. Instalacje Composer nadal używają Composer do aktualizacji i nie inicjują tego aktualizatora.

Tworzenie pierwszego bloku

1. Utwórz katalog bloku

Utwórz nowy katalog w motywie:

Kod
my-theme/
  blockstudio/
    my-first-block/
      block.json
      index.php

2. Zdefiniuj schemat bloku

Utwórz block.json z konfiguracją bloku:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "my-theme/my-first-block",
  "title": "My First Block",
  "category": "common",
  "icon": "star-filled",
  "blockstudio": {
    "attributes": [
      {
        "id": "heading",
        "type": "text",
        "label": "Heading",
        "default": "Hello World"
      },
      {
        "id": "content",
        "type": "textarea",
        "label": "Content"
      }
    ]
  }
}

3. Utwórz szablon

Utwórz index.php do renderowania:

PHP
<div class="my-first-block">
  <h2><?php echo $a['heading']; ?></h2>
  <p><?php echo $a['content']; ?></p>
</div>

Korzystanie z szablonów Twig

Blockstudio obsługuje szablony Twig od razu po instalacji. Wystarczy użyć index.twig:

Twig
<div class="my-first-block">
  <h2>{{ a.heading }}</h2>
  <p>{{ a.content }}</p>
</div>

Dodawanie stylów

Utwórz plik style.css w tym samym folderze:

CSS
.my-first-block {
  padding: 2rem;
  background: #f5f5f5;
}

Blockstudio automatycznie doda ten arkusz stylów do kolejki, gdy blok będzie używany.

Tłumaczenia

Elementy sterujące edytora i przegląd administracyjny Blockstudio wczytują tłumaczenia JavaScript dla domeny tekstowej blockstudio za pośrednictwem WordPress. Zainstaluj odpowiedni pakiet językowy lub wygeneruj pliki tłumaczeń skryptów JSON za pomocą narzędzia tłumaczeniowego w wp-content/languages/plugins/. Ciągi bez dostępnego tłumaczenia pozostają po angielsku. Tłumaczy to własny interfejs Blockstudio, a nie treść ani etykiety pól zdefiniowane w blokach.

Następne kroki

Blok jest już gotowy do użycia w edytorze WordPress. Zapoznaj się z dalszą częścią dokumentacji, aby dowiedzieć się więcej o:

  • Typy pól – wszystkich dostępnych typach pól
  • Komponenty – InnerBlocks, RichText i nie tylko
  • TailwindIntegracja – korzystaniu z Tailwind CSS
  • Hooki – rozszerzaniu funkcjonalności za pomocą filtrów i akcji

Tworzenie biblioteki bloków

Przejdź od pojedynczego bloku do pełnej biblioteki: tokeny projektu, wzorzec sekcji, pola powtarzalne, obrazy i komponowanie stron.