Assembler and extensibility: how to make it extendible from block theme developers

[gigitux]

The Assembler works only with the Twenty Twenty-Four theme, which means that users who want to use it have to switch to it to proceed with the flow. This next phase of the project aims to enable compatibility with most block themes in WordPress. In this way, users can leverage the full potential of the Assembler within their favorite block themes while developers gain the opportunity to create themes optimized for a seamless Assembler experience. In this way:

• Users who love the customization options of the Assembler can enjoy them without sacrificing their preferred block theme.
• Block theme developers can enhance their themes by offering features that integrate smoothly with the Assembler.

Currently, the Assembler is an high customized version of the Gutenberg editor. For this reason, it leverages the WordPress API for its features. This allows us to prioritize extensibility over creating custom APIs, ensuring better code maintainability and future compatibility with WordPress updates.

For instance, features like font selection and color palettes rely on a mocked theme.json file:

• Theme.json that empowered the font feature
• Theme.json that empowers the color palette feature

Currently, the Assembler allows users to customize:

• fonts
• color palette
• patterns

Fonts

Currently, the Assembler relies on a hardcoded selection of font pairs. Instead, we could rely on the active theme's theme.json file for font pair information. WordPress documentation provides clear guidelines on how to register font pairs within theme.json.

If the theme doesn’t implement any font pair, we could use the Font Library APIs to install and apply fallback fonts.

Color Palette

Similar to the fonts, the Assembler relies on a hardcoded selection of color palettes. Instead, we could rely on the active theme's theme.json file for color palettes. WordPress documentation provides clear guidelines on how to implement different color palette.

⚠️ If the theme doesn’t implement any style variations, providing a fallback solution could be complex. The reason is that the palettes are based on the slug property (for instance, the TT4 theme.json). Each block theme could implement different slugs, making it difficult to establish a universally compatible fallback mechanism.

In this commit, there is a POC of this approach: dd70e2a.

Patterns

WordPress documentation outlines how block patterns can be registered under distinct categories. The Assembler can fetch all registered patterns by utilizing the WordPress REST API. We can then define specific categories for different layout sections within the Assembler.

This allows the theme developer to register patterns that will be visible only in a specific layout section.

For example, we could define some constants:

$header_section = “ASSEMBLER_HEADER_SECTION”
$homepage_section = “ASSEMBLER_HOMEPAGE_SECTION”
$footer_section = “ASSEMBLER_FOOTER_SECTION”

The block theme developer can register its pattern under one of the above categories. For instance:

register_block_pattern(
            'assembler/my-example',
            array(
                'title'         => __( 'My First Block Pattern', 'textdomain' ),
                'description'   => _x( 'This is my first block pattern', 'Block pattern description', 'textdomain' ),
                'content'       => '<!-- wp:paragraph --><p>A single paragraph block style</p><!-- /wp:paragraph -->',
                'categories'    => array("ASSEMBLER_HEADER_SECTION"),
            )
        )

To improve the developer experience, we could create wrapper functions too.

In this commit, there is a POC of this approach: a246477.

Default Homepage template

The frame includes one header, one Intro pattern, and one footer. Currently, the select patterns are hardcoded. Instead, we should allow theme developers to select which patterns should be used. In addition to the above solution, we could use the assembler_default category to make a pattern as the default one. For instance:

register_block_pattern(
            'assembler/my-example',
            array(
                'title'         => __( 'My First Block Pattern', 'textdomain' ),
                'description'   => _x( 'This is my first block pattern', 'Block pattern description', 'textdomain' ),
                'content'       => '<!-- wp:paragraph --><p>A single paragraph block style</p><!-- /wp:paragraph -->',
                'categories'    => array("ASSEMBLER_HEADER_SECTION", "ASSEMBLER_HEADER_DEFAULT"),
            )
        )

In this case, the assembler/my-example pattern will be used as the default pattern for the header section.

Why we should avoid to create a dedicated API

The Assembler is designed to be a user-friendly starting point for creating and customizing WooCommerce stores. Its features are meant to be an "essential toolkit" for those who are new to WooCommerce or who prefer a simplified editing experience. Everything achievable with the Assembler should also be possible within the full-featured Site Editor. This ensures a smooth transition for users as they graduate to more advanced customization options.
For this reason, creating dedicated APIs for the Assembler might seem counterintuitive. Instead, leveraging existing WordPress and Gutenberg APIs offers several advantages:

• Reduced complexity: By minimizing custom code, we maintain a cleaner and more manageable codebase for the Assembler, leading to easier maintenance and updates.
• Enhanced compatibility: Aligning with existing APIs fosters better compatibility with WordPress block themes and plugins.
• Seamless transition to Site Editor: By relying on core functionalities, users/theme developers can be confident that the skills they acquire with the Assembler will translate seamlessly to the Site Editor for advanced customization.

Assembler theme

As previously mentioned, some block themes may not include font pairs or color palettes within their theme.json files. Fortunately, Font Library APIs offer the possibility of installing fallback font pairs. However, creating a universal fallback solution for color palettes presents a significant challenge.

To address these limitations and provide a consistent design experience, we could create a dedicated Assembler theme. This theme would leverage the existing, hardcoded theme.json we currently have in place.

The Assembler theme could offer multiple benefits:

• The “Assembler theme” can serve as a practical example for block theme developers. By studying it, they can learn how to create block themes fully compatible with the Assembler, expanding the design options for users.
• In the case of no font pairs/color palettes, we could render a notice to inform the user that the current block theme doesn’t support all the features of the Assembler and invite them to install the “Assembler theme”.
• Potentially, in some cases - when the store is completely new, we could enable the “Assembler theme”.

What do you think?