Blok (Gutenberg)
Beginilah cara mengambil data blok Gutenberg.
Skema GraphQL memiliki field-field berikut yang ditambahkan ke semua tipe CustomPost (seperti Post dan Page):
blocksblockDataItemsblockFlattenedDataItems
Field-field ini tidak diaktifkan jika plugin Classic Editor sedang aktif.
blocks
Field CustomPost.blocks: [BlockUnion!] mengambil daftar semua blok yang terdapat dalam custom post.
blocks mengembalikan daftar tipe Block yang telah dipetakan ke skema GraphQL. Tipe-tipe Block ini semuanya merupakan bagian dari tipe BlockUnion, dan mengimplementasikan antarmuka Block.
Plugin ini mengimplementasikan satu tipe Block, GenericBlock, yang sudah cukup untuk mengambil data dari blok mana pun (melalui field attributes: JSONObject).
Query ini:
{
post(by: { id: 1 }) {
blocks {
...on Block {
name
attributes
innerBlocks {
...on Block {
name
attributes
innerBlocks {
...on Block {
name
attributes
}
}
}
}
}
}
}
}
}...akan menghasilkan respons ini:
{
"data": {
"post": {
"blocks": [
{
"name": "core/gallery",
"attributes": {
"linkTo": "none",
"className": "alignnone",
"images": [
{
"url": "https://d.pr/i/zd7Ehu+",
"alt": "",
"id": "1706"
},
{
"url": "https://d.pr/i/jXLtzZ+",
"alt": "",
"id": "1705"
}
],
"ids": [],
"shortCodeTransforms": [],
"imageCrop": true,
"fixedHeight": true,
"sizeSlug": "large",
"allowResize": false
},
"innerBlocks": null
},
{
"name": "core/heading",
"attributes": {
"content": "List Block",
"level": 2
},
"innerBlocks": null
},
{
"name": "core/list",
"attributes": {
"ordered": false,
"values": "<li>List item 1</li><li>List item 2</li><li>List item 3</li><li>List item 4</li>"
},
"innerBlocks": null
},
{
"name": "core/heading",
"attributes": {
"className": "has-top-margin",
"content": "Columns Block",
"level": 2
},
"innerBlocks": null
},
{
"name": "core/columns",
"attributes": {
"isStackedOnMobile": true
},
"innerBlocks": [
{
"name": "core/column",
"attributes": {},
"innerBlocks": [
{
"name": "core/image",
"attributes": {
"id": 1701,
"className": "layout-column-1",
"url": "https://d.pr/i/fW6V3V+",
"alt": ""
},
"innerBlocks": null
}
]
},
{
"name": "core/column",
"attributes": {},
"innerBlocks": [
{
"name": "core/paragraph",
"attributes": {
"className": "layout-column-2",
"content": "Phosfluorescently morph intuitive relationships rather than customer directed human capital.",
"dropCap": false
},
"innerBlocks": null
}
]
}
]
},
{
"name": "core/heading",
"attributes": {
"content": "Columns inside Columns (nested inner blocks)",
"level": 2
},
"innerBlocks": null
},
{
"name": "core/columns",
"attributes": {
"isStackedOnMobile": true
},
"innerBlocks": [
{
"name": "core/column",
"attributes": {},
"innerBlocks": [
{
"name": "core/image",
"attributes": {
"id": 1701,
"className": "layout-column-1",
"url": "https://d.pr/i/fW6V3V+",
"alt": ""
},
"innerBlocks": null
},
{
"name": "core/columns",
"attributes": {
"isStackedOnMobile": true
},
"innerBlocks": [
{
"name": "core/column",
"attributes": {
"width": "33.33%"
},
"innerBlocks": [
{
"name": "core/heading",
"attributes": {
"fontSize": "large",
"content": "Life is so rich",
"level": 2
},
"innerBlocks": null
},
{
"name": "core/heading",
"attributes": {
"level": 3,
"content": "Life is so dynamic"
},
"innerBlocks": null
}
]
},
{
"name": "core/column",
"attributes": {
"width": "66.66%"
},
"innerBlocks": [
{
"name": "core/paragraph",
"attributes": {
"content": "This rhyming poem is the spark that can reignite the fires within you. It challenges you to go out and live your life in the present moment as a \u201chero\u201d and leave your mark on this world.",
"dropCap": false
},
"innerBlocks": null
},
{
"name": "core/columns",
"attributes": {
"isStackedOnMobile": true
},
"innerBlocks": [
{
"name": "core/column",
"attributes": {},
"innerBlocks": [
{
"name": "core/image",
"attributes": {
"id": 361,
"sizeSlug": "large",
"linkDestination": "none",
"url": "https://gato-graphql.lndo.site/wp-content/uploads/2022/05/graphql-voyager-public-1024x622.jpg",
"alt": ""
},
"innerBlocks": null
}
]
},
{
"name": "core/column",
"attributes": {},
"innerBlocks": null
},
{
"name": "core/column",
"attributes": {},
"innerBlocks": [
{
"name": "core/image",
"attributes": {
"id": 362,
"sizeSlug": "large",
"linkDestination": "none",
"url": "https://gato-graphql.lndo.site/wp-content/uploads/2022/05/namespaced-interactive-schema-1024x598.webp",
"alt": ""
},
"innerBlocks": null
}
]
}
]
}
]
}
]
}
]
}
]
}
]
}
}
}Skema GraphQL untuk tipe-tipe Block terlihat seperti ini:
interface Block {
name: String!
attributes: JSONObject
innerBlocks: [BlockUnion!]
contentSource: HTML!
}
type GenericBlock implements Block {
name: String!
attributes: JSONObject
innerBlocks: [BlockUnion!]
contentSource: HTML!
}
union BlockUnion = GenericBlockField-field Block
Antarmuka Block (dan, dengan demikian, tipe GeneralBlock) berisi field-field berikut:
namemengambil nama blok:"core/paragraph","core/heading""core/image", dll.attributesmengambil objek JSON yang berisi semua atribut dari blok.innerBlocksmengambil[BlockUnion!], sehingga kita dapat melakukan query terhadapnya untuk menavigasi hierarki blok yang berisi blok-blok dalam (inner blocks), dan mengambil data untuk semua blok tersebut, sebanyak level yang ada dalam konten kita.contentSourcemengambil kode sumber HTML (Gutenberg) dari blok, termasuk pemisah komentar yang berisi atribut. Namun, field ini tidak mengambil data yang persis sama dengan cara penyimpanannya di DB (lihat #2346), jadi gunakan field ini dengan hati-hati.
Mengambil GeneralBlock secara langsung (bukan BlockUnion)
Karena saat ini hanya ada satu tipe Block yang memetakan blok –GeneralBlock– masuk akal untuk membuat CustomPost.blocks (dan juga Block.innerBlocks) mengambil tipe ini secara langsung, bukan tipe BlockUnion.
Kita dapat melakukan ini di halaman Settings pada tab Blocks, dengan mencentang opsi Use single type instead of union type?:
Kemudian, query GraphQL disederhanakan:
{
post(by: { id: 1 }) {
blocks {
name
attributes
innerBlocks {
name
attributes
}
}
}
}Perlu diperhatikan bahwa mempertahankan tipe respons sebagai BlockUnion baik untuk kompatibilitas ke depan: jika kita suatu saat memutuskan untuk menambahkan tipe-tipe spesifik blok ke skema (lihat bagian di bawah), maka tidak akan ada perubahan yang merusak.
Memetakan tipe-tipe spesifik blok
Tipe JSONObject (sebagaimana diambil oleh Block.attributes) tidak diketik secara ketat: properti-propertinya dapat memiliki tipe dan kardinalitas apa pun (String, Int, [Boolean!], dll), sehingga kita perlu mengetahui informasi ini untuk setiap blok dan menangani setiap kasus di sisi klien.
Jika kita memerlukan pengetikan yang ketat, kita harus memperluas skema GraphQL melalui kode PHP, menambahkan tipe-tipe spesifik blok yang memetakan atribut-atribut spesifik suatu blok sebagai field, dan menjadikannya bagian dari BlockUnion.
Misalnya, kita dapat menambahkan tipe CoreParagraphBlock yang memetakan blok core/paragraph, dengan field content bertipe String.
Lihat dokumentasi di GatoGraphQL/GatoGraphQL untuk mempelajari cara memperluas skema GraphQL (saat ini masih dalam pengerjaan).
Memfilter blok
Field CustomPost.blocks berisi argumen filterBy dengan dua properti: include dan exclude. Kita dapat menggunakannya untuk memfilter blok mana yang diambil, berdasarkan nama blok:
{
post(by: { id: 1 }) {
id
blocks(
filterBy: {
include: [
"core/heading",
"core/gallery"
]
}
) {
name
attributes
}
}
}Ini akan menghasilkan:
{
"data": {
"post": {
"blocks": [
{
"name": "core/gallery",
"attributes": {
"linkTo": "none",
"className": "alignnone",
"images": [
{
"url": "https://d.pr/i/zd7Ehu+",
"alt": "",
"id": "1706"
},
{
"url": "https://d.pr/i/jXLtzZ+",
"alt": "",
"id": "1705"
}
],
"ids": [],
"shortCodeTransforms": [],
"imageCrop": true,
"fixedHeight": true,
"sizeSlug": "large",
"allowResize": false
},
"innerBlocks": null
},
{
"name": "core/heading",
"attributes": {
"content": "List Block",
"level": 2
},
"innerBlocks": null
},
{
"name": "core/heading",
"attributes": {
"className": "has-top-margin",
"content": "Columns Block",
"level": 2
},
"innerBlocks": null
},
{
"name": "core/heading",
"attributes": {
"content": "Columns inside Columns (nested inner blocks)",
"level": 2
},
"innerBlocks": null
}
]
}
}
}Perlu diperhatikan bahwa tidak semua blok bertipe core/heading telah disertakan: blok-blok yang bersarang di bawah core/column telah dikecualikan, karena tidak ada cara untuk mencapai mereka (karena blok core/columns dan core/column sendiri dikecualikan).
Ketidaknyamanan field blocks
Field blocks menimbulkan ketidaknyamanan bahwa, untuk mengambil seluruh data blok yang terdapat dalam custom post, termasuk data untuk blok-blok dalam, dan blok-blok dalam mereka sendiri, dan seterusnya, kita harus mengetahui berapa banyak level blok bersarang yang ada dalam konten, dan mencerminkan informasi ini dalam query GraphQL.
Atau, jika kita tidak tahu, kita harus menyusun query dengan cukup banyak level agar yakin bahwa semua data akan diambil.
Misalnya, query ini mengambil hingga 7 level penyarangan blok dalam:
{
post(by: { id: 1 }) {
blocks {
...BlockData
}
}
}
fragment BlockData on Block {
name
attributes
innerBlocks {
...on Block {
name
attributes
innerBlocks {
...on Block {
name
attributes
innerBlocks {
...on Block {
name
attributes
innerBlocks {
...on Block {
name
attributes
innerBlocks {
...on Block {
name
attributes
innerBlocks {
...on Block {
name
attributes
innerBlocks {
...on Block {
name
attributes
}
}
}
}
}
}
}
}
}
}
}
}
}
}
}blockDataItems
Untuk menghindari ketidaknyamanan cara field blocks mengambil semua data (termasuk untuk blok-blok dalamnya, dan blok-blok dalam mereka, dan seterusnya), maka ada field CustomPost.blockDataItems.
Field ini, alih-alih mengembalikan [BlockUnion], mengembalikan [JSONObject!]:
type CustomPost {
blockDataItems: [JSONObject!]
}Dengan kata lain, alih-alih mengikuti cara GraphQL yang umum di mana entitas berhubungan dengan entitas dan menavigasi antar keduanya, setiap entitas Block di tingkat teratas sudah menghasilkan seluruh data blok untuk dirinya sendiri dan semua turunannya, dalam satu hasil JSONObject.
Objek JSON berisi properti-properti untuk blok (di bawah entri name dan attributes) dan untuk blok-blok dalamnya (di bawah entri innerBlocks), secara rekursif.
Misalnya, query berikut:
{
post(by: { id: 1 }) {
blockDataItems
}
}...akan menghasilkan:
{
"data": {
"post": {
"blockDataItems": [
{
"name": "core/gallery",
"attributes": {
"linkTo": "none",
"className": "alignnone",
"images": [
{
"url": "https://d.pr/i/zd7Ehu+",
"alt": "",
"id": "1706"
},
{
"url": "https://d.pr/i/jXLtzZ+",
"alt": "",
"id": "1705"
}
],
"ids": [],
"shortCodeTransforms": [],
"imageCrop": true,
"fixedHeight": true,
"sizeSlug": "large",
"allowResize": false
}
},
{
"name": "core/heading",
"attributes": {
"content": "List Block",
"level": 2
}
},
{
"name": "core/list",
"attributes": {
"ordered": false,
"values": "<li>List item 1</li><li>List item 2</li><li>List item 3</li><li>List item 4</li>"
}
},
{
"name": "core/heading",
"attributes": {
"className": "has-top-margin",
"content": "Columns Block",
"level": 2
}
},
{
"name": "core/columns",
"attributes": {
"isStackedOnMobile": true
},
"innerBlocks": [
{
"name": "core/column",
"attributes": {},
"innerBlocks": [
{
"name": "core/image",
"attributes": {
"id": 1701,
"className": "layout-column-1",
"url": "https://d.pr/i/fW6V3V+",
"alt": ""
}
}
]
},
{
"name": "core/column",
"attributes": {},
"innerBlocks": [
{
"name": "core/paragraph",
"attributes": {
"className": "layout-column-2",
"content": "Phosfluorescently morph intuitive relationships rather than customer directed human capital.",
"dropCap": false
}
}
]
}
]
},
{
"name": "core/heading",
"attributes": {
"content": "Columns inside Columns (nested inner blocks)",
"level": 2
}
},
{
"name": "core/columns",
"attributes": {
"isStackedOnMobile": true
},
"innerBlocks": [
{
"name": "core/column",
"attributes": {},
"innerBlocks": [
{
"name": "core/image",
"attributes": {
"id": 1701,
"className": "layout-column-1",
"url": "https://d.pr/i/fW6V3V+",
"alt": ""
}
},
{
"name": "core/columns",
"attributes": {
"isStackedOnMobile": true
},
"innerBlocks": [
{
"name": "core/column",
"attributes": {
"width": "33.33%"
},
"innerBlocks": [
{
"name": "core/heading",
"attributes": {
"fontSize": "large",
"content": "Life is so rich",
"level": 2
}
},
{
"name": "core/heading",
"attributes": {
"level": 3,
"content": "Life is so dynamic"
}
}
]
},
{
"name": "core/column",
"attributes": {
"width": "66.66%"
},
"innerBlocks": [
{
"name": "core/paragraph",
"attributes": {
"content": "This rhyming poem is the spark that can reignite the fires within you. It challenges you to go out and live your life in the present moment as a \u201chero\u201d and leave your mark on this world.",
"dropCap": false
}
},
{
"name": "core/columns",
"attributes": {
"isStackedOnMobile": true
},
"innerBlocks": [
{
"name": "core/column",
"attributes": {},
"innerBlocks": [
{
"name": "core/image",
"attributes": {
"id": 361,
"sizeSlug": "large",
"linkDestination": "none",
"url": "https://gato-graphql.lndo.site/wp-content/uploads/2022/05/graphql-voyager-public-1024x622.jpg",
"alt": ""
}
}
]
},
{
"name": "core/column",
"attributes": {}
},
{
"name": "core/column",
"attributes": {},
"innerBlocks": [
{
"name": "core/image",
"attributes": {
"id": 362,
"sizeSlug": "large",
"linkDestination": "none",
"url": "https://gato-graphql.lndo.site/wp-content/uploads/2022/05/namespaced-interactive-schema-1024x598.webp",
"alt": ""
}
}
]
}
]
}
]
}
]
}
]
}
]
}
]
}
}
}Memfilter elemen data blok
Serupa dengan blocks, blockDataItems juga memungkinkan pemfilteran blok yang diambil, melalui argumen filterBy.
Query ini:
{
post(by: { id: 1 }) {
id
blockDataItems(
filterBy: {
include: [
"core/heading"
]
}
)
}
}...akan menghasilkan:
{
"data": {
"post": {
"blockDataItems": [
{
"name": "core/heading",
"attributes": {
"content": "List Block",
"level": 2
},
"innerBlocks": null
},
{
"name": "core/heading",
"attributes": {
"className": "has-top-margin",
"content": "Columns Block",
"level": 2
},
"innerBlocks": null
},
{
"name": "core/heading",
"attributes": {
"content": "Columns inside Columns (nested inner blocks)",
"level": 2
},
"innerBlocks": null
}
]
}
}
}Perlu diperhatikan bahwa, serupa dengan blocks, tidak semua blok bertipe core/heading telah disertakan: blok-blok yang bersarang di bawah core/column telah dikecualikan, karena tidak ada cara untuk mencapai mereka (karena blok core/columns dan core/column sendiri dikecualikan).
blockFlattenedDataItems
Kedua field blocks dan blockDataItems memungkinkan pemfilteran blok yang diambil (melalui argumen filterBy). Dalam kedua kasus, jika sebuah blok memenuhi kondisi penyertaan, tetapi bersarang di dalam blok yang tidak memenuhinya, maka blok tersebut akan dikecualikan.
Namun ada kalanya kita perlu mengambil semua blok dari jenis tertentu dari custom post, terlepas dari di mana blok-blok tersebut berada dalam hierarki. Misalnya, kita mungkin ingin menyertakan semua blok bertipe core/image, untuk mengambil semua gambar yang ada dalam sebuah posting blog.
Untuk memenuhi kebutuhan ini, ada field CustomPost.blockFlattenedDataItems. Tidak seperti field blocks dan blockDataItems, field ini meratakan hierarki blok menjadi satu level tunggal.
Query ini:
{
post(by: { id: 1 }) {
blockFlattenedDataItems
}
}...akan menghasilkan:
{
"data": {
"post": {
"blockFlattenedDataItems": [
{
"name": "core/gallery",
"attributes": {
"linkTo": "none",
"className": "alignnone",
"images": [
{
"url": "https://d.pr/i/zd7Ehu+",
"alt": "",
"id": "1706"
},
{
"url": "https://d.pr/i/jXLtzZ+",
"alt": "",
"id": "1705"
}
],
"ids": [],
"shortCodeTransforms": [],
"imageCrop": true,
"fixedHeight": true,
"sizeSlug": "large",
"allowResize": false
},
"innerBlockPositions": null,
"parentBlockPosition": null
},
{
"name": "core/heading",
"attributes": {
"content": "List Block",
"level": 2
},
"innerBlockPositions": null,
"parentBlockPosition": null
},
{
"name": "core/list",
"attributes": {
"ordered": false,
"values": "<li>List item 1</li><li>List item 2</li><li>List item 3</li><li>List item 4</li>"
},
"innerBlockPositions": null,
"parentBlockPosition": null
},
{
"name": "core/heading",
"attributes": {
"className": "has-top-margin",
"content": "Columns Block",
"level": 2
},
"innerBlockPositions": null,
"parentBlockPosition": null
},
{
"name": "core/columns",
"attributes": {
"isStackedOnMobile": true
},
"innerBlockPositions": [
5,
7
],
"parentBlockPosition": null
},
{
"name": "core/column",
"attributes": {},
"parentBlockPosition": 4,
"innerBlockPositions": [
6
]
},
{
"name": "core/image",
"attributes": {
"id": 1701,
"className": "layout-column-1",
"url": "https://d.pr/i/fW6V3V+",
"alt": ""
},
"parentBlockPosition": 5,
"innerBlockPositions": null
},
{
"name": "core/column",
"attributes": {},
"parentBlockPosition": 4,
"innerBlockPositions": [
8
]
},
{
"name": "core/paragraph",
"attributes": {
"className": "layout-column-2",
"content": "Phosfluorescently morph intuitive relationships rather than customer directed human capital.",
"dropCap": false
},
"parentBlockPosition": 7,
"innerBlockPositions": null
},
{
"name": "core/heading",
"attributes": {
"content": "Columns inside Columns (nested inner blocks)",
"level": 2
},
"innerBlockPositions": null,
"parentBlockPosition": null
},
{
"name": "core/columns",
"attributes": {
"isStackedOnMobile": true
},
"innerBlockPositions": [
11
],
"parentBlockPosition": null
},
{
"name": "core/column",
"attributes": {},
"parentBlockPosition": 10,
"innerBlockPositions": [
12,
13
]
},
{
"name": "core/image",
"attributes": {
"id": 1701,
"className": "layout-column-1",
"url": "https://d.pr/i/fW6V3V+",
"alt": ""
},
"parentBlockPosition": 11,
"innerBlockPositions": null
},
{
"name": "core/columns",
"attributes": {
"isStackedOnMobile": true
},
"parentBlockPosition": 11,
"innerBlockPositions": [
14,
17
]
},
{
"name": "core/column",
"attributes": {
"width": "33.33%"
},
"parentBlockPosition": 13,
"innerBlockPositions": [
15,
16
]
},
{
"name": "core/heading",
"attributes": {
"fontSize": "large",
"content": "Life is so rich",
"level": 2
},
"parentBlockPosition": 14,
"innerBlockPositions": null
},
{
"name": "core/heading",
"attributes": {
"level": 3,
"content": "Life is so dynamic"
},
"parentBlockPosition": 14,
"innerBlockPositions": null
},
{
"name": "core/column",
"attributes": {
"width": "66.66%"
},
"parentBlockPosition": 13,
"innerBlockPositions": [
18,
19
]
},
{
"name": "core/paragraph",
"attributes": {
"content": "This rhyming poem is the spark that can reignite the fires within you. It challenges you to go out and live your life in the present moment as a \u201chero\u201d and leave your mark on this world.",
"dropCap": false
},
"parentBlockPosition": 17,
"innerBlockPositions": null
},
{
"name": "core/columns",
"attributes": {
"isStackedOnMobile": true
},
"parentBlockPosition": 17,
"innerBlockPositions": [
20,
22,
23
]
},
{
"name": "core/column",
"attributes": {},
"parentBlockPosition": 19,
"innerBlockPositions": [
21
]
},
{
"name": "core/image",
"attributes": {
"id": 361,
"sizeSlug": "large",
"linkDestination": "none",
"url": "https://gato-graphql.lndo.site/wp-content/uploads/2022/05/graphql-voyager-public-1024x622.jpg",
"alt": ""
},
"parentBlockPosition": 20,
"innerBlockPositions": null
},
{
"name": "core/column",
"attributes": {},
"parentBlockPosition": 19,
"innerBlockPositions": null
},
{
"name": "core/column",
"attributes": {},
"parentBlockPosition": 19,
"innerBlockPositions": [
24
]
},
{
"name": "core/image",
"attributes": {
"id": 362,
"sizeSlug": "large",
"linkDestination": "none",
"url": "https://gato-graphql.lndo.site/wp-content/uploads/2022/05/namespaced-interactive-schema-1024x598.webp",
"alt": ""
},
"parentBlockPosition": 23,
"innerBlockPositions": null
}
]
}
}
}Perhatikan bagaimana atribut innerBlocks telah menghilang, karena blok-blok tidak lagi bersarang. Sebagai gantinya, respons menyertakan dua atribut lain (yang memungkinkan kita untuk membangun kembali hierarki blok):
parentBlockPosition: Posisi blok induk dari blok tersebut dalam array yang dikembalikan, ataunulljika blok tersebut adalah blok tingkat teratasinnerBlockPositions: Sebuah array yang berisi posisi-posisi blok dalam dari blok tersebut dalam array yang dikembalikan
Memfilter elemen data blok yang telah diratakan
Sekarang setelah hierarki blok diratakan, pemfilteran berdasarkan core/heading akan menghasilkan semua blok tersebut (bahkan jika ada yang pada awalnya bersarang di bawah blok yang telah dikecualikan).
Query ini:
{
post(by: { id: 1 }) {
id
blockFlattenedDataItems(
filterBy: {
include: [
"core/heading"
]
}
)
}
}...akan menghasilkan:
{
"data": {
"post": {
"blockFlattenedDataItems": [
{
"name": "core/heading",
"attributes": {
"content": "List Block",
"level": 2
}
},
{
"name": "core/heading",
"attributes": {
"className": "has-top-margin",
"content": "Columns Block",
"level": 2
}
},
{
"name": "core/heading",
"attributes": {
"content": "Columns inside Columns (nested inner blocks)",
"level": 2
}
},
{
"name": "core/heading",
"attributes": {
"fontSize": "large",
"content": "Life is so rich",
"level": 2
}
},
{
"name": "core/heading",
"attributes": {
"level": 3,
"content": "Life is so dynamic"
}
}
]
}
}
}Perlu diperhatikan bahwa dua atribut tambahan, parentBlockPosition dan innerBlockPositions, dihapus saat memfilter, karena keduanya tidak lagi bermakna.