You can add PureClarity zones anywhere on your Magento site using the built-in widget system. The PureClarity extension adds a “PureClarity Zone” widget type that provides flexible zone placement options.

​
Zone Widget Configuration Options

​
Zone ID

The unique identifier for the zone that must match your campaign configuration in PureClarity admin. If no matching campaigns exist, no content will display.

​
Fallback Block ID

Optional static block to display if PureClarity doesn’t populate the zone when the page renders.
To find block IDs, navigate to Content > Blocks in Magento admin and check the “Identifier” column.
Magento CMS blocks listing showing identifier column

​
Zone Display Mode

Controls device targeting for the zone: PureClarity Widget Zone Display mode options
  • Default - Display on all devices
  • Mobile Only - Display only on mobile devices
  • Desktop Only - Display only on desktop devices
The description for “Desktop Only” in the original article appears to be incorrect (it said “mobile devices”). Desktop Only mode displays content only on desktop devices.

​
Apply Margin

When enabled, adds 10px margin above and below the zone content area for better visual spacing.

​
CSS Custom Classes

Add custom CSS classes to help the zone integrate with your theme styling.

​
Step-by-Step Widget Creation

​
Example: Adding a Search Results Zone

Let’s walk through adding a zone to the search results page:

​
1. Navigate to Widget Management

Go to Content > Widgets and click “Add Widget”. Add Widget button at the top of the Widget list

​
2. Select Widget Type

Choose “PureClarity Zone” from the Type dropdown. Widget setup page with type and design theme options

​
3. Select Design Theme

Choose your active theme from the Design Theme dropdown.
The theme must match the one active on the store view where PureClarity is installed.

​
4. Continue to Configuration

Click “Continue” to proceed to the detailed configuration. Completed Widget setup page

​
5. Configure Storefront Properties

Storefront Properties overview Widget Title: Add a descriptive title for reference (e.g., “PC Zone SR-01” for Search Results Zone) Assign to Store Views: Select the store view where PureClarity is installed Sort Order: Set priority if multiple widgets occupy the same position Storefront properties filled in as per example

​
6. Configure Layout Updates

Layout updates determine where the widget appears on your site. Layout updates configuration example For our search results example:
  1. Click “Add Layout Update”
  2. Select “Specified Page” from Display on dropdown
  3. Choose “Quick Search Form” from Page dropdown
  4. Select “Before Main Columns” from Container dropdown

​
7. Save the Widget

Click “Save” to create your zone widget. Save button at the top of the Widget create page

​
Cache Management

After creating zone widgets, you must clear specific Magento caches for the zone to appear on your frontend.
Clear these cache types:
  • Layouts
  • Blocks HTML output
  • Page Cache
Navigate to System > Cache Management to clear these caches.

​
Widget Placement Options

​
Common Container Positions

ContainerLocationUse Case
Before Main ColumnsAbove main contentHero zones, announcements
After Main ColumnsBelow main contentRelated products, cross-sells
Sidebar AdditionalRight sidebarRecommendations, promotions
Content TopTop of content areaCategory banners, filters

​
Page-Specific Placements

Page TypeDisplay On SettingCommon Zones
Category PagesCatalog Category ViewCategory recommendations
Product PagesCatalog Product ViewRelated products, cross-sells
Search ResultsQuick Search FormSearch-based recommendations
HomepageCMS Home PageFeatured products, hero content
Cart PageCheckout Cart IndexUpsells, abandoned cart recovery

​
Zone Widget Best Practices

​
Naming Conventions

  • Use descriptive widget titles with zone IDs
  • Include page type in the title (e.g., “PC Zone CAT-01 Category Page”)
  • Maintain consistent naming across your site

​
Performance Considerations

  • Limit widget count - Too many zones can impact page load times
  • Use fallback blocks - Provide content when PureClarity is unavailable
  • Test responsiveness - Verify zones work across all devices

​
Content Strategy

  • Match zone purposes - Align widget placement with campaign goals
  • Consider user flow - Place zones where they enhance user experience
  • Monitor performance - Track zone effectiveness in PureClarity analytics

​
Testing Your Zone Widget

After creating and caching:
  1. Visit the target page to confirm the zone appears
  2. Check device responsiveness if using display mode settings
  3. Verify zone ID matching in PureClarity admin
  4. Test fallback content by temporarily disabling campaigns
If your zone doesn’t appear, enable Zone Debug Mode to see zone placeholders and troubleshoot placement issues.

​
Troubleshooting Widget Issues

​
Widget Not Appearing

  • Clear all relevant caches
  • Verify layout update configuration
  • Check store view assignment
  • Confirm theme selection

​
Zone Content Not Loading

  • Verify zone ID matches campaign configuration
  • Check PureClarity is enabled for the store view
  • Review feed status and data synchronization
  • Test with debug mode enabled

​
Styling Issues

  • Add custom CSS classes to the widget
  • Check theme compatibility
  • Adjust margin settings
  • Review container positioning
For comprehensive zone troubleshooting, see Why Zones Not Showing.