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

Add layout API documentation. #52673

Merged
merged 4 commits into from
Jul 18, 2023
Merged

Add layout API documentation. #52673

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c9735ae
Add layout API documentation.
tellthemachines Jul 17, 2023
1cc323f
multi type layout
tellthemachines Jul 17, 2023
c03e049
Add all possible properties to layout default object.
tellthemachines Jul 17, 2023
ae5b43d
try oneof
tellthemachines Jul 17, 2023
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
73 changes: 73 additions & 0 deletions docs/reference-guides/block-api/block-supports.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -543,6 +543,79 @@ supports: {
}
```

## layout

- Type: `boolean` or `Object`
- Default value: null
- Subproperties:
- `default`: type `Object`, default value null
- `allowSwitching`: type `boolean`, default value `false`
- `allowEditing`: type `boolean`, default value `true`
- `allowInheriting`: type `boolean`, default value `true`
- `allowSizingOnChildren`: type `boolean`, default value `false`
- `allowVerticalAlignment`: type `boolean`, default value `true`
- `allowJustification`: type `boolean`, default value `true`
- `allowOrientation`: type `boolean`, default value `true`

This value only applies to blocks that are containers for inner blocks. If set to `true` the layout type will be `flow`. For other layout types it's necessary to set the `type` explicitly inside the `default` object.

### layout.default

- Type: `Object`
- Default value: null

Allows setting the `type` property to define what layout type is default for the block, and also default values for any properties inherent to that layout type, e.g., for a `flex` layout, a default value can be set for `flexWrap`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also default values for any properties inherent to that layout type, e.g., for a flex layout, a default value can be set for flexWrap.

No biggie, but just curious about whether we should provide illustrative examples since theme.json doesn't cover any of the possible extended values?

			"default": {
				"type": "flex",
				"flexWrap": "nowrap"
			}

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm good point perhaps we should add all the possible values to the schema, or they might erroneously be flagged as invalid


### layout.allowSwitching

- Type: `boolean`
- Default value: `false`

Exposes a switcher control that allows toggling between all existing layout types.

### layout.allowEditing

- Type: `boolean`
- Default value: `true`

Determines display of layout controls in the block sidebar. If set to false, layout controls will be hidden.

### layout.allowInheriting
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure this property still makes sense. It's being used incorrectly across several core blocks (it doesn't do anything for blocks with flex type) and if we really don't want the content width toggle to display it's easier to just switch off allowEditing.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, it probably doesn't make much sense any more. Back when inheriting was a feature within a single layout type it probably did, but now we have two distinct layout types flow and constrained, so it probably doesn't make sense on its own.

I think it highlights that it was a good decision splitting the complex behaviour of inherit out into two separate layout types!


- Type: `boolean`
- Default value: `true`

For the `flow` layout type only, determines display of the "Inner blocks use content width" toggle.

### layout.allowSizingOnChildren

- Type: `boolean`
- Default value: `false`

For the `flex` layout type only, determines display of sizing controls (Fit/Fill/Fixed) on all child blocks of the flex block.

### layout.allowVerticalAlignment

- Type: `boolean`
- Default value: `true`

For the `flex` layout type only, determines display of the vertical alignment control in the block toolbar.

### layout.allowJustification

- Type: `boolean`
- Default value: `true`

For the `flex` layout type, determines display of the justification control in the block toolbar and block sidebar. For the `constrained` layout type, determines display of justification control in the block sidebar.

### layout.allowOrientation

- Type: `boolean`
- Default value: `true`

For the `flex` layout type only, determines display of the orientation control in the block toolbar.


## multiple

- Type: `boolean`
Expand Down
53 changes: 53 additions & 0 deletions schemas/json/block.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -336,6 +336,59 @@
"description": "By default, all blocks will appear in the inserter, block transforms menu, Style Book, etc. To hide a block from all parts of the user interface so that it can only be inserted programmatically, set inserter to false.",
"default": true
},
"layout": {
"type": "object",
"description": "This value only applies to blocks that are containers for inner blocks. If set to `true` the layout type will be `flow`. For other layout types it's necessary to set the `type` explicitly inside the `default` object.",
"default": null,
"properties": {
"default": {
"type": "object",
"description": "Allows setting the `type` property to define what layout type is default for the block, and also default values for any properties inherent to that layout type, e.g., for a `flex` layout, a default value can be set for `flexWrap`.",
"properties": {
"type": {
"type": "string",
"description": "The layout type.",
"enum": [ "constrained", "grid", "flex" ]
}
}
},
"allowSwitching": {
"type": "boolean",
"description": "Exposes a switcher control that allows toggling between all existing layout types.",
"default": false
},
"allowEditing": {
"type": "boolean",
"description": "Determines display of layout controls in the block sidebar. If set to false, layout controls will be hidden.",
"default": true
},
"allowInheriting": {
"type": "boolean",
"description": "For the `flow` layout type only, determines display of the `Inner blocks use content width` toggle.",
"default": true
},
"allowSizingOnChildren": {
"type": "boolean",
"description": "For the `flex` layout type only, determines display of sizing controls (Fit/Fill/Fixed) on all child blocks of the flex block.",
"default": false
},
"allowVerticalAlignment": {
"type": "boolean",
"description": "For the `flex` layout type only, determines display of vertical alignment controls in the block toolbar.",
"default": true
},
"allowJustification": {
"type": "boolean",
"description": "For the `flex` layout type, determines display of justification controls in the block toolbar and block sidebar. For the `constrained` layout type, determines display of justification control in the block sidebar.",
"default": true
},
"allowOrientation": {
"type": "boolean",
"description": "For the `flex` layout type only, determines display of the orientation control in the block toolbar.",
"default": true
}
}
},
"multiple": {
"type": "boolean",
"description": "A non-multiple block can be inserted into each post, one time only. For example, the built-in ‘More’ block cannot be inserted again if it already exists in the post being edited. A non-multiple block’s icon is automatically dimmed (unclickable) to prevent multiple instances.",
Expand Down