Conditional Layouts

Conditional layouts let you keep your site consistent while still shipping special experiences where they matter: landing pages, category hubs, product templates, and membership content.

In GeneratePress, your main tools are:

• Elements display rules (UI-driven targeting)
• WordPress conditionals (code-driven targeting)

Know Your Element Types

GeneratePress Elements come in different "shapes" (and they show up in different places). Before you write rules, be clear about the job.

Element type	Typical use	Risk if misused
Hook	Inject small markup/code at a hook	Duplicate output if multiple rules match
Layout	Change layout settings by context	Conflicts if rules overlap
Header	Replace/adjust header area	Navigation regressions if not tested
Block	Insert a block-based section conditionally	Spacing inconsistency if not scoped

note

Keep each Element narrow. A "do everything" Hook Element becomes hard to debug.

The Mental Model: A Rule Stack

If you add many Elements, think in layers:

1. Global components (sitewide header/footer helpers)
2. Template components (archives, posts, pages)
3. Contextual overrides (one category, one page, one post type)

flowchart TD
  A[Global Elements] --> B[Template Elements]
  B --> C[Specific Overrides]
  C --> D[Single-page Exceptions]

caution

Avoid overlapping rules that both "match" the same page. When multiple Elements compete for the same area, you get duplicated output or inconsistent spacing.

Naming and Rule Hygiene

Treat Elements like a small component system:

• Use a prefix in titles (for example: CTA:, Banner:, Schema:)
• Put the target in the name (for example: CTA: Posts (after content))
• Keep a short note in the Element about intent and exclusions

This makes it obvious why something exists when you revisit the site in six months.

Common Targeting Patterns

Goal	Use	Example
Add a promo banner sitewide	Element display rules	Show on entire site, exclude checkout
Add a CTA after blog posts	Element rules + location	Show on posts, not pages
Change layout for one category	Display rules	Only on category/tutorials archives
Add code to one page template	PHP conditional	is_page_template() guard

PHP Conditionals (When You Need Code)

Keep conditionals simple and explicit.

Example: only run on blog posts (not pages)

<?php
if ( ! is_singular( 'post' ) ) {
    return;
}

// Output or enqueue something post-specific here.

Example: exclude WooCommerce checkout from a global banner

<?php
if ( function_exists( 'is_checkout' ) && is_checkout() ) {
    return;
}

echo '<div class="site-banner">Free shipping this week</div>';

tip

If you can express the targeting using Element display rules, prefer that. It's easier to audit later than scattered conditionals across files.

Debugging Display Rules

When an Element does not show up, it's usually one of:

• Location is wrong (hook or placement)
• Display rules don't match the current URL
• Another Element is outputting the same thing

Quick debug tactic: add a temporary marker.

Temporary marker to confirm an Element runs

<!-- element: blog-cta / location: after_content -->

If you have WP-CLI access, listing Elements helps you see how many you're managing:

WP-CLI: list GeneratePress Elements (if available)

cd /var/www/example.com/public_html
wp post list --post_type=gp_elements --fields=ID,post_title,post_status || true

tip

When debugging overlap, temporarily disable one Element at a time (draft status) and refresh the target page. This is often faster than guessing which rule is matching.

Hands-On: Build Two Conditional Elements

1. Create an Element that adds a CTA after blog posts.
2. Create a second Element that adds a different CTA on a single category archive.
3. Confirm the category archive does not show the blog-post CTA.

Stretch goal: add an exclusion so your post CTA does not appear on a specific post (for example, the homepage announcement post).

Troubleshooting

Symptom	Likely cause	Fix
Element appears twice	Two Elements match the same page	Tighten rules; remove overlap
Element never appears	Wrong location/hook	Move to a known-good hook/location
Exclusions don't work	Rule is too broad	Use more specific include rules + explicit excludes

Quick Reference

• Layer Elements: global -> template -> specific
• Prefer display rules; use PHP for special cases
• Avoid overlapping targets

What's Next

• Next: Reusable Components