Bonsai Popup

A lightweight WordPress plugin by The Bonsai Digital Collective that displays a randomly selected promotional popup on the homepage on every visit. Manage multiple popups from the WordPress backend with per-popup active toggles and global display settings.

Features

• Custom post type — create as many popups as you need
• Each popup supports: title, body content (basic HTML), CTA button with optional new-tab, and an image
• Per-popup Active toggle — disable without deleting
• Popup shows on every homepage visit — no session suppression
• Show on mobile setting — hide below 480px when unticked (tablets and above always see the popup)
• Configurable show delay and overlay opacity via Settings page
• Keyboard accessible — Escape to close, focus moves to modal on open
• Neutral default styling — easily overridden in your theme CSS

Requirements

• WordPress 5.8+
• PHP 7.4+

Installation

1. Clone or download this repository into /wp-content/plugins/bonsai-popup/
2. Activate Bonsai Popup in WordPress Admin → Plugins
3. Go to Popups in the admin sidebar
4. Click Add New Popup and fill in the details
5. Publish the popup
6. Visit the homepage — the popup appears after the configured delay

Usage

Adding a Popup

Settings (Popups → Settings)

Customising Styles

The plugin outputs neutral styles from assets/popup.css. Override in your theme:

/* Example: theme-specific accent colour */
#bdc-popup-modal .bdc-popup-cta {
    background: #your-colour;
}
#bdc-popup-modal .bdc-popup-title {
    color: #your-heading-colour;
}

Key selectors:

Updates

Ships with YahnisElsts/plugin-update-checker (installed via Composer, vendor/ committed) pointed at the private repo github.com/Bonsai-Systems/bonsai-pop-up, tracking the main branch.

Because the repo is private, the update checker needs a GitHub token to fetch releases. Add this to the site's wp-config.php (never commit it to the plugin):

define( 'BDC_POPUP_GITHUB_TOKEN', 'github_pat_xxxxxxxxxxxxxxxxxxxxxxxx' );

Use a fine-grained token scoped to Contents: read-only on the bonsai-pop-up repo only. Without this constant defined, the plugin still works — it just won't check for updates.

To ship a new version:

1. Bump the Version: header and BDC_POPUP_VERSION constant in bonsai-popup.php, and add a CHANGELOG.md entry.
2. Commit and push to main.
3. Publish a GitHub Release tagged with the new version (release-assets mode is enabled, so attach a zip of the plugin folder — plain source-archive tags won't be picked up).

Sites check for updates on the default schedule, or immediately if an admin clicks "Check again" on the Plugins screen.

Project Structure

bonsai-popup/
├── bonsai-popup.php       # Main plugin file — CPT, meta box, settings, enqueue, update checker
├── assets/
│   ├── popup.css          # Frontend styles
│   └── popup.js           # Frontend popup logic
├── vendor/                # Composer dependencies (plugin-update-checker), committed
├── composer.json
├── CHANGELOG.md
└── README.md

Changelog

See CHANGELOG.md for full version history.

License

GPL-2.0+