> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pureclarity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Adding Zones Using HTML

> Direct template integration of PureClarity zones using HTML tags in Magento 2.x theme templates

For precise zone placement that can't be achieved with standard widgets, you can add PureClarity zones directly to your theme templates using HTML tags. The HTML syntax varies depending on your display mode configuration.

## Before You Begin

Check your PureClarity display mode setting in **Stores > Configuration > PureClarity > Mode** to determine which HTML syntax to use.

<Note>
  Direct HTML integration requires theme customization and should be performed by developers familiar with Magento theme structure.
</Note>

## HTML Syntax by Mode

### Client-Side Mode HTML

For installations using **client-side** display mode:

```html theme={null}
<div data-pureclarity="bmz:ZONE-ID;"></div>
```

**Characteristics:**

* **Minimal markup** required
* **JavaScript-driven** content insertion
* **Asynchronous loading** of recommendations
* **PureClarity-managed** templates and styling

### Server-Side Mode HTML

For installations using **server-side** display mode:

```html theme={null}
<div data-serverside-pureclarity="bmz:ZONE-ID" 
     data-pureclarity-bmz-id="ZONE-ID" 
     class="pc_bmz" />
```

**Characteristics:**

* **Multiple attributes** for server processing
* **Magento-rendered** content
* **Custom template** control
* **Server-side** data integration

<Warning>
  Using the wrong HTML syntax for your mode will prevent zones from displaying. Always verify your configuration mode before implementing HTML zones.
</Warning>

## Zone ID Configuration

### Zone ID Format

Replace `ZONE-ID` in the HTML examples with your actual PureClarity zone identifier:

**Examples:**

* Homepage hero: `HP-01`
* Category page recommendations: `CAT-01`
* Product page cross-sells: `PDP-01`
* Search results: `SR-01`

### Zone ID Best Practices

* **Use descriptive naming** - Clear identification of zone purpose
* **Maintain consistency** - Standardized naming across your site
* **Document zone mapping** - Keep records of zone placements
* **Coordinate with campaigns** - Ensure zone IDs match PureClarity admin

<Tip>
  Zone IDs must exactly match the zone identifiers configured in your PureClarity campaigns. Mismatched IDs will result in empty zones.
</Tip>

## Template Integration Locations

### Common Integration Points

**Theme Files:**

* `app/design/frontend/[Vendor]/[theme]/Magento_Catalog/templates/`
* `app/design/frontend/[Vendor]/[theme]/Magento_Checkout/templates/`
* `app/design/frontend/[Vendor]/[theme]/Magento_Cms/templates/`

**Typical Placements:**

* **Homepage sections** - In CMS page templates
* **Category pages** - In category view templates
* **Product pages** - In product detail templates
* **Cart/Checkout** - In shopping cart templates

### Example Integrations

#### Homepage Hero Zone

```html theme={null}
<!-- In CMS page template or homepage.phtml -->
<div class="hero-section">
    <div data-pureclarity="bmz:HP-01;"></div>
</div>
```

#### Category Page Recommendations

```html theme={null}
<!-- In category/view.phtml -->
<div class="category-recommendations">
    <div data-pureclarity="bmz:CAT-01;"></div>
</div>
```

#### Product Page Cross-Sells

```html theme={null}
<!-- In catalog/product/view.phtml -->
<div class="product-recommendations">
    <div data-pureclarity="bmz:PDP-01;"></div>
</div>
```

## Advanced HTML Integration

### Conditional Zone Display

```html theme={null}
<?php if ($block->isZoneEnabled('HP-01')): ?>
    <div class="homepage-zone">
        <div data-pureclarity="bmz:HP-01;"></div>
    </div>
<?php endif; ?>
```

### Responsive Zone Implementation

```html theme={null}
<!-- Desktop zone -->
<div class="hidden-xs">
    <div data-pureclarity="bmz:HP-01-DESKTOP;"></div>
</div>

<!-- Mobile zone -->
<div class="visible-xs">
    <div data-pureclarity="bmz:HP-01-MOBILE;"></div>
</div>
```

### Fallback Content

```html theme={null}
<div class="zone-container">
    <div data-pureclarity="bmz:HP-01;"></div>
    
    <!-- Fallback content if PureClarity is unavailable -->
    <div class="fallback-content" style="display: none;">
        <?php echo $block->getFallbackContent(); ?>
    </div>
</div>
```

<Note>
  Fallback content provides a backup when PureClarity services are unavailable, ensuring your site maintains functionality and appearance.
</Note>

## CSS Styling Considerations

### Zone Container Styling

```css theme={null}
.zone-container {
    min-height: 200px;
    margin: 20px 0;
    position: relative;
}

/* Loading state */
.zone-container[data-pureclarity]:empty::before {
    content: "Loading recommendations...";
    position: absolute;
    top: 50%;
    left: 50%;
    transform: translate(-50%, -50%);
    color: #999;
}
```

### Responsive Design

```css theme={null}
@media (max-width: 768px) {
    .zone-container {
        margin: 10px 0;
        min-height: 150px;
    }
}
```

### Theme Integration

```css theme={null}
/* Match your theme's existing styles */
.zone-container {
    background: var(--theme-background);
    border-radius: var(--theme-border-radius);
    padding: var(--theme-spacing);
}
```

## Performance Optimization

### Lazy Loading Zones

```html theme={null}
<div data-pureclarity="bmz:HP-01;" 
     data-lazy="true" 
     data-threshold="200">
</div>
```

### Preload Critical Zones

```html theme={null}
<!-- Preload important zones for faster rendering -->
<link rel="preload" href="//[region].pureclarity.net/api/bmz/HP-01" as="fetch">
```

### Minimize Layout Shift

```css theme={null}
.zone-container {
    /* Reserve space to prevent layout shift */
    min-height: 250px;
    width: 100%;
}
```

<Warning>
  Layout shifts can negatively impact user experience and Core Web Vitals scores. Always reserve appropriate space for zone content.
</Warning>

## Testing HTML Integration

### Validation Checklist

* [ ] **Syntax verification** - Correct HTML for your mode
* [ ] **Zone ID accuracy** - Matches PureClarity campaign configuration
* [ ] **Template compilation** - No Magento compilation errors
* [ ] **Content loading** - Zones display recommendations correctly
* [ ] **Responsive behavior** - Works across all device sizes
* [ ] **Fallback functionality** - Graceful degradation when needed

### Debug Mode Testing

Enable [Zone Debug Mode](/integrations/magento/magento-2/zone-debug) to visualize zone placement:

1. **Enable debug mode** in PureClarity configuration
2. **Clear Magento cache** to apply changes
3. **Visit pages** with HTML zones
4. **Verify zone placement** and identifiers

## Common Implementation Issues

### Zone Not Displaying

**Troubleshooting steps:**

1. **Verify HTML syntax** matches your configuration mode
2. **Check zone ID** in both template and PureClarity admin
3. **Clear all caches** (layout, blocks, page cache)
4. **Confirm template compilation** without errors
5. **Test with debug mode** enabled

### Incorrect Content

**Possible causes:**

* **Zone ID mismatch** between template and campaigns
* **Mode configuration** doesn't match HTML syntax
* **Campaign inactive** or incorrectly configured
* **Feed data** out of sync

### Performance Issues

**Optimization strategies:**

* **Minimize zone count** on single pages
* **Use appropriate caching** strategies
* **Implement lazy loading** for below-fold zones
* **Monitor server impact** for server-side mode

## Maintenance Best Practices

### Version Control

* **Track template changes** in version control systems
* **Document zone additions** and modifications
* **Test across environments** before production deployment
* **Maintain rollback capabilities** for problematic changes

### Regular Auditing

* **Review zone performance** quarterly
* **Validate zone placement** after theme updates
* **Check campaign alignment** with business goals
* **Monitor user engagement** with zone content

### Update Procedures

* **Test zone functionality** after Magento updates
* **Verify template compatibility** with new versions
* **Update documentation** when zones are modified
* **Coordinate with marketing** on campaign changes

## Related Resources

### Alternative Integration Methods

* [Adding Zones Using Widgets](/integrations/magento/magento-2/adding-zones-widgets) - GUI-based zone placement
* [Default Zone Installation](/integrations/magento/magento-2/default-zone-installation) - Standard zone setup

### Configuration Guides

* [Configuration Mode](/integrations/magento/magento-2/configuration-mode) - Understanding client-side vs server-side
* [Zone Debug Mode](/integrations/magento/magento-2/zone-debug) - Troubleshooting zone placement

### Advanced Topics

* [Server-Side Mode](/integrations/magento/magento-2/serverside) - Advanced server-side implementation
* [Custom Templates](/features/templates/creating-templates) - PureClarity template customization