Skip to main content

Customizer Integration

warning

Changing defaults via filters can surprise editors because the Customizer UI may show one value while runtime filters force another. Document any forced defaults.

Customizer Integration Explained​

Customizer conceptWhat it isCLI view
Theme modsSaved Customizer values for a themewp option get theme_mods_generatepress
DefaultsFallback values when mods are missingDefaults files + filters
Export/importMove settings between environmentswp customizer export/import (if available)

Why It Matters​

  • Customizer settings are part of your "config" and should be reproducible.
  • Child themes often need to align CSS and components with Customizer tokens.
  • Auditing theme mods helps explain layout drift between environments.

How It Works​

GeneratePress registers Customizer settings from config files. When saved, WP stores them as theme mods. The theme reads mods and outputs CSS/markup.

flowchart LR
  CFG[Customizer configs] --> SAVE[Save]
  SAVE --> MODS[(Theme mods)]
  MODS --> OUT[CSS/markup output]

Practical Walkthrough​

Step 1: Dump Theme Mods for Audit​

dump-theme-mods.sh
cd /var/www/html
wp option get theme_mods_generatepress --format=json > /tmp/theme_mods_generatepress.json
grep -n "container\|sidebar\|font\|color" /tmp/theme_mods_generatepress.json | head -n 80

Step 2: Locate the Config Files (Reference)​

locate-customizer-configs.sh
cd /var/www/html/wp-content/themes/generatepress
ls inc/customizer/configs | head -n 40

Step 3: Search for Defaults and Filters​

search-defaults-and-filters.sh
cd /var/www/html/wp-content/themes/generatepress
grep -R "defaults\|apply_filters" -n inc/defaults.php inc/customizer 2>/dev/null | head -n 80

Step 4: Check for Export/Import Commands​

check-customizer-wp-cli.sh
cd /var/www/html
wp help customizer 2>/dev/null || echo "No wp customizer command found"

Step 5: Locate the Default Settings Layer​

locate-default-settings-layer.sh
cd /var/www/html/wp-content/themes/generatepress
ls inc | grep defaults || true
grep -R "defaults" -n inc/defaults.php inc/customizer 2>/dev/null | head -n 80

Practical Examples​

Example 1: Diff Theme Mods Before/After a Change​

diff-theme-mods.sh
cd /var/www/html
wp option get theme_mods_generatepress --format=json > /tmp/theme_mods.A.json

# Make one change and save, then:
wp option get theme_mods_generatepress --format=json > /tmp/theme_mods.B.json

diff -u /tmp/theme_mods.A.json /tmp/theme_mods.B.json | head -n 120

Example 2: Export/Import (If Available)​

export-import-customizer.sh
cd /var/www/html
wp customizer export > gp-customizer.json
wp customizer import gp-customizer.json
caution

Import on staging first. A bad import can change layout, colors, and typography site-wide.

Example 3: Override a Default Value (Pattern)​

If you need to force a default, first find the filter name in the parent theme with grep. Then implement the filter in the child theme.

wp-content/themes/generatepress-child/inc/filters.php
<?php

// Pattern only: replace filter name and array keys with real ones found via grep.
// add_filter( 'generate_some_defaults_filter', function( $defaults ) {
//     $defaults['container_width'] = 1100;
//     return $defaults;
// } );

Best Practices​

PracticeWhy
Treat theme mods like configReproducible environments
Keep exports in deployment artifactsFaster recovery
Avoid forcing defaults without docsPrevents editor confusion
Purge cache after changesLSCache may serve stale output
Keep a settings changelogHelps audits and migrations

Troubleshooting​

SymptomCauseFix
Changes not visibleCachePurge LSCache and test logged-out
Theme mods emptyWrong option keyList options: `wp option list
UI shows value but output differsRuntime filter overrideDocument the filter and remove if unnecessary

Hands-On​

  1. Export theme mods to /tmp/theme_mods_generatepress.json.
  2. Change one setting and diff before/after.
  3. Store a gp-customizer.json export if available.
  4. Locate the setting definition in inc/customizer/configs/ for one key you changed.

Quick Reference​

customizer-integration-cheatsheet.sh
cd /var/www/html
wp option get theme_mods_generatepress --format=json | head

What's Next​