From 4b95c31baa52a459f71325bfbd6408bb0c4645c1 Mon Sep 17 00:00:00 2001 From: Ben Leonard Date: Wed, 13 Aug 2025 12:50:35 +0100 Subject: [PATCH 1/3] Added block style modifier JavaScript library. --- includes/register-js-libraries.php | 17 ++++++ js-libraries/block-style-modifier.js | 90 ++++++++++++++++++++++++++++ plugin.php | 1 + 3 files changed, 108 insertions(+) create mode 100644 includes/register-js-libraries.php create mode 100644 js-libraries/block-style-modifier.js diff --git a/includes/register-js-libraries.php b/includes/register-js-libraries.php new file mode 100644 index 0000000..41fa270 --- /dev/null +++ b/includes/register-js-libraries.php @@ -0,0 +1,17 @@ + { + const interval = setInterval( + () => { + if (typeof wp == 'undefined') { + return; + } + if (typeof wp.blocks == 'undefined') { + return; + } + + clearInterval(interval); + resolve(); + }, + 10 + ); + } + ); + } + + /** + * Waits for a style to become availible for a particular block. + * + * @param {string} blockName The name of the block. + * @param {string} styleName The name of the style. + */ + async awaitStyleAvailability(blockName, styleName) { + await new Promise( + (resolve) => { + const interval = setInterval( + () => { + const block = wp.blocks.getBlockType(blockName); + + if (typeof block == 'undefined') { + return; + } + + if (!block.styles.filter((style) => { return style.name == styleName; }).length) { + return; + } + + clearInterval(interval); + resolve(); + }, + 10 + ); + } + ); + } +} \ No newline at end of file diff --git a/plugin.php b/plugin.php index 11aec10..d430ba5 100644 --- a/plugin.php +++ b/plugin.php @@ -27,6 +27,7 @@ require_once __DIR__ . '/includes/class-command-base.php'; require_once __DIR__ . '/includes/commands/all.php'; require_once __DIR__ . '/includes/class-asset-enqueue.php'; +require_once __DIR__ . '/includes/register-js-libraries.php'; // Register commands. Install_Theme_Command::register(); From 3ed37e34335f824ef7c276cc08a08ecccf1b0bb2 Mon Sep 17 00:00:00 2001 From: Ben Leonard Date: Wed, 13 Aug 2025 12:51:08 +0100 Subject: [PATCH 2/3] Added example implementation of block style modifier library. --- theme-template/includes/register-scripts.php | 13 +++++++++++++ theme-template/js/admin/block-styles.js | 8 ++++++++ theme-template/vite.config.js | 1 + 3 files changed, 22 insertions(+) create mode 100644 theme-template/js/admin/block-styles.js diff --git a/theme-template/includes/register-scripts.php b/theme-template/includes/register-scripts.php index 06fa29c..ee5fd06 100644 --- a/theme-template/includes/register-scripts.php +++ b/theme-template/includes/register-scripts.php @@ -20,3 +20,16 @@ function () { wp_enqueue_script( 'example_script' ); } ); + +/** + * Enqueues admin scripts. + */ +add_action( + 'admin_enqueue_scripts', + function () { + $asset_enqueue = Asset_Enqueue::get_instance(); + + $asset_enqueue->register_vite_script( 'block_styles', 'js/admin/block-styles.js', array( 'block_style_modifier' ) ); + wp_enqueue_script( 'block_styles' ); + } +); diff --git a/theme-template/js/admin/block-styles.js b/theme-template/js/admin/block-styles.js new file mode 100644 index 0000000..2708515 --- /dev/null +++ b/theme-template/js/admin/block-styles.js @@ -0,0 +1,8 @@ +/** + * JavaScript to update core block styles for necessary theming. +*/ + +// Example usage of Block_Style_Modifier: +// const blockStyleModifier = new Block_Style_Modifier(); +// blockStyleModifier.removeStyle( 'core/button', 'outline' ); +// blockStyleModifier.addStyle( 'core/button', 'arrow', 'Arrow' ); diff --git a/theme-template/vite.config.js b/theme-template/vite.config.js index 740413d..49bfb4d 100644 --- a/theme-template/vite.config.js +++ b/theme-template/vite.config.js @@ -20,6 +20,7 @@ export default defineConfig( rollupOptions: { // overwrite default .html entry input: { + blockStyles: resolve(__dirname, 'js/admin/block-styles.js'), main: resolve(__dirname, 'vite-entry-points/main.js'), admin: resolve(__dirname, 'vite-entry-points/admin.js'), } From 9f9594376e5e152e1da093b054dcb1978cc8c745 Mon Sep 17 00:00:00 2001 From: Ben Leonard Date: Wed, 13 Aug 2025 14:17:03 +0100 Subject: [PATCH 3/3] Added documentation --- docs/.vitepress/config.mts | 29 +++++++ docs/js-libraries.md | 2 + docs/js-libraries/block-style-modifier.md | 34 +++++++++ docs/php-libraries.md | 2 + docs/php-libraries/custom-post-types.md | 18 +++++ docs/php-libraries/post-fields.md | 93 +++++++++++++++++++++++ 6 files changed, 178 insertions(+) create mode 100644 docs/js-libraries.md create mode 100644 docs/js-libraries/block-style-modifier.md create mode 100644 docs/php-libraries.md create mode 100644 docs/php-libraries/custom-post-types.md create mode 100644 docs/php-libraries/post-fields.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index a765141..a2c642d 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -20,6 +20,35 @@ export default defineConfig({ { text: 'Migrating from Theme Core', link: '/migrating-from-theme-core' } ] }, + { + text: 'Framework', + items: [ + { + text: 'PHP Libraries', + link: '/php-libraries', + items: [ + { + text: 'Custom Post Types', + link: '/php-libraries/custom-post-types' + }, + { + text: 'Post Fields', + link: '/php-libraries/post-fields' + } + ] + }, + { + text: 'JavaScript Libraries', + link: '/js-libraries', + items: [ + { + text: 'Block Style Modifier', + link: '/js-libraries/block-style-modifier' + }, + ] + } + ] + }, { text: 'Commands', items: [ diff --git a/docs/js-libraries.md b/docs/js-libraries.md new file mode 100644 index 0000000..0b161a1 --- /dev/null +++ b/docs/js-libraries.md @@ -0,0 +1,2 @@ +# JavaScript Libraries +This project comes with a series of JavaScript libraries that can be used within a theme. \ No newline at end of file diff --git a/docs/js-libraries/block-style-modifier.md b/docs/js-libraries/block-style-modifier.md new file mode 100644 index 0000000..2df4b74 --- /dev/null +++ b/docs/js-libraries/block-style-modifier.md @@ -0,0 +1,34 @@ +--- +outline: deep +--- + +# Block Style Modifier + +## Introduction +This library will allow block styles to be added and removed without the dependency, sequencing and context complications that must be accounted for when using core WordPress functionality. + +This will support the style management of both core and custom blocks. + +## The class +You will need to instantiate the Block_Style_Modifier class. + +```js +const blockStyleModifier = new Block_Style_Modifier(); +``` + +## Removal +To remove a block style you can use the removeStyle function. + +```js +blockStyleModifier.removeStyle( 'core/button', 'outline' ); +``` + +## Addition +To add a block style you can use the addStyle function. + +```js +blockStyleModifier.addStyle( 'core/button', 'arrow', 'Arrow' ); +``` + +## File architecture +During a theme installation, a file will be created at the following path, relative to the theme root: /js/admin/block-styles.js. Functionality associated with enqueueing this file will also be installed. Implementation of the Block_Style_Modifier class should be added to this file. diff --git a/docs/php-libraries.md b/docs/php-libraries.md new file mode 100644 index 0000000..f6b1de2 --- /dev/null +++ b/docs/php-libraries.md @@ -0,0 +1,2 @@ +# PHP Libraries +This project comes with a series of extendable PHP classes and functionality that can be used within a theme. diff --git a/docs/php-libraries/custom-post-types.md b/docs/php-libraries/custom-post-types.md new file mode 100644 index 0000000..2869bb0 --- /dev/null +++ b/docs/php-libraries/custom-post-types.md @@ -0,0 +1,18 @@ +--- +outline: deep +--- + +# Custom Post Types + +## Base class extension +The abstract class Creode_Theme\Base_Post_Type can be extended within your theme to declare a custom post type. + +The abstract class uses a singleton design pattern therefore cannot be publicly instantiated. each extension must be initialized by calling the it's static init function. + +## File architecture +During a theme installation, a folder will be created at the following path, relative to the theme root: /includes/post-types. Extension class files should be created within this folder. The folder also contains a file called all.php. This file should used to require extension class files and initialize them. + +```php +require_once __DIR__ . 'class-my-example-post-type.php'; +My_Example_Post_Type::init(); +``` \ No newline at end of file diff --git a/docs/php-libraries/post-fields.md b/docs/php-libraries/post-fields.md new file mode 100644 index 0000000..b160d22 --- /dev/null +++ b/docs/php-libraries/post-fields.md @@ -0,0 +1,93 @@ +--- +outline: deep +--- + +# Post Fields + +## Base class extension +The abstract class Creode_Theme\Base_Post_Fields can be extended within your theme to declare a field group against a single post type or multiple post types. + +The abstract class uses a singleton design pattern therefore cannot be publicly instantiated. each extension must be initialized by calling the it's static init function. + +The base class uses ACF Pro to manage these fields therefore this must be installed. + +Extension classes must define information about the field group and an ACF fields array. + +The base class works by assigning the field group to post types which support a particular custom feature (support). This can be defined by extending the support function and returning the applicable support feature string. + +```php +/** + * Class to register post logo fields. + */ +class Logo_Post_Fields extends Base_Post_Fields { + + /** + * {@inheritdoc} + */ + protected function group_name(): string { + return 'logo'; + } + + /** + * {@inheritdoc} + */ + protected function group_title(): string { + return 'Logo'; + } + + /** + * {@inheritdoc} + */ + protected function fields(): array { + return array( + array( + 'key' => 'field_logo', + 'name' => 'logo', + 'label' => 'Logo', + 'type' => 'image', + 'return_format' => 'ID', + ), + ); + } + + /** + * {@inheritdoc} + */ + protected function support(): string { + return 'logo'; + } +} +``` + +## Custom supports + +The example above requires that applicable post types support the "logo" custom feature (support). This means that custom post types must include this within their supports array: + +```php +/** + * {@inheritdoc} + */ +protected function args(): array { + return array( + 'supports' => array( + 'title', + 'editor', + 'thumbnail', + 'excerpt', + 'logo', + ), + 'show_in_rest' => true, + 'has_archive' => true, + ); +} +``` + +Pre-existing post types can have additional supports added by using the add_post_type_support function: https://developer.wordpress.org/reference/functions/add_post_type_support/ + +## File architecture +During a theme installation, a folder will be created at the following path, relative to the theme root: /includes/post-fields. Extension class files should be created within this folder. The folder also contains a file called all.php. This file should used to require extension class files and initialize them. + +```php +require_once __DIR__ . 'class-logo-post-fields.php'; +Logo_Post_Fields::init(); +``` \ No newline at end of file