Skip to content

Commit

Permalink
Add layout API documentation. (#52673)
Browse files Browse the repository at this point in the history 
* Add layout API documentation.

* multi type layout

* Add all possible properties to layout default object.

* try oneof
  • Loading branch information
@tellthemachines
tellthemachines authored Jul 18, 2023
1 parent 155f2a0 commit 24ecc09
Show file tree
Hide file tree
Showing 2 changed files with 183 additions and 0 deletions.
73 changes: 73 additions & 0 deletions docs/reference-guides/block-api/block-supports.md
View file
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`.

### 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

- 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
110 changes: 110 additions & 0 deletions schemas/json/block.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -336,6 +336,116 @@
"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": {
"default": false,
"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.",
"oneOf": [
{ "type": "boolean" },
{
"type": "object",
"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"
]
},
"contentSize": {
"type": "string",
"description": "The content size used on all children."
},
"wideSize": {
"type": "string",
"description": "The wide size used on alignwide children."
},
"justifyContent": {
"type": "string",
"description": "Content justification value.",
"enum": [
"right",
"center",
"space-between",
"left",
"stretch"
]
},
"orientation": {
"type": "string",
"description": "The orientation of the layout.",
"enum": [ "horizontal", "vertical" ]
},
"flexWrap": {
"type": "string",
"description": "The flex wrap value.",
"enum": [ "wrap", "nowrap" ]
},
"verticalAlignment": {
"type": "string",
"description": "The vertical alignment value.",
"enum": [
"top",
"center",
"bottom",
"space-between",
"stretch"
]
},
"minimumColumnWidth": {
"type": "string",
"description": "The minimum column width value."
},
"columnCount": {
"type": "number",
"description": "The column count value."
}
}
},
"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

1 comment on commit 24ecc09

@github-actions
Copy link

Choose a reason for hiding this comment

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

Flaky tests detected in 24ecc09.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/5582103688
📝 Reported issues:

Please sign in to comment.