Geo Conditions

Geolocation-based element conditions, dynamic data tags, and geo-targeted content blocks for WordPress.

Built first-class for Bricks Builder — with full support for Element Conditions, Dynamic Data tags, and a cache-safe AJAX content system that works with any page cache plugin.

Features

• 🌍 Bricks Element Conditions — show/hide elements by country, region, or city
• 🏷️ Bricks Dynamic Tags — {geo_country}, {geo_city}, {geo_content:slug}, and more
• 📦 Geo Content Blocks — CPT-based geo-targeted content with country rules and a fallback
• ⚡ Cache-safe AJAX — works with WP Rocket, LiteSpeed, W3TC, and any full-page cache
• 🔍 Smart detection chain — Cloudflare → Bunny.net → IP2Location.io (configurable priority)
• 🍪 Cookie caching — visitor geo is stored in a browser cookie, skipping detection on repeat loads
• 🌐 Searchable country picker — Select2 multi-select with all 195 countries

Detection Chain

Geo is resolved in priority order (configurable in Settings):

Results are cached as WordPress transients (per IP) and as a browser cookie, so detection runs at most once per visitor per session.

Best setup: If you're on Cloudflare (even the free plan), no API key is needed. Geo headers are added automatically.

Bricks Builder Integration

Element Conditions

Go to any element → Conditions → add a condition set → select the Geolocation group.

⚠️ Bricks evaluates element conditions server-side on initial render. For cached sites, use the AJAX approach below.

Dynamic Data Tags

Use in any Bricks text, heading, or dynamic data field:

{geo_country}           → KW
{geo_country_name}      → Kuwait
{geo_region}            → Al Ahmadi
{geo_city}              → Ahmadi
{geo_source}            → cloudflare
{geo_content:my-slug}   → rendered geo content block HTML

Geo Content Rules

Go to Geo Conditions → Content Rules → Add New.

Each rule set has:

• A slug used in shortcodes and dynamic tags
• An ordered list of rules, each with selected countries and HTML content
• Rules are evaluated top-to-bottom — first country match wins
• The first row is always the Default / Fallback — shown when no rule matches

Rendering content blocks

PHP (not cache-safe):

[geo_content id="homepage-banner"]

AJAX (cache-safe, recommended):

[geo_content id="homepage-banner" ajax="1" placeholder="Loading…"]
[geo_content_ajax id="homepage-banner" placeholder="Loading…"]

HTML data attribute (cache-safe, works anywhere):

<div data-geo-content="homepage-banner"></div>

Cache-Safe AJAX System

geo-loader.js runs immediately on page load and:

1. Checks the browser cookie — if fresh and no dynamic elements, skips AJAX entirely
2. Collects all [data-geo-content] and [data-geo-condition] elements on the page
3. Fires a single batched POST to admin-ajax.php
4. Swaps in content HTML and applies show/hide visibility

Because admin-ajax.php is always excluded from page caches, this works transparently with any caching setup.

Element visibility via data attribute

<!-- Show only for US visitors -->
<div data-geo-condition='{"type":"country","compare":"==","value":"US"}'>
    US-only content
</div>

<!-- Hide for a list of countries -->
<div data-geo-condition='{"type":"country","compare":"not_in","value":"DE,FR,IT"}'>
    Non-EU content
</div>

<!-- Region-based -->
<div data-geo-condition='{"type":"region","compare":"contains","value":"California"}'>
    California content
</div>

JS events

// Fires when a geo content block is populated
el.addEventListener('geoContentLoaded', e => {
    console.log('Geo:', e.detail.geo);
});

// Fires when visibility is resolved
el.addEventListener('geoVisibilityResolved', e => {
    console.log('Visible:', e.detail.visible);
});

Shortcodes

PHP API

// Global helper — get full geo array
$geo = geo_conditions_get_geo();
// [
//   'country_code' => 'KW',
//   'country_name' => 'Kuwait',
//   'region'       => 'Al Ahmadi',
//   'city'         => 'Ahmadi',
//   'source'       => 'cloudflare',
// ]

// Direct class access
$code = \GeoConditions\Geo_Detector::instance()->get_country_code();
$city = \GeoConditions\Geo_Detector::instance()->get_city();

Settings

Geo Conditions → Settings

• Detection priority — drag to reorder Cloudflare / Bunny / IP2Location
• IP2Location API key — free at ip2location.io, 30k queries/month
• Server cache duration — transient TTL per IP (default: 60 minutes)
• Browser cookie duration — how long the geo cookie is kept (default: 24 hours)
• Debug mode — shows a geo info bar at the bottom of every page (admins only)
• Flush cache — clears all server-side transients instantly

Requirements

Bricks Builder is optional — all other features (shortcodes, AJAX content, data attributes) work with any theme or builder.

Installation

1. Upload the geo-conditions folder to /wp-content/plugins/
2. Activate via Plugins → Installed Plugins
3. Go to Geo Conditions → Settings
4. Set your detection priority and (optionally) your IP2Location API key
5. Create your first content rule at Geo Conditions → Content Rules

File Structure

geo-conditions/
├── geo-conditions.php                  Bootstrap, constants, autoloader
├── readme.txt                          WordPress.org readme
├── README.md                           This file
├── includes/
│   ├── class-geo-detector.php          Detection chain + cookie/transient cache
│   ├── class-geo-cache.php             Transient cache manager
│   ├── class-ajax-handler.php          AJAX endpoint (content + visibility)
│   ├── class-geo-content-manager.php   Geo Content CPT, rules, rendering
│   ├── class-bricks-conditions.php     Bricks Element Conditions integration
│   ├── class-bricks-dynamic-tags.php   Bricks Dynamic Data tags
│   ├── class-elementor-integration.php Elementor dynamic tags
│   ├── class-shortcode.php             Shortcode handlers
│   └── class-settings-page.php         Admin settings UI
└── assets/
    ├── js/geo-loader.js                Frontend AJAX loader
    ├── js/geo-admin.js                 Admin JS utilities
    ├── css/geo-conditions.css          Frontend CSS (loading states)
    └── css/geo-conditions-admin.css    Admin CSS

Builder Support

License

GPL-2.0-or-later

Built by Nahnu Plugins