Μετάβαση στο περιεχόμενο

Συμπλήρωση επιλογών

Αντί να παρέχετε διαφορετικούς τύπους πεδίων, όπως Αναρτήσεις, Χρήστες ή Όρους, το Blockstudio προσφέρει έναν ευέλικτο τρόπο συμπλήρωσης δεδομένων απευθείας από το block.json. Αυτή η δυνατότητα λειτουργεί με τους τύπους πεδίων select, radio, checkbox, color και gradient.

Υπάρχουν τέσσερις τρόποι συμπλήρωσης δεδομένων:

  • Ερώτημα – Επιστρέφει αποτελέσματα από ερώτημα αναρτήσεων, χρηστών ή όρων
  • Ανάκτηση – Επιστρέφει αποτελέσματα από εξωτερική πηγή
  • Συνάρτηση – Επιστρέφει αποτελέσματα από προσαρμοσμένη συνάρτηση
  • Προσαρμοσμένα δεδομένα – Επιστρέφει αποτελέσματα από προσαρμοσμένο σύνολο δεδομένων

Ερώτημα

Όταν επιλέγετε τη λειτουργία ερωτήματος, μπορούν να συμπληρωθούν Αναρτήσεις, Χρήστες ή Όροι.

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/native",
  "title": "Native Block",
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts"
        }
      }
    ]
  }
}

Οι διαθέσιμοι τύποι ερωτημάτων χρησιμοποιούν εσωτερικά αυτές τις συναρτήσεις WordPress:

Ερώτημα Συνάρτηση
posts get_posts
users get_users
terms get_terms

Ορίσματα

Μπορείτε να περάσετε προσαρμοσμένα ορίσματα μέσω του χαρακτηριστικού arguments:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "jobs",
            "numberposts": "20"
          }
        }
      }
    ]
  }
}

Μορφή επιστροφής

Από προεπιλογή, το Blockstudio επιστρέφει:

Ερώτημα Τιμή Ετικέτα
posts αντικείμενο ανάρτησης post_title
users αντικείμενο χρήστη display_name
terms αντικείμενο όρου name

Προσαρμόστε την απόκριση με το returnFormat:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "posts",
            "numberposts": "20"
          },
          "returnFormat": {
            "value": "id",
            "label": "post_name"
          }
        }
      }
    ]
  }
}

Λειτουργία ανάκτησης

Ενεργοποιήστε τη δυναμική αναζήτηση με την επιλογή fetch:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "fetch": true,
          "arguments": {
            "post_type": "posts",
            "numberposts": "20"
          }
        }
      }
    ]
  }
}

Αυτό ενεργοποιεί το stylisedUi και ανακτά αρχικά τις πρώτες 20 αναρτήσεις. Η πληκτρολόγηση στο πεδίο επιλογής αναζητά αναρτήσεις χρησιμοποιώντας το όρισμα s.

Συνάρτηση

Χρησιμοποιήστε μια προσαρμοσμένη συνάρτηση για να συμπληρώσετε επιλογές:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types"
        }
      }
    ]
  }
}

Ορίσματα

Περάστε τα ορίσματα ως πίνακα (χρησιμοποιεί εσωτερικά το call_user_func_array):

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types",
          "arguments": [[], "objects"]
        }
      }
    ]
  }
}

Μορφή επιστροφής

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types",
          "arguments": [[], "objects"],
          "returnFormat": {
            "value": "name",
            "label": "label"
          }
        }
      }
    ]
  }
}

Συνδυασμός επιλογών

Συνδυάστε στατικές επιλογές με δεδομένα που συμπληρώνονται δυναμικά:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "users",
        "type": "radio",
        "label": "Users",
        "options": [
          {
            "value": "administrators",
            "label": "Administrators"
          },
          {
            "value": "editors",
            "label": "Editors"
          }
        ],
        "populate": {
          "type": "query",
          "query": "users",
          "position": "before"
        }
      }
    ]
  }
}

Η επιλογή position (before ή after) καθορίζει τη θέση των συμπληρωμένων επιλογών σε σχέση με τις στατικές.

Προειδοποίηση

Δεν υποστηρίζεται ο συνδυασμός επιλογών και συμπληρωμένων δεδομένων στη λειτουργία ανάκτησης.

Προσαρμοσμένα δεδομένα

Δημιουργήστε επαναχρησιμοποιήσιμα σύνολα δεδομένων με το φίλτρο blockstudio/blocks/attributes/populate. Το φίλτρο λαμβάνει ένα όρισμα, έναν πίνακα όλων των προσαρμοσμένων συνόλων δεδομένων με κλειδιά τα ονόματά τους. Προσθέστε το σύνολο δεδομένων σας με ένα κλειδί και επιστρέψτε τον πίνακα:

PHP
add_filter('blockstudio/blocks/attributes/populate', function($options) {
  $options['customData'] = [
    ['value' => '1', 'label' => 'Option 1'],
    ['value' => '2', 'label' => 'Option 2'],
  ];
  return $options;
});

Έπειτα αναφερθείτε στο κλειδί στο block σας:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "custom",
          "custom": "customData"
        }
      }
    ]
  }
}

Εξωτερικά δεδομένα

Ανακτήστε δεδομένα από εξωτερική πηγή:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "select",
        "type": "select",
        "label": "Select",
        "multiple": true,
        "populate": {
          "type": "fetch",
          "arguments": {
            "urlSearch": "https://example.com/wp-json/wp/v2/posts?search="
          },
          "returnFormat": {
            "value": "id",
            "label": "title.rendered"
          }
        }
      }
    ]
  }
}

Ο όρος αναζήτησης προστίθεται στο urlSearch.

Δυναμικά ορίσματα

Τα ορίσματα συμπλήρωσης μπορούν να αναφέρονται σε άλλα χαρακτηριστικά block χρησιμοποιώντας τη σύνταξη {attributes.*}. Όταν αλλάζει το χαρακτηριστικό στο οποίο γίνεται αναφορά, το πεδίο ανακτά ξανά αυτόματα τις επιλογές του.

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "post_type",
        "type": "select",
        "label": "Post Type",
        "options": [
          { "label": "Pages", "value": "page" },
          { "label": "Posts", "value": "post" }
        ]
      },
      {
        "id": "selected_post",
        "type": "select",
        "label": "Select Post",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "{attributes.post_type.value}",
            "numberposts": 10
          }
        }
      }
    ]
  }
}

Αυτό λειτουργεί με όλους τους τύπους συμπλήρωσης (query, function, custom). Κάθε τιμή στη διαμόρφωση συμπλήρωσης που περιέχει {attributes.*} επιλύεται στην πλευρά του πελάτη με την τρέχουσα τιμή του χαρακτηριστικού, πριν εκτελεστεί το ερώτημα.

Οι αναφορές χρησιμοποιούν τις αποθηκευμένες τιμές του επεξεργαστή. Για μια επιλογή επιλογέα, χρησιμοποιήστε το {attributes.post_type.value} για την τιμή της ή το {attributes.post_type.label} για την ετικέτα της· το returnFormat ελέγχει την τιμή προτύπου, όχι αυτήν την αποθηκευμένη μορφή του επεξεργαστή.

Τα ένθετα ορίσματα επιλύονται χωρίς να σειριοποιούνται σε συμβολοσειρά προτύπου. Ένα όρισμα που αποτελείται από ένα μόνο σύμβολο κράτησης θέσης διατηρεί τον τύπο της αναφοράς του, συμπεριλαμβανομένων αριθμών, λογικών τιμών, πινάκων και αντικειμένων. Ένα σύμβολο κράτησης θέσης ενσωματωμένο σε άλλο κείμενο παράγει συμβολοσειρά. Οι αναφορές που λείπουν παραμένουν αμετάβλητες και οι τιμές σε εισαγωγικά ή σε πολλές γραμμές αποστέλλονται ακέραιες. Οι συναρτήσεις επανάκλησης διατηρούν τις λίστες ορισμάτων τους κατά θέση. Ο επεξεργαστής προσθέτει ορίσματα αναζήτησης WordPress μόνο στα query populate και όχι στις κλήσεις συναρτήσεων.

Απόδοση εξαρτημένων επιλογών

Οι εξαρτημένες επιλογές δεν φορτώνονται κατά την καταχώριση του block, επειδή κάθε παρουσία block μπορεί να έχει διαφορετικά ορίσματα. Η απόδοση χρησιμοποιεί την αποθηκευμένη επιλογή αντί να την απορρίπτει επειδή η λίστα επιλογών είναι κενή. Η συνάρτηση επανάκλησης populate δεν εκτελείται ξανά στο frontend.

Το returnFormat του πεδίου εξακολουθεί να ισχύει:

returnFormat Μονή επιλογή Πολλαπλές επιλογές
value (προεπιλογή) Η αποθηκευμένη τιμή, για παράδειγμα "a" Ένας πίνακας αποθηκευμένων τιμών, για παράδειγμα ["a", "b"]
label Η αποθηκευμένη ετικέτα Ένας πίνακας αποθηκευμένων ετικετών
both Η αποθηκευμένη επιλογή {value, label} Ένας πίνακας αποθηκευμένων επιλογών

Για επιλογές που συμπληρώνονται από ερώτημα, οι τιμές εξακολουθούν να αντιστοιχίζονται στο αντίστοιχο αντικείμενο ανάρτησης, χρήστη ή όρου WordPress, εκτός αν το populate.returnFormat.value είναι "id". Οι ετικέτες προέρχονται από την αποθηκευμένη επιλογή. Αν μια εισαγόμενη επιλογή δεν έχει ετικέτα, ως ετικέτα χρησιμοποιείται η τιμή της. Μια αντίστοιχη στατική επιλογή που έχει δηλωθεί στο options υπερισχύει της αποθηκευμένης επιλογής, οπότε εφαρμόζεται η τρέχουσα ετικέτα της.

Οι κενές επιλογές παραμένουν false (ή παίρνουν το ρυθμισμένο για το πεδίο fallback). Αυτό δεν αλλάζει την επικύρωση των συνηθισμένων στατικών επιλογών: μια αποθηκευμένη τιμή που δεν υπάρχει πλέον σε μια λίστα στατικών επιλογών εξακολουθεί να επιστρέφει false.

Οι δυναμικές λίστες επιλογών διατηρούν επίσης τις επιλογές default και fallback όσο οι επιλογές τους παραμένουν σε αναμονή. Χρησιμοποιήστε μια βαθμωτή τιμή, μια επιλογή {value, label} ή έναν πίνακα από τιμές ή επιλογές για λίστα πολλαπλών επιλογών. Για μια βαθμωτή τιμή χρησιμοποιείται ως ετικέτα η ίδια η τιμή, εκτός αν αντιστοιχεί σε δηλωμένη στατική επιλογή. Ένα αντικείμενο επιλογής διατηρεί την ετικέτα που του δόθηκε· μια αντίστοιχη στατική επιλογή υπερισχύει. Δεν εκτελείται κανένα callback συμπλήρωσης στον διακομιστή για την αναζήτηση αυτών των προεπιλεγμένων τιμών.