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

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

Τα προσαρμοσμένα πεδία σάς επιτρέπουν να ορίζετε επαναχρησιμοποιήσιμες ομάδες πεδίων που μπορούν να χρησιμοποιηθούν σε πολλά μπλοκ. Σκεφτείτε τα ως πρότυπα πεδίων: ορίστε τα μία φορά και χρησιμοποιήστε τα παντού.

Τα προσαρμοσμένα πεδία δεν είναι το ίδιο με τους προσαρμοσμένους τύπους πεδίων. Χρησιμοποιήστε το custom/{name} για επαναχρησιμοποιήσιμες ομάδες υπαρχόντων πεδίων. Χρησιμοποιήστε έναν προσαρμοσμένο τύπο πεδίου με χώρο ονομάτων, όπως το acme/dimensions, όταν ένα θέμα ή πρόσθετο καταχωρίζει ένα νέο στοιχείο ελέγχου επεξεργαστή και μορφή τιμής.

Καταχώριση συστήματος αρχείων

Δημιουργήστε ένα αρχείο field.json μέσα σε έναν κατάλογο fields/ στον κατάλογο blockstudio:

Κώδικας
theme/
└── blockstudio/
    └── fields/
        └── hero/
            └── field.json
JSON
{
  "$schema": "https://blockstudio.dev/schema/field",
  "name": "hero",
  "title": "Hero Section",
  "attributes": [
    {
      "id": "heading",
      "type": "text",
      "label": "Heading",
      "default": "Hello World"
    },
    { "id": "description", "type": "textarea", "label": "Description" },
    { "id": "enabled", "type": "toggle", "label": "Enabled" }
  ]
}

Καταχώριση φίλτρου PHP

Καταχωρίστε προσαρμοσμένα πεδία μέσω προγραμματισμού χρησιμοποιώντας το φίλτρο blockstudio/fields:

PHP
add_filter('blockstudio/fields', function ($fields) {
    $fields['cta'] = [
        'title'      => 'Call to Action',
        'attributes' => [
            ['id' => 'text', 'type' => 'text', 'label' => 'Button Text'],
            ['id' => 'url', 'type' => 'text', 'label' => 'URL'],
        ],
    ];
    return $fields;
});

Χρήση στο block.json

Αναφερθείτε σε ένα προσαρμοσμένο πεδίο χρησιμοποιώντας τον τύπο custom/{name}:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero" }]
  }
}

Αυτό αναπτύσσεται ενσωματωμένα στα πεδία που ορίζονται στον ορισμό του προσαρμοσμένου πεδίου. Τα πεδία που αναπτύσσονται χρησιμοποιούν τα αρχικά τους ID (heading, description, enabled).

Τα προσαρμοσμένα πεδία μπορούν επίσης να επαναχρησιμοποιούν πλήρεις ορισμούς ομάδων:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "title": "Header",
      "attributes": [
        { "id": "kicker", "type": "text", "label": "Kicker" },
        { "id": "title", "type": "text", "label": "Title" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/section-header" }]
  }
}

Τα θυγατρικά στοιχεία της ομάδας αποθηκεύονται ως section-header_kicker, section-header_title κ.ο.κ. Στα πρότυπα, χρησιμοποιήστε το bs_get_group() για να τα εξαγάγετε σε ένα καθαρό αντικείμενο ομάδας.

Δομή ID

Χρησιμοποιήστε το idStructure για να προσθέσετε πρόθεμα ή να μετασχηματίσετε τα ID πεδίων. Το σύμβολο κράτησης θέσης {id} αντικαθίσταται από το αρχικό ID πεδίου:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
  }
}

Έτσι δημιουργούνται πεδία με ID: hero_heading, hero_description, hero_enabled.

Παρακάμψεις

Προσαρμόστε μεμονωμένα πεδία ανά στιγμιότυπο χρησιμοποιώντας το overrides. Τα κλειδιά είναι τα αρχικά ID πεδίων από τον ορισμό:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "custom/hero",
        "idStructure": "hero_{id}",
        "overrides": {
          "heading": { "default": "Welcome", "label": "Title" },
          "enabled": { "id": "active" }
        }
      }
    ]
  }
}

Οι ιδιότητες παράκαμψης συγχωνεύονται με τον αρχικό ορισμό πεδίου. Μια παράκαμψη id παρακάμπτει το μοτίβο idStructure. Στο παραπάνω παράδειγμα, το enabled γίνεται active αντί για hero_enabled.

Η συγχώνευση γίνεται μόνο σε ένα επίπεδο: μια ιδιότητα που παρακάμπτετε αντικαθιστά ολόκληρη την αρχική ιδιότητα. Μια παράκαμψη options είναι η πλήρης λίστα επιλογών, όχι προσθήκη σε αυτή, και το ίδιο ισχύει για το conditions και για το attributes μιας ομάδας. Οι συνθήκες της αναφοράς προστίθενται στη συνέχεια.

JSON
{
  "type": "custom/background",
  "overrides": {
    "background": {
      "options": [
        { "value": "white", "label": "White" },
        { "value": "grey", "label": "Grey" }
      ]
    }
  }
}

Αυτό το μπλοκ προσφέρει μόνο Λευκό και Γκρι, ανεξάρτητα από το πόσες επιλογές παραθέτει ο ορισμός.

Συνθήκες

Οι συνθήκες μέσα στους ορισμούς προσαρμοσμένων πεδίων επανεγγράφονται αυτόματα όταν εφαρμόζεται το idStructure. Ένα πεδίο που εξαρτάται υπό συνθήκη από ένα αδελφό πεδίο εξακολουθεί να λειτουργεί μετά την ανάπτυξη.

JSON
{
  "name": "font-size",
  "attributes": [
    { "id": "enable", "type": "toggle", "label": "Modify font size" },
    {
      "id": "min",
      "type": "number",
      "label": "Min Size",
      "conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
    },
    {
      "id": "max",
      "type": "number",
      "label": "Max Size",
      "conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
    }
  ]
}
JSON
{ "type": "custom/font-size", "idStructure": "title_font_{id}" }

Το Blockstudio το αναπτύσσει σε title_font_enable, title_font_min, title_font_max και επανεγγράφει τις συνθήκες ώστε να αναφέρονται στο title_font_enable αντί για το enable. Τα στοιχεία ελέγχου εναλλαγής λειτουργούν ακριβώς όπως αν τα πεδία είχαν οριστεί ενσωματωμένα.

Συνθήκες επιπέδου αναφοράς

Προσθέστε το conditions στην αναφορά για να εφαρμοστούν σε κάθε πεδίο που αναπτύσσεται. Αυτό είναι χρήσιμο για την απόκρυψη ολόκληρης ομάδας πίσω από μια εξωτερική εναλλαγή:

JSON
{
  "type": "custom/font-size",
  "idStructure": "subtitle_font_{id}",
  "conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}

Αυτές οι συνθήκες συγχωνεύονται με όσες έχουν ήδη οριστεί μέσα στον ορισμό πεδίου. Τα ID των συνθηκών επανεγγράφονται επίσης μέσω του idStructure.

Πολλαπλά προσαρμοσμένα πεδία

Μπορείτε να χρησιμοποιήσετε πολλά προσαρμοσμένα πεδία σε ένα μπλοκ, μαζί με κανονικά πεδία:

JSON
{
  "blockstudio": {
    "attributes": [
      { "id": "intro", "type": "text", "label": "Intro" },
      { "type": "custom/hero", "idStructure": "hero_{id}" },
      { "type": "custom/cta", "idStructure": "cta_{id}" }
    ]
  }
}

Ένθεση

Τα προσαρμοσμένα πεδία λειτουργούν μέσα σε ομάδες, καρτέλες και επαναλήπτες:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "group",
        "id": "content",
        "title": "Content",
        "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
      }
    ]
  }
}

Πρόσθετες διαδρομές ανακάλυψης

Χρησιμοποιήστε το φίλτρο blockstudio/fields/paths για να προσθέσετε επιπλέον καταλόγους για την ανακάλυψη πεδίων:

PHP
add_filter('blockstudio/fields/paths', function ($paths) {
    $paths[] = get_stylesheet_directory() . '/blockstudio/fields';
    return $paths;
});

Στατική ανάλυση

Το πακέτο blockstudio/phpstan αναπτύσσει αναφορές custom/* που βασίζονται σε αρχεία κατά την επικύρωση των PHP, Twig, Blade, των ετικετών μπλοκ και των συναγόμενων σχημάτων χαρακτηριστικών. Η ανάπτυξή του ακολουθεί τους ίδιους κανόνες ένθεσης, idStructure και overrides που περιγράφονται παραπάνω.

Για ορισμούς εκτός του έργου που αναλύεται, προσθέστε τον κατάλογο της βιβλιοθήκης στο blockstudioScanRoots στο phpstan.neon. Τα πεδία που καταχωρίζονται μόνο μέσω του φίλτρου blockstudio/fields PHP υπάρχουν κατά την εκτέλεση και δεν μπορούν να συναχθούν στατικά.