Templates and Patterns

With templates on, the storefront's product, catalog, category, tag, cart, checkout, and search pages render through visual-editor templates, so a store owner can design them in the site editor. The storefront also offers three block patterns. Both are built from the commerce Blocks.

Turning templates on

Templates are off by default, so installing visual-editor doesn't change an existing store:

// config/artisanpack/ecommerce-storefront-livewire.php
'visual_editor' => [
    'blocks'    => true,
    'templates' => true,
],

A page renders through a template only when all of these hold:

• visual_editor.templates is true;
• the blocks are available (see Visual Editor);
• cms-framework's site editor is installed (ArtisanPackUI\CMSFramework\Modules\SiteEditor\Resolution\TemplateResolver exists);
• the ve-template Blade component is registered.

Otherwise, and whenever no template in the page's chain resolves, the page renders its Livewire component as usual. If the resolver throws, the error is reported and the page falls back the same way.

Default templates

With templates on, the storefront offers these templates to the site editor through the ap.visualEditor.templates filter. A template you already have with the same slug is kept; the storefront's is only a default. Each is attributed to the active theme (or storefront when no theme manager is available).

Apart from single-product, each template wraps its blocks in a group block with the classes flex flex-col gap-6.

Which template a page uses

The page tries each slug in its chain, in order, and uses the first one the site editor resolves to a template with blocks.

So, to give one product its own layout, create a single-product-blue-mug template; to change every variable product, create single-product-variable. Slugs are lowercased. A product, category, or tag slug that isn't made of letters, numbers, -, and _ (starting with a letter or number) skips its entry and moves on to the next one in the chain.

Order lookup, order pages, and account pages don't use templates.

Patterns

The storefront offers these patterns through ap.visualEditor.patterns whenever the blocks are available (templates on or off). They are in the commerce pattern category and unsynced.

A pattern you already have with the same slug is kept.

Changing the defaults

Two filters change what the storefront offers. Each receives an array keyed by slug, with title, description, and content (block markup). Entries with an invalid slug (lowercase letters, numbers, _, -, and /), or without a title or content, are dropped.

StorefrontTemplates::block( $slug, $attrs ) builds a commerce block's markup for you:

use ArtisanPackUI\EcommerceStorefrontLivewire\Blocks\StorefrontTemplates;

addFilter( 'ap.ecommerceStorefrontLivewire.patterns', function ( array $patterns ): array {
    $patterns['artisanpack-commerce/new-arrivals'] = [
        'title'       => __( 'New arrivals' ),
        'description' => __( 'The eight newest products.' ),
        'content'     => StorefrontTemplates::block( 'product-grid', [ 'source' => 'newest', 'limit' => 8 ] ),
    ];

    unset( $patterns['artisanpack-commerce/sale-banner-grid'] );

    return $patterns;
} );

See Hooks Reference.