Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Block attributes docs: minor documentation inconsistencies #41468

Merged
merged 5 commits into from
Jun 22, 2022
Merged

Block attributes docs: minor documentation inconsistencies #41468

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
af42c32
Block attributes docs: consistency across attribute definitions
vasartam May 31, 2022
d483c08
Block attributes docs: use tabs
vasartam May 31, 2022
594fab7
Block attributes docs: unify code blocks descriptions
vasartam May 31, 2022
45b1cb4
Block attributes docs: add 'source'
vasartam May 31, 2022
5371d9c
Block attributes docs: nest 'Meta source' heading one level deeper
vasartam May 31, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 17 additions & 11 deletions docs/reference-guides/block-api/block-attributes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,7 @@ Attribute available in the block:

Most attributes from markup will be of type `string`. Numeric attributes in HTML are still stored as strings, and are not converted automatically.

Attribute definition:
```js
{
width: {
Expand All @@ -167,12 +168,14 @@ Most attributes from markup will be of type `string`. Numeric attributes in HTML
}
```

Attribute available in the block:
```js
{ "width": "50" }
```

The only exception is when checking for the existence of an attribute (for example, the `disabled` attribute on a `button`). In that case type `boolean` can be used and the stored value will be a boolean.

Attribute definition:
```js
{
disabled: {
Expand All @@ -184,6 +187,7 @@ The only exception is when checking for the existence of an attribute (for examp
}
```

Attribute available in the block:
```js
{ "disabled": true }
```
Expand Down Expand Up @@ -230,7 +234,7 @@ Saved content:

Attribute definition:
```js
attributes: {
{
content: {
type: 'string',
source: 'text',
Expand All @@ -244,7 +248,7 @@ Attribute available in the block:
{ "content": "The inner text of .my-content class" }
```

### `html`
### `html` source

Use `html` to extract the inner HTML from markup. Note that text is returned according to the rules of [`innerHTML`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerHTML).

Expand All @@ -259,7 +263,7 @@ Saved content:

Attribute definition:
```js
attributes {
{
content: {
type: 'string',
source: 'html',
Expand All @@ -275,6 +279,7 @@ Attribute available in the block:

Use the `multiline` property to extract the inner HTML of matching tag names for the use in `RichText` with the `multiline` prop.

Attribute definition:
```js
{
content: {
Expand All @@ -291,7 +296,7 @@ Attribute available in the block:
{ "content": "<p>First line</p><p>Second line</p>" }
```

### `query`
### `query` source

Use `query` to extract an array of values from markup. Entries of the array are determined by the `selector` argument, where each matched element within the block will have an entry structured corresponding to the second argument, an object of attribute sources.

Expand Down Expand Up @@ -333,21 +338,22 @@ Attribute definition:
Attribute available in the block:
```js
{
"images": [
{ "url": "https://lorempixel.com/1200/800/", "alt": "large image" },
{ "url": "https://lorempixel.com/50/50/", "alt": "small image" }
]
"images": [
{ "url": "https://lorempixel.com/1200/800/", "alt": "large image" },
{ "url": "https://lorempixel.com/50/50/", "alt": "small image" }
]
}
```

## Meta (deprecated)
### Meta source (deprecated)

<div class="callout callout-alert">
Although attributes may be obtained from a post's meta, meta attribute sources are considered deprecated; <a href="https://github.com/WordPress/gutenberg/blob/c367c4e2765f9e6b890d1565db770147efca5d66/packages/core-data/src/entity-provider.js">EntityProvider and related hook APIs</a> should be used instead, as shown in the <a href="/block-editor/how-to-guides/metabox/#step-2-add-meta-block">Create Meta Block how-to</a>.
</div>

Attributes may be obtained from a post's meta rather than from the block's representation in saved post content. For this, an attribute is required to specify its corresponding meta key under the `meta` key:
Attributes may be obtained from a post's meta rather than from the block's representation in saved post content. For this, an attribute is required to specify its corresponding meta key under the `meta` key.

Attribute definition:
```js
{
author: {
Expand Down Expand Up @@ -390,7 +396,7 @@ edit: function( props ) {

{% end %}

### Considerations
#### Considerations

By default, a meta field will be excluded from a post object's meta. This can be circumvented by explicitly making the field visible:

Expand Down