FRAGMENTS: Fragment Experiments and Claude's Wrap Up

Platform: Miva Empressa (current, new admin) Category: Template Architecture / Performance Verified: Yes — live branch experiment

Background & Motivation

Global headers, footers, and page templates accumulate heavy computational MVT code alongside UI markup — price group logic, customer detection, feature flag checks, struct population — tangled in with the HTML. The goal of this pattern is separation of concerns: move the programming layer into fragments, leave UI templates focused on presentation.

Previously handled with a function_something naming convention in ReadyTheme content sections — sections that output nothing visual but set l.settings variables for downstream use. Fragments are the native, more performant replacement.

Fragment Syntax

<!-- Simple fragment, no data sharing -->
<mvt:fragment code="my_fragment_code" />
 
<!-- With local l.settings share -->
<mvt:fragment code="my_fragment_code" share="shared_data" />
 
<!-- With nested struct member -->
<mvt:fragment code="my_fragment_code" share="shared_data:member1:member2" />
 
<!-- With global variable share -->
<mvt:fragment code="my_fragment_code" share="global:shared_data" />

Fragments can be called from any interpreted template — pages, layouts, other fragments.

WARNING/IMPORTANT: You must write to l.settings:fragment:share in the fragment mvt code if you want your shared variable to have the new data. Kind of like a pointer in old C. See the full example at the bottom.

The Share Attribute — Pass by Reference

The share attribute is the key architectural feature. It works like pass-by-reference — the named variable is bidirectionally linked between the calling template and the fragment. Whatever the fragment writes to l.settings:fragment:share is immediately reflected in the caller's named variable after the fragment returns.

Calling template

<mvt:assign name="l.settings:customer:id" value="g.customer_id" />
<mvt:fragment code="compute_customer" share="customer" />
 
<!-- l.settings:customer is now populated by the fragment -->
&mvt:customer:price_group;
&mvt:customer:display_name;

Inside the fragment

<!-- Read incoming data -->
<mvt:eval expr="l.settings:fragment:share:id" />
 
<!-- Write results back -->
<mvt:assign name="l.settings:fragment:share:price_group" value="'retail'" />
<mvt:assign name="l.settings:fragment:share:display_name" value="'Scot Ranney'" />

Note: The share bridge is a single named variable — the entire l.settings scope is NOT automatically available inside a fragment. Data must be explicitly declared in the share contract. This is a feature, not a limitation — it forces clean interfaces between the programming and UI layers.

Experiment Results

Verified bidirectional struct sharing in a live branch:

<!-- Calling template -->
<mvt:assign name="l.settings:scot:fname" value="'Scot'" />
<mvt:assign name="l.settings:scot:lname" value="'Ranney'" />
<mvt:fragment code="hellotest" share="scot" />
<!-- After: l.settings:scot:fname = 'xScot', l.settings:scot:lname = 'xRanney' -->
 
<!-- Inside fragment hellotest -->
<mvt:assign name="l.settings:fragment:share:fname" value="'xScot'" />
<mvt:assign name="l.settings:fragment:share:lname" value="'xRanney'" />

Mutations to fragment:share members are reflected in the calling template's named variable immediately after the fragment returns. Full struct pass-by-reference confirmed.

Architectural Patterns

1. Input/Output Struct — Function Replacement

Seed a struct with inputs, call the fragment, read computed outputs. Clean function signature pattern.

<mvt:assign name="l.settings:pricing:base_price" value="l.settings:product:price" />
<mvt:assign name="l.settings:pricing:group" value="g.customer_group" />
<mvt:fragment code="compute_pricing" share="pricing" />
 
&mvt:pricing:final_price;
&mvt:pricing:discount_label;

2. Namespace Isolation — No Variable Collisions

Each fragment owns a named struct. Multiple fragments on the same page cannot stomp each other's variables.

<mvt:fragment code="load_customer_data"   share="customer" />
<mvt:fragment code="load_inventory_flags" share="inventory" />
<mvt:fragment code="load_promo_rules"	 share="promo" />
 
<!-- All three structs available, fully isolated -->

3. Pipeline / Context Builder

Build up a single context struct progressively through a chain of focused fragments.

<mvt:fragment code="ctx_customer"  share="ctx" />
<mvt:fragment code="ctx_pricing"   share="ctx" />
<mvt:fragment code="ctx_inventory" share="ctx" />
 
<!-- ctx struct fully populated, available to all downstream UI code -->

Performance Rationale

ReadyTheme content sections spin up the full Miva page rendering ecosystem on every call — full module initialization, full l.settings population, associated DB lookups. Fragments render in a narrow isolated scope and skip all of that overhead.

Pages with multiple function_something content sections can see meaningful TTFB improvement when migrated to fragments — each section eliminated removes a full ecosystem spin-up from the render cycle.

Migration Path — function_something to Fragments

1. Identify all function_something or widget_something content sections that produce no HTML output
2. For each, create a fragment with an appropriate share struct
3. Replace the <mvt:item name="readytheme" param="contentsection( 'function_something' )" /> call with <mvt:fragment code="fragment_code" share="my_struct" />
4. Remove the old content section

Rule of thumb: ReadyTheme content sections own HTML output. Fragments own the computational layer.

Example 1: Loading an array of categories and product lists, with product links.

Template code (borrowed from Geographicus) that calls the fragment:

<mvt:comment>
#
# ─── 	EXPLORE SECTION: add three category codes  to l.settings:_explore to create three products lists that will update on their own.
# 	VERY GOOD SEO practice here- auto updating links creates rich internal linking and a content changing home page without any extra work.
#	Currently using ids for new, feat, and rare (new maps, favorites, and kevin's favorites)
#
</mvt:comment>

<mvt:assign name="l.settings:_explore" value="'	new | feat | rare '" />

<mvt:fragment code="sfnt_explore" share="_explore" />

<section class="sfnt-explore container my-5">
	<h2 class="sfnt-explore__heading pop-heading">
			From the Collection
			<span class="pop-heading-rule"></span>
	</h2>
	<div class="row g-4">
		<mvt:foreach iterator="category" array="_explore">
			<div class="col-lg-4">
				<div class="carto-panel h-100">
				<span class="carto-corner carto-corner--tl"></span>
				<span class="carto-corner carto-corner--tr"></span>
				<span class="carto-corner carto-corner--bl"></span>
				<span class="carto-corner carto-corner--br"></span>
				<h6>&mvt:category:name;</h6>
				<nav class="nav flex-column">
					<mvt:foreach iterator="product" array="category:catlisting">
						<a class="nav-link ps-0" href="&mvt:product:link:uri;">&mvt:product:name;</a>
					</mvt:foreach>
				</nav>
				</div>
			</div>
		</mvt:foreach>
	</div>
</section>

Fragment Code: Note the bottom where we assign the compiled data into the share.

<mvt:comment>
#
# This will populate an array l.settings:_explore that takes category codes and rolls through them loading 
# active products and links.
# Used on the SFNT to add SEO links that change regularly based on new and sold products.
#
</mvt:comment>

<mvt:assign name="l.ok" value="miva_splitstring(l.settings:_explore,'|',l.settings:catcodes,'trim')" />

<mvt:assign name="l.settings:_explore" value="''" />

<mvt:foreach iterator="catcode" array="catcodes">
	<mvt:assign name="l.settings:_temp" value="''" />
	<mvt:do file="g.Module_Library_DB" name="l.ok" value="Runtime_Category_Load_Code_Cached( l.settings:catcode,l.settings:category )" />
	<mvt:do file="g.Module_Library_DB" name="l.ok" value="Runtime_ProductList_Load_Offset_Category_Sort( l.settings:category:id,0,6,'disp_order',l.nextoffset,l.settings:category:catlisting )" />
	<mvt:foreach iterator="product" array="category:catlisting">
		<mvt:do file="g.Module_Feature_URI_DB" name="l.ok" value="URI_Load_Product_Canonical(l.settings:product:id, l.settings:product:link)" />
	</mvt:foreach>
	<mvt:assign name="l.ok" value="miva_array_insert(l.categories,l.settings:category,-1)" />
</mvt:foreach>

<mvt:assign name="l.settings:fragment:share" value="l.categories" />

Discovered and documented during a Bootstrap 4→5 conversion project. Fragment behavior confirmed by direct experiment — bidirectional struct sharing via share is live and working on current Empressa. This pattern replaces the ProContent module approach and the function_something ReadyTheme hack for computational code isolation.