Skip to content

Integrating Page Builder with an Older Framework#

This guide covers how to integrate Page Builder and Flex Components into a store running custom or pre-10.05 Shadows theme, without performing a full framework migration.

Overview#

Page Builder is available on every Miva store. The Flex module, default components, CSS, JS, and four starter layouts (Blank, Storefront, Landing Page 1, Landing Page 2) are pre-installed. New standalone pages can be created with Page Builder immediately — navigate to User Interface > Page Builder > Create Page with no template changes required.

Template integration is only required when adding Page Builder to existing pages (homepage, category pages, product pages, etc.) or when components need to visually match an older theme.

Page Builder components are Web Components with encapsulated styles. They do not depend on the existing framework’s CSS and will not break existing templates. The only template changes involved are adding sequence item tags in a branch — nothing reaches production until the branch is merged.

Step 1: Create a Template Branch#

All template work should be done in a branch.

  1. Navigate to User Interface
  2. Click the branch name in the upper left corner
  3. Select Create New Branch
  4. Name the branch (e.g., Page Builder Integration) and copy from Production
  5. Click Create

This allows all changes to be sandboxed until the branch is merged to production.

⚠️ Hardcoded Resource Links in Older Frameworks

Many stores on older frameworks use hardcoded <link> and <script> tags in templates that point directly to CSS and JS files on the server, outside of Miva’s managed Resource system.

When a template branch is created, templates are branched but the files those hardcoded links reference are not. The branch and production share the same physical files on disk — editing a hardcoded CSS or JS file in a branch immediately affects the live site.

Before starting work, audit templates for hardcoded resource links. Look for <link> and <script> tags referencing file paths directly (e.g., /css/styles.css, /js/scripts.js) rather than using <mvt:item name="head" param="css:resource_code" /> or <mvt:item name="head" param="js:resource_code" />.

If hardcoded links are present: - Do not edit those files while working in the branch. - To modify those files as part of the integration, copy them with new filenames, update the hardcoded references in the branch templates to point to the copies, and edit only the copies. When the branch is merged, templates will reference the new files. - Consider migrating hardcoded resources into Miva’s managed Resource system to make them properly branch-aware going forward.

⚠️ Resource Groups

Resource Groups are not branch-specific. Deleting a Resource Group in a development branch removes it from production immediately. Never delete default Resource Groups — only add new resources to them.

Step 2: Add Page Builder to the Storefront (Homepage)#

2a. Assign the Required Items#

The flex and sequence items must be assigned to the SFNT page.

Via the Admin UI: 1. Navigate to User Interface > Templates 2. Select the SFNT page 3. Go to the Items tab 4. Assign both flex and sequence

Via Provisioning XML: 

<PageItem_Assign Pagecode="SFNT" itemcode="sequence" />
<PageItem_Assign Pagecode="SFNT" itemcode="flex" />

2b. Add the Sequence Tag to the Template#

Edit the SFNT page template and add the sequence item tag where components should render:

<section class="o-wrapper">
    <div class="o-layout">
        <mvt:item name="sequence" />
    </div>
</section>

Full replacement: Replace all existing storefront content with this tag. Page Builder components manage all page content.

Gradual migration: Place <mvt:item name="sequence" /> above or below existing template code to migrate content section by section while keeping the rest of the page intact.

Example: Older Shadows SFNT Template#

An older Shadows storefront uses ReadyTheme items to render content sections. A typical template looks like:

Before: 

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="readytheme" param="contentsection( 'hero_image' )" />
    </div>
</section>

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="readytheme" param="contentsection( 'featured_categories' )" />
    </div>
</section>

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="readytheme" param="contentsection( 'featured_products' )" />
    </div>
</section>

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="readytheme" param="contentsection( 'promo_banner' )" />
    </div>
</section>

After — full replacement: 

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="sequence" />
    </div>
</section>

The individual ReadyTheme content sections are replaced by Page Builder components (Hero Banner, Category Carousel, Product Carousel, Text Banner, etc.) managed through the Page Builder editor.

After — gradual migration: 

<!-- Page Builder-managed content -->
<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="sequence" />
    </div>
</section>

<!-- Existing ReadyTheme content still in use -->
<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="readytheme" param="contentsection( 'featured_products' )" />
    </div>
</section>

Note: ReadyTheme content sections and Page Builder can coexist on the same page. Remove ReadyTheme calls incrementally as content is migrated into Page Builder components.

2c. Build the Page in Page Builder#

  1. Go to User Interface > Page Builder
  2. Open the SFNT page
  3. Add and configure components
  4. Click Save

Step 3: Add Page Builder to Dynamic Pages#

Most standard pages support a dedicated Page Builder component that replaces the existing content — including dynamic pages (Category, Product) and static pages (About Us, Contact Us, FAQs). These pages can be fully managed using the main sequence item.

Two integration approaches:

  • Full Page Builder control (recommended): Assign the main sequence item and replace the existing content tag in the template with <mvt:item name="sequence" />. Place the appropriate component (Category Listing, Product Display, etc.) in Page Builder.
  • Header/footer zones only (gradual migration): Retain the existing content tag and add header_sequence and footer_sequence items above and below it to enable Page Builder-managed zones while the core page content remains unchanged.

3a. Create and Assign the Sequence Items#

Two new items — header_sequence and footer_sequence — must be created and assigned along with flex (and the main sequence for content pages) to each target page.

Via the Admin UI:

Create the two items:

  1. Navigate to User Interface > Items
  2. Click Add Item
  3. Set the Code to header_sequence and select Sequence as the module
  4. Click Save
  5. Repeat to create a second item with Code footer_sequence

Assign items to each page. For each page below, navigate to User Interface > Templates, select the page, go to the Items tab, and assign the specified items:

Page Items to assign
Category Display (CTGY) sequence, header_sequence, footer_sequence, flex
Product Display (PROD) sequence, header_sequence, footer_sequence, flex
Product List (PLST) sequence, header_sequence, footer_sequence, flex
Search Results (SRCH) sequence, header_sequence, footer_sequence, flex
About Us (ABUS) sequence, header_sequence, footer_sequence, flex
Contact Us (CTUS) sequence, header_sequence, footer_sequence, flex
FAQs (FAQS) sequence, header_sequence, footer_sequence, flex
Privacy Policy (PRPO) sequence, header_sequence, footer_sequence, flex
Shipping & Returns (SARP) sequence, header_sequence, footer_sequence, flex
Basket (BASK) header_sequence, footer_sequence, flex

Via Provisioning XML:

<!-- Create Header/Footer Sequence Items -->
<Item_Add Code="header_sequence" Module="cmp-mv-sequence" />
<Item_Add Code="footer_sequence" Module="cmp-mv-sequence" />

<!-- Pages with dedicated Page Builder content components -->
<PageItem_Assign Pagecode="CTGY" itemcode="sequence" />
<PageItem_Assign Pagecode="CTGY" itemcode="header_sequence" />
<PageItem_Assign Pagecode="CTGY" itemcode="footer_sequence" />
<PageItem_Assign Pagecode="CTGY" itemcode="flex" />

<PageItem_Assign Pagecode="PROD" itemcode="sequence" />
<PageItem_Assign Pagecode="PROD" itemcode="header_sequence" />
<PageItem_Assign Pagecode="PROD" itemcode="footer_sequence" />
<PageItem_Assign Pagecode="PROD" itemcode="flex" />

<PageItem_Assign Pagecode="PLST" itemcode="sequence" />
<PageItem_Assign Pagecode="PLST" itemcode="header_sequence" />
<PageItem_Assign Pagecode="PLST" itemcode="footer_sequence" />
<PageItem_Assign Pagecode="PLST" itemcode="flex" />

<PageItem_Assign Pagecode="SRCH" itemcode="sequence" />
<PageItem_Assign Pagecode="SRCH" itemcode="header_sequence" />
<PageItem_Assign Pagecode="SRCH" itemcode="footer_sequence" />
<PageItem_Assign Pagecode="SRCH" itemcode="flex" />

<PageItem_Assign Pagecode="ABUS" itemcode="sequence" />
<PageItem_Assign Pagecode="ABUS" itemcode="header_sequence" />
<PageItem_Assign Pagecode="ABUS" itemcode="footer_sequence" />
<PageItem_Assign Pagecode="ABUS" itemcode="flex" />

<PageItem_Assign Pagecode="CTUS" itemcode="sequence" />
<PageItem_Assign Pagecode="CTUS" itemcode="header_sequence" />
<PageItem_Assign Pagecode="CTUS" itemcode="footer_sequence" />
<PageItem_Assign Pagecode="CTUS" itemcode="flex" />

<PageItem_Assign Pagecode="FAQS" itemcode="sequence" />
<PageItem_Assign Pagecode="FAQS" itemcode="header_sequence" />
<PageItem_Assign Pagecode="FAQS" itemcode="footer_sequence" />
<PageItem_Assign Pagecode="FAQS" itemcode="flex" />

<PageItem_Assign Pagecode="PRPO" itemcode="sequence" />
<PageItem_Assign Pagecode="PRPO" itemcode="header_sequence" />
<PageItem_Assign Pagecode="PRPO" itemcode="footer_sequence" />
<PageItem_Assign Pagecode="PRPO" itemcode="flex" />

<PageItem_Assign Pagecode="SARP" itemcode="sequence" />
<PageItem_Assign Pagecode="SARP" itemcode="header_sequence" />
<PageItem_Assign Pagecode="SARP" itemcode="footer_sequence" />
<PageItem_Assign Pagecode="SARP" itemcode="flex" />

<!-- Basket — header/footer only -->
<PageItem_Assign Pagecode="BASK" itemcode="header_sequence" />
<PageItem_Assign Pagecode="BASK" itemcode="footer_sequence" />
<PageItem_Assign Pagecode="BASK" itemcode="flex" />

3b. Add the Item Tags to Each Page Template#

Content pages (CTGY, PROD, PLST, SRCH, ABUS, CTUS, FAQS, PRPO, SARP)#

Option A — Full Page Builder control (recommended):

Replace only the existing dynamic content tag with <mvt:item name="sequence" />, preserving the surrounding HTML wrapper. The wrapping markup maintains existing spacing and layout structure. Place the appropriate content component (Category Listing, Product Display, Product List, Search Results) in Page Builder alongside any supplemental components.

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="header_sequence" />
    </div>
</section>

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="sequence" />
    </div>
</section>

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="footer_sequence" />
    </div>
</section>

Option B — Header/footer zones only (gradual migration):

Retain the existing dynamic content tag and its surrounding wrapper. Add the header/footer zones around the existing block.

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="header_sequence" />
    </div>
</section>

<section class="o-wrapper">
    <div class="o-layout">
        <div class="o-layout__item">
            <mvt:item name="category_listing" />
        </div>
    </div>
</section>

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="footer_sequence" />
    </div>
</section>

Basket (BASK) — header/footer zones only#

The Basket page uses a dedicated basket item to render the cart. Use header/footer zones only — do not replace any existing basket markup:

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="header_sequence" />
    </div>
</section>

<section class="o-wrapper">
    <div class="o-layout__item">
        <!-- Existing basket content unchanged -->
    </div>
</section>

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="footer_sequence" />
    </div>
</section>

Example: Older Shadows CTGY Template#

An older Shadows category page typically uses ReadyTheme sections for category header images and promotional banners alongside the dynamic product listing.

Before: 

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="readytheme" param="contentsection( 'category_header_image' )" />
    </div>
</section>

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="category_listing" />
    </div>
</section>

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="readytheme" param="contentsection( 'category_footer_promo' )" />
    </div>
</section>

After — full Page Builder control: 

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="header_sequence" />
    </div>
</section>

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="sequence" />
    </div>
</section>

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="footer_sequence" />
    </div>
</section>

Only <mvt:item name="category_listing" /> is replaced — the surrounding <section> and layout divs remain so the page retains its existing spacing and grid alignment. The ReadyTheme content sections can be removed. A Category Listing component renders the product grid; additional components (banners, carousels) can be added alongside it in Page Builder.

After — gradual migration: 

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="header_sequence" />
    </div>
</section>

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="readytheme" param="contentsection( 'category_header_image' )" />
    </div>
</section>

<mvt:item name="category_listing" />

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="readytheme" param="contentsection( 'category_footer_promo' )" />
    </div>
</section>

<section class="o-wrapper">
    <div class="o-layout__item">
        <mvt:item name="footer_sequence" />
    </div>
</section>

The header_sequence and footer_sequence zones are now Page Builder-managed. To complete the migration, replace <mvt:item name="category_listing" /> with <mvt:item name="sequence" />, remove the ReadyTheme calls, and place the Category Listing component in Page Builder.

3c. Rename the Items (Optional)#

Item titles can only be set via Provisioning XML — there is no admin UI option for this.

<Page_Update code="CTGY">
    <Item code="sequence"><Title>Page Builder Content</Title></Item>
    <Item code="header_sequence"><Title>Page Builder Header</Title></Item>
    <Item code="footer_sequence"><Title>Page Builder Footer</Title></Item>
</Page_Update>

Repeat for each page with a main sequence item: PROD, PLST, SRCH, ABUS, CTUS, FAQS, PRPO, SARP. For BASK, include only header_sequence and footer_sequence.

Step 4: Add a Global Page Builder Zone (Optional)#

Global flex components render on every page of the site and are managed from a single location. This is appropriate for sitewide content such as promotional banners, free shipping thresholds, or announcement bars.

Once configured, the Global Header and Global Footer zones are accessible inside Page Builder by clicking the globe icon in the left navigation panel. Components added to these zones render across the entire site.

In Shadows 10.10+, both global zones are pre-configured. Skip to Step 4c. Older frameworks require the one-time setup in Steps 4a and 4b.

How It Works#

A global flex component is implemented as a Page Fragment whose template contains a sequence item. Miva renders the fragment wherever it is referenced in the global header or footer template. The sequence item inside the fragment is what Page Builder manages through the globe icon.

Fragment template structure:

<div class="o-wrapper t-global-sequence t-fragment__global-header">
    <mvt:item name="sequence" />
</div>

4a. Create the Fragment (Older frameworks only)#

Via the Admin UI:

  1. Navigate to User Interface > Templates > Fragments
  2. Click Add Fragment
  3. Enter a Name (e.g., Global Header) and Code (e.g., global_header)
  4. In the template editor, add the fragment markup: 
    <div class="o-wrapper t-global-sequence t-fragment__global-header">
    <mvt:item name="sequence" />
</div>
  5. Go to the Items tab and assign both sequence and flex
  6. Click Save

Repeat for the footer fragment, using code global_footer and CSS class t-fragment__global-footer.

4b. Reference the Fragment in the Global Template (Older frameworks only)#

Navigate to User Interface > Global Settings, find the Global Header & Footer section, and add the fragment tag to each template:

<!-- Global header template — after site navigation, before breadcrumb area -->
<mvt:fragment code="global_header" />

<!-- Global footer template — after main content area, before site footer -->
<mvt:fragment code="global_footer" />

This is a one-time change. Once the fragment tags are present in the global templates, the zones appear in Page Builder automatically.

4c. Add Components to the Global Zones#

  1. Navigate to User Interface > Page Builder and open any page
  2. Click the globe icon in the left navigation panel
  3. Select Global Header or Global Footer
  4. Add components and configure content
  5. Click Save

Components added here render on every page of the site.

Step 5: Component Styling#

Out of the box, Page Builder components use mmx-base styles — a generic theme that functions on any framework but will not match a custom store design. The steps below cover how to align component styles with an existing theme.

Update the Primary Color#

Navigate to User Interface > CSS Resources (or User Interface > Resources > CSS Resources). Find and edit mmx-base/styles.css. In the .mmx-theme--light selector, change --color-primary-bg from var(--black) to the store’s brand hex color. This applies the brand color across all components.

Override Styles with mmx-customizations#

The mmx-customizations CSS resource is the recommended place for theme-specific overrides. Changes here are not affected by component updates.

  1. Navigate to User Interface > CSS Resources
  2. Locate mmx-customizations and confirm it is Active
  3. Add overrides to the source:
@import url("https://fonts.googleapis.com/css2?family=Poppins:wght@100;400&display=swap");

:root {
    --mmx-font-family-1: "Poppins", sans-serif;
    --mmx-color-primary-bg: #2E86C1;
}

mmx-hero::part(button__inner) {
    text-transform: uppercase;
}

mmx-image-across {
    --mmx-color-primary-bg: #1A5276;
}

Note: MMX components use Shadow DOM. Internal styles are encapsulated and cannot be targeted with standard CSS selectors. Use ::part() selectors to target elements exposed via part attributes.

Theme Editor (Shadows 10.12+)#

Stores on Shadows 10.12 or later can use the Theme Editor — a visual interface for configuring typography, buttons, and layouts across all Flex Components and Shadows templates. Access it at User Interface > Theme Editor or via the edit icon in Page Builder.

If Flex Components display “Legacy Styles” after upgrading to 10.12+, use the Switch to Theme button within each component to migrate to Theme Editor styles.

Extending Theme Editor to the Full Storefront (Shadows 26.01+)#

By default, Theme Editor styles apply to Flex Components. To extend them to the full storefront — checkout, account pages, wishlists, navigation, and all built-in templates — the theme’s template markup must be updated to use Theme Editor CSS classes.

Shadows 26.01.00 includes these changes. Stores on custom themes forked from an earlier Shadows version must apply them manually.

Theme Editor generates CSS targeting classes like mm-theme-typography-title-two and mm-theme-button-primary. Replacing legacy Shadows classes (e.g., c-heading-delta) with these in templates gives Theme Editor control over those elements site-wide. The GitHub diff from Shadows 10.13.04 → 26.01.00 is the authoritative reference for the required changes.

See Theme Editor — Shadows Integration for the full class reference, migration guide, and testing checklist.

Step 6: Preview, Test, and Deploy#

Preview#

  • Use the Template Branch Preview URL to view the full site with branch changes applied
  • Use Page Builder’s responsive preview to verify desktop, tablet, and mobile layouts
  • Confirm existing pages render correctly alongside new components

Merge to Production#

  1. Open the Branch Controls menu from the Branch Status Box
  2. Select Merge and choose Production as the target
  3. Sort changesets by date (oldest first), select all, and confirm

Rollback#

  1. Navigate to User Interface
  2. Click the three-dot menu > History
  3. Locate the changeset prior to the merge
  4. Select it and click Revert to Changeset

Alternative: Copy Page Approach#

To add Page Builder to an existing page without directly editing its templates:

  1. Create a new page from a Page Builder layout (e.g., SFNT-NEW using the Storefront layout)
  2. Build the content in Page Builder
  3. Use Copy Page to overwrite the existing page
  4. The existing page’s URL is preserved

Warning: Copy Page also copies SEO metadata (page title, meta keywords, meta description). Ensure the new page has correct SEO data before copying, or configure a Copy Page Rule that excludes SEO fields.

Page Reference#

Page Code Integration Approach Recommended Component(s)
Storefront SFNT Full — sequence replaces all content Hero, Product Carousel, Text Banner
Category Display CTGY Full or gradual — sequence replaces product grid Category List, Product List
Product Display PROD Full or gradual — sequence replaces product display Product Details
Product List PLST Full or gradual — sequence replaces product grid Product List
Search Results SRCH Full or gradual — sequence replaces results Product List
About Us ABUS Full — sequence replaces content Hero, Text, Image & Text, Text Editor
Contact Us CTUS Full — sequence replaces content Contact Form
FAQs FAQS Full — sequence replaces content Accordion, Text
Privacy Policy PRPO Full — sequence replaces content Text, Text Editor
Shipping & Returns SARP Full — sequence replaces content Accordion, Text, Text Editor
Basket BASK Header/footer zones only —