Blocks support

The framework provides backend support for the WooCommerce cart and checkout blocks (eventually to be expanded to support more WC-specific block types).

Declaring support

When adding support for the cart/checkout blocks, a frameworked plugin should indicate support by adding the corresponding flags in the SV_WC_Plugin constructor arguments, which by default are false (these defaults could be changed to true in a future version of the FW or the way handling WC features support is updated with some harmonization with the gateways "supports" flags for example):

// plugin supports hpos and checkout/cart blocks
'supported_features' => [
    'hpos'   => true,
    'blocks' => [
    'cart'     => true,
    'checkout' => true,
	],
],

Note

Presently, if a plugin loads a FW version that is intended to offer blocks support, but these values are false, it may display a notice to admins in case the cart/checkout blocks are detected in the corresponding WC pages to invite the merchant to revert to shortcodes. This behavior could be overridden in Blocks_Handler::add_admin_notices (see below).

Blocks Handler

The framework will automatically load a Blocks_Handler via a init_blocks_handler method. Individual plugins supporting blocks should override this method with their own handler instance extending Blocks_Handler. Typically this instance should extend the get_cart_block_integration_instance and get_checkout_block_integration_instance methods to return the desired integration class(es).

The handler will evaluate whether the plugin is supposed to load compatibility classes with the blocks, based on the aforementioned flags and the instances returned by these methods (a plugin could be flagged as compatible without having to implement dedicated classes if compatibility is built-in or achievable by other means).

The handler also includes some static methods to help detecting whether the plugin supports blocks or whether the cart/checkout blocks are actually in use by the install:

• is_checkout_block_in_use - returns true if the checkout block is in use in the current install
• is_cart_block_in_use - returns true if the cart block is in use in the current install
• page_contains_checkout_shortcode - returns true if a given page contains the woocommerce_checkout shortcode
• page_contains_cart_shortcode - returns true if a given page contains the woocommerce_cart shortcode

Integration Classes

The integration handlers should extend the base class Block_Integration which will provide most of the groundwork needed via the Block_Integration_Trait. Typically the plugins that intend to include a frontend blocks script will need to define a name for their integration to be used by WooCommerce via the get_name method. This will be sufficient to have the framework attempt to load a js file based on this name. The trait includes several filters and overrideable methods that could come in handy to specific integrations.

Script Data

If the block frontend scripts needs to handle data passed from the backend, this could be handled by extending the Block_Integration::get_script_data method, which should return an associative array of data. This data may be exposed in the frontend so make sure not to expose sensible data in there.

Gateways

Frameworked gateway plugins provide a slightly different integration mechanism which is still based off the classes and handlers mentioned above. The Gateway_Blocks_Handler is typically not expected to be overridden in this case (although still a possibility), and instead gateway plugins should just override the get_checkout_block_integration_instance and get_cart_block_integration_instance methods (typically just the former) found in the SV_WC_Payment_Gateway class (as a reminder, this is not the main gateway plugin class, but the individual gateway main class). Payment gateways typically work at checkout level so they will need to return here a class that extends the Gateway_Checkout_Block_Integration abstract.

Checkout Integration

The Gateway_Checkout_Block_Integration needs to pass the current gateway in context (as a gateway plugin could technically handle more than one gateway, for instance credit cards and echecks) as well as the plugin main class in its constructor. These are used by the framework base class to provide a large payload data expected to consumed by the corresponding frontend script, typically all the configuration and environment values that are shared across frameworked gateway plugins. Individual gatways within these plugins that extend this class might want to pass additional data that needs to be available in the frontend. There are several methods thad could be overridden but a more consistent way should be by extending the predefined callback add_payment_method_data which is hooking into a 'wc_' . $this->get_name() . '_' . $this->block_name . '_block_payment_method_data' defined in get_payment_method_data. You will notice this method builds the payment data by calling several internal methods which could also be overridden although typically this is not recommended.

Frontend scripts

Once a plugin backend has been integrated with these handlers, the framework classes will attempt to load specific js scripts that are expected to be placed into the assets/js/blocks folder, and corresponding stylesheet(s) into the assets/css/blocks folder. The expected name of the assets will be built by the Block_Integration_Trait methods based on the plugin and integration name, but could be altered by overriding methods or using filters if necessary. Likewise, the path could be changed into something else, which could be useful as to have it targeting a development script for example.

The content of these scripts is not covered in this wiki as individual plugins can decide how to build their own integration assets, which are expected to follow WooCommerce blocks developer guidelines.

Dependencies

Sometimes gateways and regular plugins need to load certain dependencies at checkout. The blocks scripts are registered in the Block_Integration_Trait::initialize method. It is here that dependencies for script and styles are defined via overrideable methods that return array of script handles which are also filterable. If necessary, it's also possible to add dependencies via add_main_script_dependency and add_main_script_stylesheet_dependency respectively, which can be invoked from the constructor of the integration class implementing the trait. Note that this only adds their handle, meaning you should have registered (or enqueued) that dependency with WordPress before the initialize method runs.