Przejdź do treści

Przechowywanie

Domyślnie wszystkie wartości pól są przechowywane jako atrybuty bloku w komentarzu bloku w treści wpisu. Funkcja przechowywania pozwala dodatkowo zapisywać wartości w metadanych wpisu (wp_postmeta) lub opcjach (wp_options), dzięki czemu są dostępne poza kontekstem bloku.

Po co korzystać z przechowywania?

Atrybuty bloku są przechowywane w komentarzach HTML w treści wpisu, co oznacza, że są dostępne tylko podczas analizowania zawartości bloków. Korzystając z dodatkowych lokalizacji przechowywania, możesz:

  • Wyszukiwać wpisy według wartości pól za pomocą meta_query
  • Uzyskiwać dostęp do wartości przez REST API w konfiguracjach bez interfejsu
  • Udostępniać dane innym wtyczkom, takim jak SEO, lub wtyczkom buforującym
  • Tworzyć ustawienia globalne, które są zachowywane między wpisami

Typy przechowywania

Typ Lokalizacja Zakres Najlepsze zastosowanie
postMeta Tabela wp_postmeta Dla każdego wpisu Możliwe do wyszukania dane dotyczące konkretnego wpisu
option Tabela wp_options Globalny (cała witryna) Ustawienia witryny, współdzielone wartości

Uwaga

Atrybuty bloku są zawsze automatycznie przechowywane w komentarzu HTML treści wpisu. Właściwość storage dodaje dodatkowe lokalizacje przechowywania, ale nie zastępuje przechowywania w bloku.

Konfiguracja

Dodaj właściwość storage do dowolnej definicji pola:

JSON
{
  "name": "blockstudio/example",
  "title": "Example Block",
  "blockstudio": {
    "attributes": [
      {
        "id": "subtitle",
        "type": "text",
        "label": "Subtitle",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "my_subtitle"
        }
      }
    ]
  }
}

Właściwości przechowywania

Właściwość Typ Opis
type string | string[] Dodatkowe miejsce przechowywania location(s): "postMeta", "option"
postMetaKey string Własny klucz metadanych (domyślnie: {block_name}_{field_id})
optionKey string Własny klucz opcji (domyślnie: {block_name}_{field_id})

Jedno czy wiele miejsc przechowywania

JSON
// Add post meta storage
"storage": {
  "type": "postMeta"
}

// Add both post meta and option storage
"storage": {
  "type": ["postMeta", "option"]
}

Jak to działa

  1. Rejestracja: Po załadowaniu WordPress, Blockstudio rejestruje klucze meta i ustawienia na podstawie konfiguracji pól
  2. Edycja: Wartości są zarządzane jako atrybuty bloków w edytorze (zawsze przechowywane w bloku)
  3. Zapisywanie: Metadane wpisu są synchronizowane po zapisaniu wpisu. Opcje witryny są synchronizowane po opublikowaniu wpisu lub zmianie wartości pola we wpisie już opublikowanym.

Automatyczne zapisy i wersje nie synchronizują żadnej z tych lokalizacji przechowywania. Wpisy robocze, oczekujące, prywatne i zaplanowane mogą aktualizować własne metadane, ale nie zmieniają aktywnych opcji witryny. Opcje wpisu zaplanowanego są synchronizowane po jego opublikowaniu przez WordPress.

Wartości są kopiowane dosłownie, łącznie z ukośnikami odwrotnymi, cudzysłowami i zagnieżdżonymi wartościami powtarzacza. Nie dodawaj znaków ucieczki do wartości pól, aby zrekompensować przechowywanie metadanych WordPress; za tę granicę odpowiada Blockstudio. Opcje witryny zachowują te same dosłowne wartości bez dodatkowego poprzedzania ukośnikami.

Jeśli wcześniejsza wersja usuwała ukośniki odwrotne z kopii metadanych wpisu, po aktualizacji zapisz wpis ponownie. Oryginalna wartość pola w atrybutach bloku służy do odświeżenia kopii metadanych.

Zapisywanie opcji witryny

Opcje są współdzielone w całej witrynie. Opublikowanie nowego bloku zapisuje wartości pól opcji podane w jego zapisanych atrybutach. Przy kolejnych zapisach każde pole jest porównywane z poprzednią zapisaną wersją tego bloku, a zapisywane są tylko zmienione wartości. Zapisanie tytułu wpisu ani niezmienionej starszej kopii bloku w innym wpisie nie nadpisuje nowszej wartości opcji.

Pominięcie pola w zapisanych atrybutach pozostawia jego opcję bez zmian. Chroni to również istniejące opcje, gdy nowe pole zostanie dodane do block.json. Jawne null usuwa opcję; puste ciągi, false, 0 i puste tablice są zapisywane jako wartości. Usunięcie bloku nie usuwa jego opcji.

Do zarządzania każdą współdzieloną opcją używaj jednego wyznaczonego, opublikowanego bloku. Jeśli kilka bloków celowo zmienia tę samą opcję, wygrywa ostatnia zapisana wartość. Mechanizm przechowywania nie wczytuje bieżącej opcji do każdego bloku: każdy blok zachowuje własne wartości pól w treści wpisu.

W przypadku stron opartych na plikach trwały blok key pozwala Blockstudio rozpoznać ten sam blok po przeniesieniu go w dokumencie. Bloki bez klucza są dopasowywane według nazwy i pozycji.

Dostęp do zapisanych wartości

W szablonach bloków

W szablonie bloku wartości pól są zawsze dostępne za pośrednictwem $attributes:

PHP

PHP
<div>
  <h1><?php echo $a['subtitle']; ?></h1>
</div>

Twig

Twig
<div>
  <h1>{{ a.subtitle }}</h1>
</div>

Metadane wpisu (poza kontekstem bloku)

Wartości zapisane w postMeta są dostępne w dowolnym miejscu w WordPress:

PHP

PHP
// Get meta value
$subtitle = get_post_meta( $post_id, 'my_subtitle', true );

// Query posts by meta value
$posts = get_posts([
  'meta_key'   => 'my_subtitle',
  'meta_value' => 'Hello World',
]);

Twig

Twig
{# Using Timber #}
{{ post.meta('my_subtitle') }}

{# Or via function #}
{{ function('get_post_meta', post.id, 'my_subtitle', true) }}

Metadane wpisu są również dostępne za pośrednictwem REST API:

Powłoka
GET /wp-json/wp/v2/posts/123
# Response includes: { "meta": { "my_subtitle": "Hello World" } }

Opcje (wartości globalne)

Wartości zapisane w option są dostępne w całej witrynie:

PHP

PHP
$company_name = get_option( 'site_company_name' );

Twig

Twig
{{ function('get_option', 'site_company_name') }}

Przykłady

SEO pola meta

Zapisuj dane SEO w metadanych wpisu, aby zapewnić zgodność z wtyczkami SEO:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "seo_title",
        "type": "text",
        "label": "SEO Title",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "_yoast_wpseo_title"
        }
      },
      {
        "id": "seo_description",
        "type": "textarea",
        "label": "Meta Description",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "_yoast_wpseo_metadesc"
        }
      }
    ]
  }
}

Dodaj przechowywanie metadanych wpisu, aby umożliwić wyszukiwanie wpisów według wartości pola:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "featured",
        "type": "toggle",
        "label": "Featured",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "is_featured"
        }
      }
    ]
  }
}

Wyszukaj wyróżnione wpisy:

PHP
$featured_posts = get_posts([
  'meta_key'   => 'is_featured',
  'meta_value' => '1',
]);

Globalne ustawienia witryny

Przechowuj konfigurację całej witryny w opcjach:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "company_name",
        "type": "text",
        "label": "Company Name",
        "storage": {
          "type": "option",
          "optionKey": "site_company_name"
        }
      },
      {
        "id": "support_email",
        "type": "text",
        "label": "Support Email",
        "storage": {
          "type": "option",
          "optionKey": "site_support_email"
        }
      }
    ]
  }
}

Uzyskaj dostęp w dowolnym miejscu witryny:

PHP
<footer>
  <p>&copy; <?php echo get_option( 'site_company_name' ); ?></p>
  <p>Contact: <?php echo get_option( 'site_support_email' ); ?></p>
</footer>

Metadane wpisu i opcja

W przypadku danych, które muszą być dostępne zarówno na poziomie wpisu, jak i globalnie:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "important_value",
        "type": "text",
        "label": "Important Value",
        "storage": {
          "type": ["postMeta", "option"],
          "postMetaKey": "important_meta",
          "optionKey": "important_option"
        }
      }
    ]
  }
}

Domyślne nazwy kluczy

Jeśli nie podasz własnego klucza, Blockstudio wygeneruje go automatycznie:

Typ przechowywania Domyślny format klucza Przykład
postMeta {block_name}_{field_id} blockstudio_example_subtitle
option {block_name}_{field_id} blockstudio_example_subtitle

Nazwa bloku jest oczyszczana (ukośniki są zastępowane podkreśleniami).

Ostrzeżenie

W środowisku produkcyjnym zalecamy używanie własnych kluczy. Domyślne klucze mogą się zmienić po zmianie nazwy bloku.