diff --git a/plugins/woocommerce/changelog/add-template-api-readmes b/plugins/woocommerce/changelog/add-template-api-readmes new file mode 100644 index 00000000000..a3d87cd8135 --- /dev/null +++ b/plugins/woocommerce/changelog/add-template-api-readmes @@ -0,0 +1,4 @@ +Significance: minor +Type: add + +Documentation for block templates and product editor templates. diff --git a/plugins/woocommerce/src/Admin/BlockTemplates/README.md b/plugins/woocommerce/src/Admin/BlockTemplates/README.md new file mode 100644 index 00000000000..964dfb8511f --- /dev/null +++ b/plugins/woocommerce/src/Admin/BlockTemplates/README.md @@ -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. diff --git a/plugins/woocommerce/src/Admin/Features/ProductBlockEditor/ProductTemplates/GroupInterface.php b/plugins/woocommerce/src/Admin/Features/ProductBlockEditor/ProductTemplates/GroupInterface.php index 7a80d56c59a..f8fd4bfc9d0 100644 --- a/plugins/woocommerce/src/Admin/Features/ProductBlockEditor/ProductTemplates/GroupInterface.php +++ b/plugins/woocommerce/src/Admin/Features/ProductBlockEditor/ProductTemplates/GroupInterface.php @@ -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. */ diff --git a/plugins/woocommerce/src/Admin/Features/ProductBlockEditor/ProductTemplates/README.md b/plugins/woocommerce/src/Admin/Features/ProductBlockEditor/ProductTemplates/README.md new file mode 100644 index 00000000000..c3bbd31558b --- /dev/null +++ b/plugins/woocommerce/src/Admin/Features/ProductBlockEditor/ProductTemplates/README.md @@ -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. diff --git a/plugins/woocommerce/src/Admin/Features/ProductBlockEditor/ProductTemplates/SectionInterface.php b/plugins/woocommerce/src/Admin/Features/ProductBlockEditor/ProductTemplates/SectionInterface.php index 42f3ab0ae31..29dc52fe292 100644 --- a/plugins/woocommerce/src/Admin/Features/ProductBlockEditor/ProductTemplates/SectionInterface.php +++ b/plugins/woocommerce/src/Admin/Features/ProductBlockEditor/ProductTemplates/SectionInterface.php @@ -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. */