Add preview logic to enable pattern caching as .html files and subsequent load from the cache

[bobbingwide]

A number of FSE themes in the wordpress.org directory load a whole host of patterns from .php files.
See bobbingwide/oik-themes#11 particularly bobbingwide/oik-themes#11 (comment)

In #2, I developed logic to load patterns from .htm files in the block-template-parts folder.
These were template parts that didn't make it into the official templates.

Having seen Nick Diego's presentation at https://www.meetup.com/SF-WordPress-Users/events/283096780/ I'm encouraged to continue to develop my solution for Internationalization and Localization of FSE themes.

My approach is to continue to use .html files rather than .php for the translation. I believe this will produce a better product in the long run.

I propose to develop a prototype solution that will enable previewing of any theme's patterns from blocks.wp-a2z.org without having to activate the theme at runtime.

There are several stages

1. Implement logic to load and display the pattern from the .html file or .php file.
2. Implement logic to cache the en_US version of each pattern into a plain .html file
3. Implement logic to load and display the cached plain .html version.
4. Extend the oik-i18n work to include translation of the en_US version where the strings are extracted directly from the .html.

Proposed solution

Develop step 1 first: Extend the basic solution in #2 to support loading of patterns from the patterns folder and its subfolders.

Folder/files	Contents
patterns/	Source folder for.html patterns for the theme
patterns/*.html	Patterns in the General category
patterns/category	Source folder for patterns in the category "Category"
patterns/category/*.html	Patterns in the Category category

Notes:

• Pattern categories are registered using register_block_pattern_category( $category_name, $category_properties )
• Patterns are registered using register_block_pattern( $pattern_name, $pattern_properties)

where $pattern_properties include:

Property	Vaue
title	generated from the .html file name
content	content of the .html file
categories	determined from the subfolder name

There are other properties but these are not necessarily required for front-end previewing.

Example: with a pattern from the Fizzie theme

fizzie/patterns/plugins-blocks-catalogued.html

register_block_pattern_category( 'fizzie', 'Fizzie' );
register_block_pattern_category( 'general', 'General' );
register_block_pattern( 'plugins-blocks-catalogued',  
   [ [ 'title'] => "Plugins blocks catalogued", 
   'categories' => ['fizzie', 'general' ],
  'content' => content of the .html file
  ] );

This solution works fine for themes delivering .html patterns.
For themes with .php files it loads files which are not patterns.
Implementing stage 2. should resolve this issue.

[bobbingwide]

2. Implement logic to cache the en_US version of each pattern into a plain .html file.

Requirements

• plain .html files which are domain agnostic and which can be translated
• generated automatically from the source theme
• automatically generated for each new version of the theme.

The challenges with working with .php files in the theme are:

• that they'll only get loaded when the theme is active.
• they may contain code that's dependent upon functions loaded by the theme's functions.php file

This can possibly be addressed by tricking the theme into registering the block pattern categories and patterns by loading the theme's function's php and rerunning the init hook callback that performs the registering.

Another way to do this is to temporarily activate the theme and implement a process that checks the cached version with the current version. If there's a new theme version then the patterns would be re-exported.

This second option appears to be easier? How do we temporarily activate a theme? By an AJAX request or something?

[bobbingwide]

Proposed directory usage for cacheing theme's patterns

WordPress uses the wp-content/languages/themes folder to store the .mo files for your chosen locale

• We can use a theme specific subfolder for the cached patterns for each locale.
  eg wp-content/languages/themes/fizzie/en_US for the source
  and wp-content/languages/themes/fizzie/en_GB for the UK English language version
  wp-content/languages/themes/fizzie/bb_BB for the Bbboing language version.

• This folder will reflect the category structure described for .html files.

• It may need to implement translated templates and parts as well.

[bobbingwide]

How do we temporarily activate a theme?

I've developed the first pass of the logic.

• When the query parameter preview_theme is set then oik-patterns will load this theme instead of the defined theme.
• Because there isn't yet a better solution the theme will load its patterns during init processing.
• At the end of init processing oik-patterns will then cache the theme's pattern files
• It also generates a patterns.json file.
• Theoretically the patterns.json file will list all the patterns
• Each of the .php files which contained a pattern will have been cached.
• So oik-themes no longer needs to bother about finding all the source .php files.

Let's see what we can do with the patterns.json file.

[bobbingwide]

The patterns.json file will need an array of the titles for each of the categories, as these are translatable.

[bobbingwide]

I'm going to change the title of this from "Try loading patterns from .html files in a patterns folder and/or subfolders in FSE themes"
to "Add preview logic to enable pattern caching as .html files and subsequent load from the cache".

oik-patterns would provide the following services:

1. Loading of patterns for a theme with .html pattern files
2. Preview capability for a theme with .php pattern files
3. Caching of rendered patterns
4. Loading of cached patterns for the theme that had been previewed.

[bobbingwide]

Additional requirements for child theme preview.
The logic in oik-patterns that will replace the theme when preview_theme=theme needs to be more robust.

• it needs to validate the theme name early.
• If the theme name is not valid then the template and stylesheet filters do not need to be added.
• The logic should take into account child themes, which define their template in style.css

The validation is performed at plugins_loaded. If the query parm is set then the OIK_patterns_export is loaded and validate_theme() is run. All the logic's now in OIK_patterns_export; oik-patterns.php doesn't need to do anything else.

[bobbingwide]

This is now installed in blocks.wp-a2z.org.
I tested different values for the preview_theme query arg

preview_theme	OK?	Explanation
silly	y	Appeared as Fizzie - No such theme
wizzie	y	Appeared as Wizzie - child theme of Fizzie
affinity	y	Appeared as Fizzie - Not a block theme
aino	y	Appeared as Aino
armando	y	Appearead as Armando
../fred	y	Appeared as Fizzie - invalid theme name
genesis	y	Appeared as Genesis
genesis-oik	y	Appeared as genesis-oik

Notes:

• Unlike foster-child, this code doesn't check if the theme is a block theme.
• If the header/ footer templates display a menu what you get depends on how it's coded
• Sometimes it's OK, other times it's the page list, or maybe no menu at all