woocommerce/plugins/woocommerce-blocks/docs/contributors/block-assets.md

# Block Script Assets <!-- omit in toc -->

## Table of contents <!-- omit in toc -->

-   [When are assets needed?](#when-are-assets-needed)
-   [Choosing Handles for Assets (and scripts in general)](#choosing-handles-for-assets-and-scripts-in-general)
-   [Using the `AbstractBlock` class](#using-the-abstractblock-class)
    -   [AbstractBlock::render](#abstractblockrender)
    -   [AbstractBlock::enqueue_editor_assets](#abstractblockenqueue_editor_assets)
    -   [AbstractBlock::enqueue_assets](#abstractblockenqueue_assets)
    -   [AbstractBlock::enqueue_data](#abstractblockenqueue_data)
-   [woocommerce_shared_settings deprecated filter](#woocommerce_shared_settings-deprecated-filter)

[Block Types](https://github.com/woocommerce/woocommerce-gutenberg-products-block/tree/trunk/src/BlockTypes) are often responsible for enqueuing script assets that make blocks functional on both the front-end and within the editor. Additionally, some block scripts require extra data from the server and thus have extra dependencies that need to be loaded.

For performance reasons the blocks plugin ensures assets and asset data is made available only as needed.

## When are assets needed?

Assets are needed when we know a block will be rendered.

In the context of [Block Types](https://github.com/woocommerce/woocommerce-gutenberg-products-block/tree/trunk/src/BlockTypes), assets and asset data is enqueued within the block `render()` method.

In an admin editor context we must also ensure asset _data_ is available when the `enqueue_block_editor_assets` hook is fired. That is because block scripts are enqueued ready for the Block Inserter, but the block may not be rendered.

Note: `enqueue_block_editor_assets` fires regardless of whether or not a block has been rendered in the editor context, so unless handled correctly, block data may be loaded twice. The `AbstractBlock` class below handles this for you, or you can track whether or not assets have been loaded already with a class variable.

## Choosing Handles for Assets (and scripts in general)

When creating a script or style assets, the following rules should be followed to keep asset names consistent, and to avoid
conflicts with other similarly named scripts.

1. All asset handles should have a `wc-` prefix.
2. If the asset handle is for a Block (in editor context) use the `-block` suffix.
3. If the asset handle is for a Block (in frontend context) use the `-block-frontend` suffix.
4. If the asset is for any other script being consumed or enqueued by the blocks plugin, use the `wc-blocks-` prefix.

Some examples:

1. A Block called 'featured-product' would have asset handles named: `wc-featured-product-block` and `wc-featured-product-block-frontend`.
2. A script being used by a block, for example, named 'tag-manager' would have the handle: `wc-blocks-tag-manager`.

These rules also apply to styles.

## Using the `AbstractBlock` class

The [`AbstractBlock` class](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/trunk/src/BlockTypes/AbstractBlock.php) has some helper methods to make asset management easier. Most Block Types in this plugin extend this class.

### AbstractBlock::render

The default `render` method will call `AbstractBlock::enqueue_assets`—this ensures both scripts and asset data is ready once the block is rendered.

### AbstractBlock::enqueue_editor_assets

This method is hooked into `enqueue_block_editor_assets`. If assets have not already loaded, it calls `AbstractBlock::enqueue_data` to ensure data dependencies exist ready for the Block Editor.

### AbstractBlock::enqueue_assets

If assets have not already been loaded, this method calls `enqueue_data` and `enqueue_scripts`.

Classes which extend `AbstractBlock` should override `enqueue_data` and `enqueue_scripts` to handle their specific assets.

### AbstractBlock::enqueue_data

If extending `AbstractBlock` this method can be overridden. It should enqueue/register asset data used by the block.

```php
protected function enqueue_data( array $attributes = [] ) {
    $data_registry = Automattic\WooCommerce\Blocks\Package::container()->get(
        Automattic\WooCommerce\Blocks\Assets\AssetDataRegistry::class
    );
    $data_registry->add( 'some-asset-data', 'data-value' );
}
```

## woocommerce_shared_settings deprecated filter

This filter was used as a workaround. Currently the best way to achieve data registration comes from using AssetsDataRegistry:

```php
	Automattic\WooCommerce\Blocks\Package::container()
		->get( Automattic\WooCommerce\Blocks\Assets\AssetDataRegistry::class )
		->add( $key, $value );
```

On the client side the value will be available via:

```js
wc.wcSettings.getSetting( 'key' );
```

<!-- FEEDBACK -->

---

[We're hiring!](https://woocommerce.com/careers/) Come work with us!

🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce/issues/new?assignees=&labels=type%3A+documentation&template=suggestion-for-documentation-improvement-correction.md&title=Feedback%20on%20./docs/contributors/block-assets.md)

<!-- /FEEDBACK -->