Hook Elements

warning

If you enable PHP execution in a Hook Element, treat it like production code: validate, escape output, and test on staging.

Hook Elements Explained

Field	What it controls	Why you care
Hook location	Where the element runs (before header, after entry, etc.)	Determines placement
Priority	Order vs other callbacks	Prevents duplicates and conflicts
Display rules	Where it appears	Avoids site-wide accidents
Content	HTML/blocks/PHP (depending on config)	Output and security

Why It Matters

• Fast customization: you can ship small changes without touching theme code.
• Scoped changes: display rules keep output where you want it.
• Debuggable: you can correlate output to a hook name and a rule.

How It Works

GeneratePress fires generate_* hooks via do_action(). GP Premium registers an element callback onto that hook and only renders it when display rules match.

flowchart LR
  HOOK["do_action('generate_*')"] --> RULES[Display rules check]
  RULES -->|match| OUT[Hook Element output]
  RULES -->|no match| SKIP[No output]

Practical Walkthrough

Step 1: Find the Hook Point in the Theme

find-hook-point-in-theme.sh

cd /var/www/html/wp-content/themes/generatepress
grep -R "do_action( 'generate_" -n inc templates | head -n 60

Step 2: Confirm Default Callbacks (So You Know What You Are Extending)

find-default-hook-callbacks.sh

cd /var/www/html/wp-content/themes/generatepress
grep -R "add_action( 'generate_" -n inc | head -n 60

Step 3: Audit Existing Hook Elements (Optional)

list-hook-elements.sh

cd /var/www/html
wp post list --post_type=gp_elements --fields=ID,post_title,post_status --format=table 2>/dev/null || true

Step 4: Validate a Specific Hook Name Exists

validate-hook-name.sh

cd /var/www/html/wp-content/themes/generatepress

# Example: confirm the hook is present in the theme
grep -R "do_action( 'generate_before_header'" -n inc templates | head -n 20

Practical Examples

Example 1: Add an Announcement Bar Above the Header

Hook location: generate_before_header

Content (HTML):

Hook Element content

<div class="gp-announcement">Scheduled maintenance: Sunday 02:00 UTC</div>

Display rules: Home page only (start narrow).

Common hook locations (examples):

Region	Hook examples	Typical use
Header	generate_before_header, generate_after_header	Notices, breadcrumbs, secondary nav
Content	generate_before_main_content, generate_after_entry_content	CTAs, inline promos
Footer	generate_before_footer, generate_footer, generate_after_footer	Credits, links, small banners

Example 2: Insert Verification/Tracking Code Safely

Hook location: wp_head (or a GeneratePress header hook)

caution

Do not paste untrusted scripts. Third-party scripts can slow pages and create security risk.

Example 3: Debug a Hook Placement

If you are not sure where a hook appears, temporarily output a labeled marker.

Temporary debug marker

<div style="border:2px dashed red;padding:8px">HOOK DEBUG: generate_after_header</div>

Best Practices

Practice	Why
Start with narrow display rules	Prevents accidental global output
Prefer Block Elements for complex sections	Better editing and fewer HTML mistakes
Keep hook output lightweight	Hooks run on many pages
Document the hook name + intent	Faster future maintenance
Escape dynamic output	Prevent XSS and broken HTML
Avoid large inline CSS blocks	Keep CSS in files where it can be cached

Troubleshooting

Symptom	Cause	Fix
Element appears in the wrong place	Wrong hook location	Confirm with grep where the hook fires
Element not visible	Rule mismatch or caching	Widen rules temporarily, purge LSCache
Duplicate output	Two elements on same hook	Audit element inventory and priorities
Broken layout	Missing wrapper styles	Add minimal CSS and validate on mobile
PHP output errors	PHP disabled or syntax error	Disable PHP execution, validate code, and check error logs

Hands-On

1. Pick one hook near the header and confirm where it fires in inc/structure/header.php.
2. Create a Hook Element that outputs a small banner on one test page.
3. Disable the element and confirm it disappears (proving rollback).
4. Move the same banner to a different hook and document the difference in placement.

Quick Reference

hook-elements-cheatsheet.sh

cd /var/www/html/wp-content/themes/generatepress
grep -R "do_action( 'generate_" -n inc/structure/header.php | head

What's Next

• Next: Block Elements
• Related: Global Layout Framework