Add README.md files for BlockTemplates and ProductTemplates (#40425)
* Initial BlockTemplates readme * Fix code docs in SectionInterface * Fix code docs in GroupInterface * BlockTemplates README.md updates * ProductTemplates README.md updates * Changelog * Update reference to handbook. * Markdown linting: Allow the same headings under different nesting * Add missing method headers * Update Usage section of BlockTemplates README to be more clear * Import BlockInterface in examples
This commit is contained in:
Matt Sherman
GitHub
parent
756b0a6171
commit
e65c5dbef4
|
|
@ -0,0 +1,4 @@
|
|||
Significance: minor
|
||||
Type: add
|
||||
|
||||
Documentation for block templates and product editor templates.
|
||||
|
|
@ -0,0 +1,208 @@
|
|||
# BlockTemplates
|
||||
|
||||
The `Automattic\WooCommerce\Admin\BlockTemplates` namespace contains interfaces for working with block templates.
|
||||
|
||||
## Usage
|
||||
|
||||
Objects that implement the interfaces and fire the hooks in this namespace are instantiated using more specific APIs,
|
||||
such as:
|
||||
|
||||
- [Product Editor Templates](../Features/ProductBlockEditor/ProductTemplates/README.md)
|
||||
|
||||
Please see the documentation for those APIs for more information on how to do this.
|
||||
|
||||
Note: In order to use these interface type definitions, you will need to import them. For example to import the `BlockInterface`:
|
||||
|
||||
```php
|
||||
use Automattic\WooCommerce\Admin\BlockTemplates\BlockInterface;
|
||||
```
|
||||
|
||||
## Hooks
|
||||
|
||||
### `woocommerce_block_template_area_{template_area}_after_add_block_{block_id}`
|
||||
|
||||
Fires after a specific block is added to any template in a specific area.
|
||||
|
||||
The dynamic portion of the hook name, `$template_area`, refers to the area of the template the block was added to.
|
||||
|
||||
The dynamic portion of the hook name, `$block_id`, refers to the ID of the block that was added.
|
||||
|
||||
#### Parameters
|
||||
|
||||
##### `BlockInterface $block`
|
||||
|
||||
The block that was added.
|
||||
|
||||
### `woocommerce_block_template_after_add_block`
|
||||
|
||||
Fires after a block is added to a template.
|
||||
|
||||
Unless you need to perform an action after any block is added to any template, you should use the more specific `woocommerce_block_template_area_{template_area}_after_add_block_{block_id}` hook instead for better performance.
|
||||
|
||||
#### Parameters
|
||||
|
||||
##### `BlockInterface $block`
|
||||
|
||||
The block that was added.
|
||||
|
||||
### `woocommerce_block_template_area_{template_area}_after_remove_block_{block_id}`
|
||||
|
||||
Fires after a specific block is removed from any template in a specific area.
|
||||
|
||||
The dynamic portion of the hook name, `$template_area`, refers to the area of the template the block was removed from.
|
||||
|
||||
The dynamic portion of the hook name, `$block_id`, refers to the ID of the block that was removed.
|
||||
|
||||
#### Parameters
|
||||
|
||||
##### `BlockInterface $block`
|
||||
|
||||
The block that was removed.
|
||||
|
||||
### `woocommerce_block_template_after_remove_block`
|
||||
|
||||
Fires after a block is removed from a template.
|
||||
|
||||
Unless you need to perform an action after any block is removed from any template, you should use the more specific `woocommerce_block_template_area_{template_area}_after_remove_block_{block_id}` hook instead for better performance.
|
||||
|
||||
#### Parameters
|
||||
|
||||
##### `BlockInterface $block`
|
||||
|
||||
The block that was removed.
|
||||
|
||||
## Interfaces
|
||||
|
||||
### BlockTemplateInterface
|
||||
|
||||
All block templates implement this interface.
|
||||
|
||||
#### Methods
|
||||
|
||||
##### `get_id(): string`
|
||||
|
||||
Get the template ID.
|
||||
|
||||
##### `get_title(): string`
|
||||
|
||||
Get the template title.
|
||||
|
||||
##### `get_description(): string`
|
||||
|
||||
Get the template description.
|
||||
|
||||
##### `get_area(): string`
|
||||
|
||||
Get the template area.
|
||||
|
||||
##### `get_block( string $block_id ): ?BlockInterface`
|
||||
|
||||
Get a block by ID.
|
||||
|
||||
##### `remove_block( string $block_id )`
|
||||
|
||||
Removes a block from the template.
|
||||
|
||||
##### `remove_blocks()`
|
||||
|
||||
Removes all blocks from the template.
|
||||
|
||||
##### `get_formatted_template(): array`
|
||||
|
||||
Get the formatted template.
|
||||
|
||||
### BlockContainerInterface
|
||||
|
||||
#### Methods
|
||||
|
||||
##### `get_block( string $block_id ): ?BlockInterface`
|
||||
|
||||
Get a block by ID.
|
||||
|
||||
##### `remove_block( string $block_id )`
|
||||
|
||||
Removes a block from the template.
|
||||
|
||||
##### `remove_blocks()`
|
||||
|
||||
Removes all blocks from the template.
|
||||
|
||||
##### `&get_root_template(): BlockTemplateInterface`
|
||||
|
||||
Get the root template that the block belongs to.
|
||||
|
||||
##### `get_formatted_template(): array`
|
||||
|
||||
Get the block configuration as a formatted template.
|
||||
|
||||
### ContainerInterface
|
||||
|
||||
#### Methods
|
||||
|
||||
##### `get_block( string $block_id ): ?BlockInterface`
|
||||
|
||||
Get a block by ID.
|
||||
|
||||
##### `remove_block( string $block_id )`
|
||||
|
||||
Removes a block from the container.
|
||||
|
||||
##### `remove_blocks()`
|
||||
|
||||
Removes all blocks from the container.
|
||||
|
||||
##### `&get_root_template(): BlockTemplateInterface`
|
||||
|
||||
Get the root template that the container belongs to.
|
||||
|
||||
##### `get_formatted_template(): array`
|
||||
|
||||
Get the container as a formatted template.
|
||||
|
||||
### BlockInterface
|
||||
|
||||
#### Methods
|
||||
|
||||
##### `get_name(): string`
|
||||
|
||||
Get the block name.
|
||||
|
||||
#### `get_id(): string`
|
||||
|
||||
Get the block ID.
|
||||
|
||||
#### `get_order(): int`
|
||||
|
||||
Get the block order.
|
||||
|
||||
#### `set_order( int $order )`
|
||||
|
||||
Set the block order.
|
||||
|
||||
##### `get_attributes(): array`
|
||||
|
||||
Get the block attributes as a key/value array.
|
||||
|
||||
##### `set_attributes( array $attributes )`
|
||||
|
||||
Set the block attributes as a key/value array.
|
||||
|
||||
##### `&get_parent(): ContainerInterface`
|
||||
|
||||
Get the parent container that the block belongs to.
|
||||
|
||||
##### `&get_root_template(): BlockTemplateInterface`
|
||||
|
||||
Get the root template that the block belongs to.
|
||||
|
||||
##### `remove()`
|
||||
|
||||
Removes the block from its parent. When a block is removed from its parent, it is detached from both the parent and the root template.
|
||||
|
||||
##### `is_detached(): bool`
|
||||
|
||||
Check if the block is detached from its parent or root template. A detached block is no longer a part of the template and will not be included in the formatted template.
|
||||
|
||||
##### `get_formatted_template(): array`
|
||||
|
||||
Get the block configuration as a formatted template.
|
||||
|
|
@ -6,12 +6,12 @@ use Automattic\WooCommerce\Admin\BlockTemplates\BlockContainerInterface;
|
|||
use Automattic\WooCommerce\Admin\BlockTemplates\BlockInterface;
|
||||
|
||||
/**
|
||||
* Interface for block containers.
|
||||
* Interface for group containers, which contain sections and blocks.
|
||||
*/
|
||||
interface GroupInterface extends BlockContainerInterface {
|
||||
|
||||
/**
|
||||
* Adds a new section block.
|
||||
* Adds a new section to the group
|
||||
*
|
||||
* @param array $block_config block config.
|
||||
* @return SectionInterface new block section.
|
||||
|
|
@ -19,7 +19,7 @@ interface GroupInterface extends BlockContainerInterface {
|
|||
public function add_section( array $block_config ): SectionInterface;
|
||||
|
||||
/**
|
||||
* Adds a new block to the section block.
|
||||
* Adds a new block to the group.
|
||||
*
|
||||
* @param array $block_config block config.
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -0,0 +1,125 @@
|
|||
# ProductTemplates
|
||||
|
||||
The `Automattic\WooCommerce\Admin\Features\ProductBlockEditor\ProductTemplates` namespace contains interfaces for interacting with product editor templates, which are used to define the structure of the product editor form.
|
||||
|
||||
General interfaces for interacting with block templates are located in the
|
||||
[`Automattic\WooCommerce\Admin\BlockTemplates`](../../../BlockTemplates/README.md) namespace.
|
||||
|
||||
## Usage
|
||||
|
||||
For more examples and best practices, please see the Product Editor Development Handbook.
|
||||
|
||||
### Adding a new group to product editor templates after an existing group
|
||||
|
||||
```php
|
||||
use Automattic\WooCommerce\Admin\BlockTemplates\BlockInterface;
|
||||
|
||||
function YOUR_PREFIX_add_group( BlockInterface $general_group ) {
|
||||
$parent = $general_group->get_parent();
|
||||
|
||||
$parent->add_group(
|
||||
[
|
||||
'id' => 'YOUR-PREFIX-group',
|
||||
'order' => $general_group->get_order() + 5,
|
||||
'attributes' => [
|
||||
'title' => __( 'My Group', 'YOUR-TEXT-DOMAIN' ),
|
||||
],
|
||||
]
|
||||
);
|
||||
}
|
||||
|
||||
add_action( 'woocommerce_block_template_area_product-form_after_add_block_general', 'YOUR_PREFIX_add_group' );
|
||||
```
|
||||
|
||||
### Adding a new block to product editor templates after an existing block
|
||||
|
||||
```php
|
||||
use Automattic\WooCommerce\Admin\BlockTemplates\BlockInterface;
|
||||
|
||||
function YOUR_PREFIX_add_block( BlockInterface $product_name_block ) {
|
||||
$parent = $product_name_block->get_parent();
|
||||
|
||||
$parent->add_block(
|
||||
[
|
||||
'id' => 'YOUR-PREFIX-block',
|
||||
'blockName' => 'woocommerce/product-text-field',
|
||||
'order' => $product_name_block->get_order() + 5,
|
||||
'attributes' => [
|
||||
'label' => __( 'My Block', 'YOUR-TEXT-DOMAIN' ),
|
||||
],
|
||||
]
|
||||
);
|
||||
}
|
||||
|
||||
add_action( 'woocommerce_block_template_area_product-form_after_add_block_product-name', 'YOUR_PREFIX_add_block' );
|
||||
```
|
||||
|
||||
### Removing a block from product editor templates
|
||||
|
||||
```php
|
||||
use Automattic\WooCommerce\Admin\BlockTemplates\BlockInterface;
|
||||
|
||||
function YOUR_PREFIX_remove_block( BlockInterface $sale_price_block ) {
|
||||
$sale_price_block->remove();
|
||||
}
|
||||
|
||||
add_action( 'woocommerce_block_template_area_product-form_after_remove_block_sale-price', 'YOUR_PREFIX_remove_block' );
|
||||
```
|
||||
|
||||
## Interfaces
|
||||
|
||||
### GroupInterface
|
||||
|
||||
Groups are the top-level organizational structure for product editor templates.
|
||||
They typically contain one or more sections, though they can also contain
|
||||
blocks directly.
|
||||
|
||||
#### Methods
|
||||
|
||||
##### `add_section( array $block_config ): SectionInterface`
|
||||
|
||||
Add a new section to the group.
|
||||
|
||||
##### `add_block( array $block_config ): BlockInterface`
|
||||
|
||||
Add a new block to the group.
|
||||
|
||||
### SectionInterface
|
||||
|
||||
Sections are the second-level organizational structure for product editor templates.
|
||||
They typically contain one or more blocks, though they can also contain sub-sections
|
||||
if further organization is needed.
|
||||
|
||||
#### Methods
|
||||
|
||||
##### `add_section( array $block_config ): SectionInterface`
|
||||
|
||||
Add a new sub-section to the section.
|
||||
|
||||
##### `add_block( array $block_config ): BlockInterface`
|
||||
|
||||
Add a new block to the section.
|
||||
|
||||
### ProductFormTemplateInterface
|
||||
|
||||
All product form templates implement this interface.
|
||||
Product form templates are used to define the structure of the product editor form.
|
||||
They contain groups as their top-level organizational structure.
|
||||
|
||||
#### Methods
|
||||
|
||||
##### `add_group( array $block_config ): GroupInterface`
|
||||
|
||||
Add a new group to the template.
|
||||
|
||||
##### `get_group_by_id( string $group_id ): ?GroupInterface`
|
||||
|
||||
Gets a group by ID. Returns null if the group does not exist.
|
||||
|
||||
##### `get_section_by_id( string $section_id ): ?SectionInterface`
|
||||
|
||||
Gets a section by ID. Returns null if the section does not exist.
|
||||
|
||||
##### `get_block_by_id( string $block_id ): ?BlockInterface`
|
||||
|
||||
Gets a block by ID. Returns null if the block does not exist.
|
||||
|
|
@ -7,12 +7,12 @@ use Automattic\WooCommerce\Admin\BlockTemplates\BlockInterface;
|
|||
|
||||
|
||||
/**
|
||||
* Interface for block containers.
|
||||
* Interface for section containers, which contain sub-sections and blocks.
|
||||
*/
|
||||
interface SectionInterface extends BlockContainerInterface {
|
||||
|
||||
/**
|
||||
* Adds a new section block.
|
||||
* Adds a new sub-section to the section.
|
||||
*
|
||||
* @param array $block_config block config.
|
||||
* @return SectionInterface new block section.
|
||||
|
|
@ -20,7 +20,7 @@ interface SectionInterface extends BlockContainerInterface {
|
|||
public function add_section( array $block_config ): SectionInterface;
|
||||
|
||||
/**
|
||||
* Adds a new block to the section block.
|
||||
* Adds a new block to the section.
|
||||
*
|
||||
* @param array $block_config block config.
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue