Satori Popup Button

A WordPress block that adds a button or link which opens a popup modal with customizable content. Built for Bedrock + Sage.

How it works

The block is save-based: React outputs the HTML (including data attributes), which is stored in post content. On the frontend, assets/js/popup.js (vanilla JS, separate from the webpack build) reads those attributes to wire open/close behaviour and hover styles. The PHP Block::render() simply returns the saved content. See ARCHITECTURE.md for details.

Features

• Per-page popups – Each block instance has its own popup; no global modal
• Trigger options – Button or link, with custom text, alignment, and border radius
• Color settings – Text, background, hover text, and hover background via theme palette or custom hex
• Popup content – InnerBlocks with Cover block (color/image backgrounds), heading, paragraph, image, buttons
• Popup sizes – Small, medium, large, full width
• Tailwind styling – All styles via Tailwind utilities; no raw CSS
• Accessibility – ARIA attributes, focus trap, Escape to close, backdrop click to close, prefers-reduced-motion

Requirements

• WordPress 6.0+
• PHP 8.0+
• Bedrock-compatible setup
• Block editor (Gutenberg)

Installation

1. Place the plugin in web/app/plugins/satori-popup/
2. Activate via WP Admin → Plugins
3. Run npm install && npm run build inside the plugin directory
4. Add the Popup Button block from the design category in the block inserter

Development

cd web/app/plugins/satori-popup
npm install
npm run build

• npm run build – Compiles block JS (edit/save) and Tailwind CSS
• npm run start – Watches for changes during development

Note: The block uses editorScript (webpack-built) and viewScript (assets/js/popup.js, vanilla JS). Only the editor bundle is built by webpack; popup.js is loaded as-is.

Testing (Cypress E2E)

Cypress end-to-end tests cover block settings, editor behaviour, frontend render, and CTA functionality.

Prerequisites

• A running WordPress site with the plugin activated
• An admin user (set WP_USER and WP_PASSWORD in cypress.env.json)

Setup (required)

1. Copy cypress.env.json.example to cypress.env.json
2. Set baseUrl, WP_USER, and WP_PASSWORD to match your WordPress site

Run tests

# Run all tests (headless)
npm run cypress:run

# Open Cypress UI (interactive)
npm run cypress:open

Test suites

Environment

In cypress.env.json, set:

• baseUrl – Your WordPress URL (e.g. http://localhost:8080)
• WP_USER / WP_PASSWORD – Login credentials for an existing admin user
• WP_PATH – WordPress path prefix: /wp for Bedrock, "" for standard WP

Troubleshooting

• Popup doesn’t open – Ensure assets/js/popup.js exists and block.json viewScript path is correct. Check the browser console.
• Styles missing – Run npm run build to regenerate build/style-index.css from Tailwind.
• Deprecated blocks show validation errors – Ensure migrate() in save.js correctly maps old attributes.

Structure

satori-popup/
├── cypress/
│   ├── e2e/                    # E2E test specs
│   │   ├── login.cy.js
│   │   ├── popup-block-settings.cy.js
│   │   ├── popup-block-editor.cy.js
│   │   ├── popup-block-frontend.cy.js
│   │   └── popup-block-cta.cy.js
│   └── support/
│       ├── commands.js        # Custom Cypress commands
│       └── e2e.js
├── assets/
│   └── js/
│       ├── popup.js       # Frontend open/close, hover, focus trap (vanilla JS)
│       └── popup.asset.php # Version for cache busting
├── build/
│   ├── index.js           # Compiled block (edit/save)
│   ├── style-index.css    # Compiled Tailwind styles
│   └── ...
├── includes/
│   ├── class-assets.php   # Asset hooks (block assets via block.json)
│   ├── class-autoloader.php
│   ├── class-block.php    # Block registration
│   └── class-plugin.php   # Plugin bootstrap
├── src/
│   ├── constants.js       # ALLOWED_BLOCKS, TEMPLATE, sizes, aligns
│   ├── edit.js            # Block editor UI
│   ├── index.js           # Block registration + Cover filter
│   ├── popup.css          # Tailwind source
│   └── save.js            # Frontend markup + deprecated
├── block.json
├── package.json
├── satori-popup.php       # Plugin entry
└── tailwind.config.js

Block Attributes

Styling

All styles use Tailwind. The block uses theme color palette when available; custom hex is supported via the color dropdown. Cover block background and image are configured in the Cover block settings.

Documentation

• ARCHITECTURE.md – Boot flow, data flow, data attribute contract
• CHANGELOG.md – Version history
• CONTRIBUTING.md – Development and contribution guidelines

License

GPL-2.0-or-later

Author

Stephen Mason – satori.digital