Split Blocks - Place Page Builder blocks above and below page content

What are split_blocks?

In a typical Shoporama theme, Page Builder blocks are rendered either before or after the main content of the page. This works fine in many cases, but it limits the store owner. What if you want a hero banner above the product list and a newsletter signup below it?

That's exactly what split_blocks solves. When enabled, Page Builder splits the blocks into two zones:

• Blocks above the content - Hero banners, campaign messages, USP sections and anything else that needs to grab the user's attention right away.
• Blocks below the content - Product recommendations, newsletter signup, Instagram feed, testimonials and similar supplementary content.

In between the two zones is the main content of the page - product info, category list, checkout flow or whatever the page displays. This gives the store owner full control over the layout without having to edit templates.

Activation in theme_settings.json

To enable split_blocks, add one line to your theme's theme_settings.json file, located in the root of the theme:

{ " info": "My Theme", " split_blocks": true, " settings": [ ... ] }

Without this line - or with "split_blocks": false - all blocks are displayed in a single list and are typically rendered after the main page content.

The experience in admin

When split_blocks is enabled, Page Builder changes in the admin panel. Instead of one unified block list, the store owner gets two separate zones:

• "Blocks above content" - The top draggable list where blocks to display before placing the main content of the page.
• A visual divider - The text "Main page content" is clearly displayed between the two zones, so the store owner always knows where their own content is rendered.
• "Blocks below the content" - The bottom draggable list for blocks to be displayed after the main content.

Blocks can be freely dragged between the two zones with drag-and-drop. Position data is saved automatically, so the store owner doesn't have to think about the technique - just drag the blocks to where they make sense.

Template implementation

In the theme's Smarty templates, two separate variables are used to render the blocks: $page_blocks_top and $page_blocks_bottom. These are automatically filled by Shoporama based on the position of the blocks.

All you need to do as a theme developer is to include them in the right places in your template:

<!-- Blocks above the content --> <{includefile="components/page-blocks.html" blocks=$page_blocks_top}><!-- Main page content here--> <!-- Blocks below the content --> <{includefile="components/page-blocks.html" blocks=$page_blocks_bottom}>

Both calls use the same components/page-blocks.html component- it doesn't know if it renders top or bottom blocks, it just renders the blocks it gets. This makes implementation simple and consistent.

Complete example: category.html

Here is a complete example of a category page using split_blocks. Notice how the blocks wrap around the actual category content:

<div id="main" class="pb-12"> <!-- Top blocks: hero banners, promotions, USP section --><{include file="components/page-blocks.html" blocks=$page_blocks_top}> <!-- Breadcrumbs --><div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-4"> <{include file="components/breadcrumbs.html"}> </div> <!-- Category products, filtering, etc. --><div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8"> <{include file="components/category-content.html"}> </div> <!-- Bottom blocks: recommendations, newsletter, Instagram --><{include file="components/page-blocks.html" blocks=$page_blocks_bottom}> </div>

The pattern is the same across all page types - product, page, blog post, search, cart, checkout and user profile. Place top blocks before the main content and bottom blocks after. That's all.

When do split_blocks make sense?

Split_blocks are relevant for most modern themes, but here are some situations where it's particularly valuable:

• Category pages with hero banners - The store owner can place a promotional banner above the product list and complementary content below it.
• Product pages with related content - Recommendations and cross-selling below the product information, while a promotional message appears at the top.
• Front page - Full control over what appears before and after the main content without having to edit templates.
• Checkout flow - Trust markers and USP sections above the checkout form, and support information below it.

If your theme only has blocks in one place (e.g. only below the content), split_blocks is not necessary. But as soon as the store owner needs to place content around the main content, it's the right solution.

To summarize

With split_blocks, you give the store owner control over block placement on all pages - without them having to edit code. The implementation requires one line in theme_settings.json and two includes in each template. It's a small effort with a big impact on store layout flexibility.

Read more about Page Builder and how to implement Theme Builder in your theme. See also our post on accordion layout for theme settings for another useful theme_settings.json function.