WireMarkupRegions

The Markup Regions system is driven by pw-* attributes in your template output. No PHP calls to WireMarkupRegions are needed — you just output HTML with these attributes and ProcessWire handles the rest.

Actions via pw-* attributes

<!-- Replace the #content region entirely -->
<div pw-replace="content"><p>New content here</p></div>
<!-- or: match by id attribute on the element itself -->
<div id="content" pw-replace><p>New content</p></div>

<!-- Append to #content -->
<p pw-append="content">This paragraph gets appended.</p>

<!-- Prepend to #content -->
<p pw-prepend="content">This paragraph gets prepended.</p>

<!-- Insert before the #sidebar element -->
<aside pw-before="sidebar">Goes before sidebar</aside>

<!-- Insert after the #sidebar element -->
<aside pw-after="sidebar">Goes after sidebar</aside>

<!-- Remove the #promo region entirely -->
<div pw-remove="promo"></div>

Merging attributes onto the target

When you include other attributes on a region element, they are merged onto the target element in the layout — not just applied to your inserted content:

<!-- Append content AND add class "has-sidebar" to #main in the layout -->
<div id="main" class="has-sidebar" pw-append>
    <aside>Sidebar content</aside>
</div>

<!-- Append content AND remove class "no-js" from #body in the layout -->
<div id="body" class="-no-js" pw-append></div>

Prefix a class name with - to remove it from the target.

Optional regions

Mark a region with pw-optional (or data-pw-optional) to have it automatically removed from the final output if it ends up empty:

<div id="promo" pw-optional>
    <?php if($page->promo_text): ?>
        <p><?= $page->promo_text ?></p>
    <?php endif ?>
</div>

mergeTags($htmlTag, $mergeTag)

Merge attributes from one HTML tag string into another. The tag name from $htmlTag is kept; class attributes are merged (not replaced); other attributes in $mergeTag are added or overwrite those in $htmlTag.

$tag = $regions->mergeTags(
    '<div id="main" class="old">',
    '<div class="new extra" title="hello">'
);
// '<div id="main" class="old new extra" title="hello">'

Class merge operators:

// Add a class (force-add even if previously removed)
$regions->mergeTags($tag, '<div class="+highlight">');
// Remove a class
$regions->mergeTags($tag, '<div class="-old-class">');
// Remove all classes matching a prefix
$regions->mergeTags($tag, '<div class="-col-*">');

getTagInfo($tag)

Parse an HTML opening tag and return an info array including name, id, pwid, classes, attrs, action, actionTarget, and close.

$info = $regions->getTagInfo('<div id="main" class="wrap" pw-append>');
// ['name' => 'div', 'id' => 'main', 'action' => 'append', 'actionTarget' => 'main', ...]

renderAttributes($attrs, $encode, $quote)

Render an associative array as an HTML attribute string. Boolean true values render as standalone attributes (e.g. checked); array values are joined with spaces.

$str = $regions->renderAttributes(['id' => 'main', 'class' => 'wrap', 'checked' => true]);
// 'id="main" class="wrap" checked'

hasAttribute($name, $value, &$html)

Check whether an HTML attribute appears anywhere in the given markup.

if($regions->hasAttribute('id', 'main', $html)) { ... }
if($regions->hasAttribute('class', 'sidebar', $html)) { ... }

removeRegionTags(&$html)

Remove <region> and <pw-region> wrapper tags from markup and strip pw-id / data-pw-id attributes from remaining tags. Returns true when the markup changed.

if($regions->removeRegionTags($html)) {
    // $html was modified in place
}

hasRegions(&$html) / hasRegionActions(&$html)

Fast checks for markup that contains region identifiers or pw-* actions.

if($regions->hasRegions($html)) { ... }
if($regions->hasRegionActions($html)) { ... }

stripRegions($tag, $markup, $getRegions)

Strip non-nested tags (comments, scripts, styles) from markup, or extract them.

$clean    = $regions->stripRegions('<!--', $markup);      // remove HTML comments
$clean    = $regions->stripRegions('<script', $markup);   // remove script tags
$stripped = $regions->stripRegions('<!--', $markup, true); // extract comments instead

stripOptional($markup)

Remove elements with pw-optional / data-pw-optional that are empty; strip the attribute from non-empty ones.

$clean = $regions->stripOptional($markup);

• Source file: wire/core/Tools/WireMarkupRegions/WireMarkupRegions.php
• Enable with $config->useMarkupRegions = true in /site/config.php.
• Template output before <!DOCTYPE> is treated as region updates; output after is the layout document.
• pw-id and data-pw-id attributes work like id for region targeting, without affecting the rendered DOM id.
• All pw-* action attributes are stripped from the final output.
• <!--#name--> HTML comments serve as fast-match hints for closing tags, improving parsing performance on large documents.
• Single-use tags (<html>, <head>, <body>, <title>, <main>, <base>) can be targeted by tag name alone without an id.
• The ^ prefix on an action target (pw-append="^footer") matches by tag name rather than id.