# WordPress Block API Small collection of helpful interfaces and abstract classes to make the development of WordPress Blocks and Extensions easier and more consistent. ## Requirements * PHP version 7.3 or greater * WordPress version 5.7 or greater ## Installation You will need [Composer](https://getcomposer.org/) installed on your computer in order to build and use this package. * Add this package to the `require` field in your `composer.json` * Import `vendor/autoload.php` in your project ```bash composer require sixach/wp-block-api ``` --- # Usage ## In Blocks & Extensions Simply extend the block or extension class that fits the requirements of your package and extend all relevant interfaces (for extensions): ```PHP namespace Sixa_Blocks; final class My_Block extends Block { public static function register(): void { register_block_type_from_metadata( plugin_dir_path( __DIR__ ) ); } } ``` ```PHP namespace Sixa_Blocks; final class My_Extension extends Extension { public static function register(): void { Functions::register_extension_from_metadata( plugin_dir_path( __DIR__ ) ); } } ``` Development and usage is simplified if all blocks and extensions use `namespace Sixa_Blocks`. ### Create an `extension.json` Registration of extensions is done using a JSON configuration file akin to the `block.json` file that WordPress Core uses. Example: ```JSON { "name": "sixa-wp-extension-awesome-feature", "frontendScript": "file:./build/script.js", "frontendStyle": "file:./build/style.css", "script": "file:./build/both.js", "style": "file:./build/style-index.css", "editorScript": "file:./build/index.js", "editorStyle": "file:./build/index.css", "requires": [ "sixa/add-to-cart" ] } ``` Currently, `extension.json` uses the following fields: #### name Defines the name of the extension. This field is heavily utilized for asset handles and must be unique. #### frontendScript File handle used for the script that's only enqueued in the frontend. Use `file:` prefix if you are passing a path to a local file. The path must be relative to `extension.json`. #### frontendStyle File handle used for the style that's only enqueued in the frontend. Use `file:` prefix if you are passing a path to a local file. The path must be relative to `extension.json`. #### script File handle used for the script that's enqueued in the editor and the frontend. Use `file:` prefix if you are passing a path to a local file. The path must be relative to `extension.json`. #### style File handle used for the style that's enqueued in the editor and the frontend. Use `file:` prefix if you are passing a path to a local file. The path must be relative to `extension.json`. #### editorScript File handle used for the script that's only enqueued in the editor. Use `file:` prefix if you are passing a path to a local file. The path must be relative to `extension.json`. #### editorStyle File handle used for the style that's only enqueued in the editor. Use `file:` prefix if you are passing a path to a local file. The path must be relative to `extension.json`. #### requires An array of block names that the given extension requires. During asset enqueueing, the post content is check if at least one of the passed blocks is present. If it is not, the extension assets are not enqueued to improve performance. ## In Projects Each block and extension includes an `init` function that can be called to initialize the class. No other function needs to be called. ### As a Plugin To run your block or extension as a standalone plugin, simply create a plugin file (e.g. `index.php`) that calls the `init` function of your class. ```PHP array( __CLASS__, 'render' ), ) ); } public static function render( array $attributes = array() ): string { // Add your render callback here. } private static function some_setup(): void { // Add your setup code here (e.g. post type registration). } } ``` ## Abstract Class WooCommerce Block A simple block class that extends `Sixa_Blocks\Block` with a few additional convenience functions to enable WooCommerce specific block initialization. Particularly, for a set of WooCommerce blocks (i.e. blocks that require WooCommerce), initialization and registration of the block is only necessary if WooCommerce is also installed. In some cases the block might even produce a fatal error if WooCommerce is not activated. For these instances, we intend to skip block registration. `Sixa_Blocks\WooCommerce_Block` extends `Sixa_Blocks\Block` with a simple check in `Sixa_Blocks\WooCommerce_Block::init()` that prevents the block from being registered (i.e. `Sixa_Blocks\Block::register()` from being added in `init`) if WooCommerce is not installed and activated. Other than that, `Sixa_Blocks\WooCommerce_Block` is identical to `Sixa_Blocks\Block`. ### Basic Example ```PHP namespace Sixa_Blocks; final class My_WooCommerce_Block extends WooCommerce_Block { public static function register(): void { register_block_type_from_metadata( plugin_dir_path( __DIR__ ) ); } } ``` `Sixa_Blocks\My_WooCommerce_Block::register()` is automatically **not** called if WooCommerce is not installed. ## Abstract Class Extension A simple extension class that includes the default implementation of an extension. Particularly, `Sixa_Blocks\Extension` includes and performs block initialization and adds `Sixa_Blocks\Extension::register()` to the WordPress action hook `init`. `Sixa_Blocks\Extension::register()` is not implemented. In its most basic form, a simple block only needs to implement this function and perform `Sixa_Blocks\Functions::register_extension_from_metadata` according to the extension requirements. ### Basic Example ```PHP namespace Sixa_Blocks; final class My_Extension extends Extension { public static function register(): void { Functions::register_extension_from_metadata( plugin_dir_path( __DIR__ ) ); } } ```