
# Atributų atvaizdavimas

Šablonų failuose visus atributus galima pasiekti naudojant kintamuosius `$attributes` arba `$a` ir atitinkamą lauko ID.


## PHP

```php title="index.php"
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
```

## Twig

```twig title="index.twig"
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
```

## Atributų įrašymas programiškai

Redaktorius įdeda išsaugotas reikšmes į `blockstudio.attributes`. Bet koks įrašymas į bloką už redaktoriaus ribų, pavyzdžiui, per REST API, WP-CLI, turinio perkėlimą arba MCP serverį, aptinka bloką pagal atributus, kuriuos Blockstudio užregistruoja `WP_Block_Type`, ir įrašo juos aukščiausiame lygyje. Abu formatai atvaizduojami:

```php
// Top level, as a programmatic writer produces it.
echo do_blocks( '<!-- wp:acme/hero {"visual_type":"media"} /-->' );

// Nested, as the editor saves it.
echo do_blocks( '<!-- wp:acme/hero {"blockstudio":{"attributes":{"visual_type":"media"}}} /-->' );
```

Nuskaitomi tik bloko deklaruoti ID iš aukščiausio lygio, todėl paties WordPress atributai, tokie kaip `anchor`, `className`, `lock`, `metadata` ir `style`, niekada nepriimami kaip laukų reikšmės. Jei tas pats ID yra abiejose vietose, naudojama įdėta reikšmė.

## Programinis atributų nuskaitymas

Šablone nevykdomam kodui, pavyzdžiui, struktūriniams duomenims svetainėje `save_post`,
eksportavimui, paieškos indeksavimui arba `render_block` filtrui, dažnai reikia išsaugotų bloko
reikšmių taip, kaip jas mato šablonas. `bs_block_values()` grąžina jas
neatvaizduodama bloko. Iškvieskite ją užregistravę bloką (`init` arba
vėliau), pateikę visą `attrs` masyvą iš `parse_blocks()`:

```php
foreach (parse_blocks($post->post_content) as $block) {
  if ($block['blockName'] === null) {
    continue;
  }

  $a = bs_block_values($block['blockName'], $block['attrs']);

  if ($a === null) {
    // Not a Blockstudio block, and no extension applies.
    continue;
  }

  echo esc_html($a['title'] ?? '');
}
```

Rezultatas yra šablono `$a` masyvas, kurio raktai yra laukų ID:

- Taikomos numatytosios laukų reikšmės, o kartotuvas su `min` turi pradines eilutes.
- Aukščiausio lygio reikšmės sujungiamos su `blockstudio.attributes`, o įdėtinė reikšmė turi pirmenybę. Iš aukščiausio lygio reikšmių nuskaitomi tik deklaruoti ID, o WordPress atmeta aukščiausio lygio reikšmę, jei ji neatitinka užregistruoto lauko tipo, pavyzdžiui, pasirinkimo eilutę, lygiai taip pat kaip atvaizduojant.
- Įtraukiami atitinkančių [plėtinių](https://blockstudio.dev/lt/docs/extensions/) laukai kartu su numatytosiomis reikšmėmis. Pagrindinio arba trečiosios šalies bloko plėtinys nuskaito tik `blockstudio.attributes`, kaip ir atvaizduojant.
- Taikomi grąžinimo formatai, todėl pasirinkimo laukas su `returnFormat`, kurio reikšmė yra `label`, pateikia etiketę, o failų laukas – priedo duomenis.
- Išjungti ir tušti laukai šablone pateikiami kaip `false`.

`null` reiškia, kad nei bloką, nei plėtinį nevaldo Blockstudio.
Blockstudio blokas be laukų grąžina `[]`.

Funkcija vykdo tą pačią transformaciją kaip ir atvaizduojant, todėl turi tokį patį
šalutinį poveikį: failų laukai užklausia priedų, bloko laukas, kuris negrąžina
`data`, atvaizduoja nurodytą bloką, o
`blockstudio/blocks/attributes/render` filtras vykdomas kiekvienai reikšmei. Ji
neatvaizduoja paties bloko šablono ir neišsprendžia `innerBlocks`; pereikite juos
patys. Kodo lauko sugeneruotas `%selector%` ID skiriasi kiekvieno iškvietimo metu.

Reikšmės nustatomos pagal dabartinį WordPress kontekstą. Tik atvaizduojant kuriami metaduomenys, tokie kaip
blokų skaitikliai ir `innerBlocks`, nesukuriami; atributų atvaizdavimo filtrams
perduodamas bloko pavadinimas, o ne visiškai atvaizduoto bloko metaduomenys.

Nėra parinkties gauti išsaugotas reikšmes be transformacijos. Tiesiogiai nuskaitykite
`attrs` masyvą arba naudokite
[`bs_validate_block()`](https://blockstudio.dev/lt/docs/blocks/rendering/#validating-stored-values) joms
patikrinti.

## Tuščios reikšmės

Jei laukas tuščias arba nepasirinkta jokia parinktis, atributo reikšmė yra `false`.


### PHP

```php title="index.php"
<?php if ($a['message']) : ?>
  <h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
```

### Twig

```twig title="index.twig"
{% if a.message %}
  <h1>{{ a.message }}</h1>
{% endif %}
```

## Sudėtiniai tipai

### Failai

Pagal numatytuosius nustatymus (be `returnFormat` arba su `"returnFormat": "object"`) failų laukas
grąžina masyvą su priedo duomenimis. Naudojant `"multiple": true`,
grąžinamas šių masyvų sąrašas. Jei failo priedo nebėra, grąžinama `false`.

| Raktas | Aprašas |
|-----|-------------|
| `ID` | Priedo ID. |
| `title` | Priedo pavadinimas. |
| `alt` | Alternatyvusis tekstas. Jei tuščias, naudojamas priedo pavadinimas. |
| `caption` | Antraštė. |
| `description` | Aprašas. |
| `href` | Priedo puslapio nuolatinė nuoroda. |
| `url` | Failo URL. Pasirinkus dydį išskleidžiamajame sąraše (`"size": true`), nurodomas pasirinkto dydžio URL. |
| `sizes` | URL ir kiekvieno užregistruoto vaizdo dydžio matmenys, žr. toliau. |

#### PHP

```php title="index.php"
<?php if ($a['image']) :
  $image = $a['image'];
  $sizes = $image['sizes'] ?? [];
?>
  <img
    src="<?php echo esc_url($sizes['large'] ?? $image['url']); ?>"
    alt="<?php echo esc_attr($image['alt']); ?>"
    <?php if (isset($sizes['large-width'], $sizes['large-height'])) : ?>
      width="<?php echo esc_attr($sizes['large-width']); ?>"
      height="<?php echo esc_attr($sizes['large-height']); ?>"
    <?php endif; ?>
  />
<?php endif; ?>
```

#### Twig

```twig title="index.twig"
{% if a.image %}
  <img
    src="{{ (a.image.sizes.large ?? a.image.url)|e('html_attr') }}"
    alt="{{ a.image.alt|e('html_attr') }}"
    {% if a.image.sizes['large-width'] is defined and a.image.sizes['large-height'] is defined %}
      width="{{ a.image.sizes['large-width']|e('html_attr') }}"
      height="{{ a.image.sizes['large-height']|e('html_attr') }}"
    {% endif %}
  />
{% endif %}
```

`sizes` turi po vieną įrašą kiekvienam užregistruotam vaizdo dydžiui ir `full`: URL po
 dydžio pavadinimu, o matmenys – po `<size>-width` ir `<size>-height`. Jei priedui dydis WordPress nebuvo sugeneruotas, naudojamas originalus failas su jo matmenimis. Jei WordPress negali nustatyti vaizdo ar peržiūros, rakto `sizes` nėra. Pavyzdžiui, PDF be sugeneruotos peržiūros neturi `sizes`, tačiau PDF su peržiūros metaduomenimis gali turėti vaizdo dydžių. `sizes` yra `null`, kai neužregistruotas joks vaizdo dydis arba kai filtras [`files/sizes`vaizdo dydžius](https://blockstudio.dev/lt/docs/blocks/hooks/php/#attributesfilessizes) juos išjungia.
Šis filtras taip pat gali sutrumpinti žemėlapį, todėl prieš skaitydami dydžio matmenis patikrinkite, ar tas dydis yra, kaip parodyta ankstesniuose pavyzdžiuose.

Objektas neturi raktų `width`, `height`, `mime`, `type` ar `size`. Matmenis nuskaitykite iš
`sizes` arba naudokite `ID` su tokiomis funkcijomis kaip
`wp_get_attachment_image()` ir `get_post_mime_type()`.

#### Grąžinimo formatai

`returnFormat` keičia lauko grąžinamą reikšmę:

| `returnFormat` | Reikšmė |
|----------------|-------|
| `"object"` (numatytoji) | Aukščiau aprašytas masyvas. |
| `"id"` | Išsaugotas priedo ID arba ID sąrašas su `"multiple": true`. |
| `"url"` | URL kaip eilutė arba URL sąrašas su `"multiple": true`. Vaizdams naudojamas dydis, nustatytas naudojant `returnSize` (numatytoji reikšmė `full`), o kitiems failams – jų failo URL. |

### Nuoroda

Nuorodos laukas grąžina objektą su atributais URL:


#### PHP

```php title="index.php"
<?php if ($a['link']) : ?>
  <a
    href="<?php echo $a['link']['url']; ?>"
    target="<?php echo $a['link']['target']; ?>"
  >
    <?php echo $a['link']['title']; ?>
  </a>
<?php endif; ?>
```

#### Twig

```twig title="index.twig"
{% if a.link %}
  <a href="{{ a.link.url }}" target="{{ a.link.target }}">
    {{ a.link.title }}
  </a>
{% endif %}
```

### Piktograma

Piktogramos laukas grąžina objektą su raktais `set`, `subSet` ir `icon`. Naudokite pagalbines funkcijas `bs_render_icon()` ir `bs_icon()`, kad išvestumėte SVG:


#### PHP

```php title="index.php"
<?php if ($a['icon']) : ?>
  <div class="icon">
    <?php bs_render_icon($a['icon']); ?>
  </div>
<?php endif; ?>
```

#### Twig

```twig title="index.twig"
{% if a.icon %}
  <div class="icon">
    {{ bs_icon(a.icon) }}
  </div>
{% endif %}
```

`bs_render_icon()` tiesiogiai išveda SVG. `bs_icon()` grąžina jį kaip eilutę.

### Atributai

Atributų tipo laukas grąžina `{attribute, value}` porų masyvą, kurį galima atvaizduoti kaip HTML atributus. Naudokite `bs_render_data_attributes()`, kad juos išvestumėte:


#### PHP

```php title="index.php"
<div <?php bs_render_data_attributes($a['attributes']); ?>>
  Content
</div>
```

#### Twig

```twig title="index.twig"
<div {{ fn('bs_render_data_attributes', a.attributes) }}>
  Content
</div>
```

`bs_render_data_attributes()` tiesiogiai išveda atributus. `bs_data_attributes()` grąžina eilutę.

### Grupė

Grupės laukai prie vaikinių atributų ID prideda grupės pavadinimą. Naudokite `bs_get_group()`, kad išskirtumėte grupės laukus į tvarkingą masyvą:


#### PHP

```php title="index.php"
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>
```

#### Twig

```twig title="index.twig"
{% set group = fn('bs_get_group', a, 'settings') %}
<h1>{{ group.title }}</h1>
<p>{{ group.description }}</p>
```

Taip nuo atributų raktų pašalinamas grupės prefiksas. Pavyzdžiui, `$a['settings_title']` tampa `$group['title']`.

Pagalbinė funkcija taip pat veikia, kai grupė gaunama iš pakartotinai naudojamo tinkinto lauko:

```json title="fields/section-header/field.json"
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "attributes": [
        { "id": "kicker", "type": "text" },
        { "id": "title", "type": "text" }
      ]
    }
  ]
}
```

```json title="block.json"
{
  "blockstudio": {
    "attributes": [
      { "type": "custom/section-header" }
    ]
  }
}
```

```twig title="index.twig"
{% set sectionHeader = fn('bs_get_group', a, 'section-header') %}
<p>{{ sectionHeader.kicker }}</p>
<h2>{{ sectionHeader.title }}</h2>
```

### Kartotuvas

Pereikite kartotuvo elementus ciklu:


#### PHP

```php title="index.php"
<?php foreach ($a['items'] as $item) : ?>
  <div class="item">
    <h3><?php echo $item['title']; ?></h3>
    <p><?php echo $item['description']; ?></p>
  </div>
<?php endforeach; ?>
```

#### Twig

```twig title="index.twig"
{% for item in a.items %}
  <div class="item">
    <h3>{{ item.title }}</h3>
    <p>{{ item.description }}</p>
  </div>
{% endfor %}
```


> **[Laukų šablonų receptų rinkinys](https://blockstudio.dev/lt/guides/field-patterns/)**
