PHPackages                             calevans/staticforge-popup - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. calevans/staticforge-popup

ActiveLibrary[Utility & Helpers](/categories/utility)

calevans/staticforge-popup
==========================

Popup feature for StaticForge

2.0.2(2mo ago)012MITPHPPHP ^8.4

Since Dec 10Pushed 2mo agoCompare

[ Source](https://github.com/calevans/staticforge-popup)[ Packagist](https://packagist.org/packages/calevans/staticforge-popup)[ RSS](/packages/calevans-staticforge-popup/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (2)Versions (10)Used By (0)

[StaticForge](https://calevans.com/staticforge) Popup Feature
=============================================================

[](#staticforge-popup-feature)

A powerful popup management feature for StaticForge sites. This library allows you to define popups using Markdown and YAML frontmatter, and easily attach them to specific pages.

Copyright 2025, Cal Evans
License: MIT

Features
--------

[](#features)

- **Markdown Support**: Define popup content using standard Markdown.
- **Flexible Triggers**:
    - **Timer**: Show popup after a specified delay.
    - **Exit Intent**: Show popup when the user moves their mouse out of the viewport.
- **Smart Blocking**: Uses cookies to prevent showing the same popup repeatedly (configurable duration).
- **Page-Specific Targeting**: Enable popups on specific pages via frontmatter.
- **Custom Styling**: Support for global popup CSS and per-popup CSS files.
- **Form Integration**: Built-in support for StaticForge forms.

Installation
------------

[](#installation)

Install via Composer:

```
composer require calevans/staticforge-popup
php bin/staticforge feature:setup staticforge-popup
```

Configuration & Usage
-------------------------

[](#configuration--usage)

Implementing a popup involves 5 steps. If you are not using a form in your popup, you can skip Step 1.

### Step 1: Define the Form (Optional)

[](#step-1-define-the-form-optional)

If your popup includes a form (like a newsletter signup), you must first define it in your `siteconfig.yaml`. This allows the popup feature to know about the fields and submission URL.

**`siteconfig.yaml`**:

```
forms:
  newsletter:
    provider_url: "https://your-newsletter-provider.com/subscribe"
    submit_text: "Subscribe Now"
    success_message: "Thanks for signing up!"
    error_message: "Something went wrong. Please try again."
    fields:
      - name: first_name
        label: First Name
        type: text
        required: true
      - name: email
        label: Email Address
        type: email
        required: true
```

**What is `provider_url`?**

The `provider_url` is the endpoint where the form data will be POSTed when the user clicks submit. This can be any service that accepts form data.

- **[Sendpoint](https://github.com/calevans/sendpoint)**: A simple, secure, self-hosted solution designed specifically for handling form submissions from static sites. It does one thing: validates data and sends emails.
- **[n8n](https://n8n.io)**: A powerful workflow automation tool that can receive webhooks and process the data (e.g., add to a CRM, send an email, etc.).
- **Other Services**: Any newsletter provider (Mailchimp, ConvertKit) or form handling service (Formspree) that provides a submission URL.

### Step 2: Create the Popup Content

[](#step-2-create-the-popup-content)

Create a `.popup` file in your content directory (e.g., `content/popups/newsletter.popup`). This file defines the content and behavior of your popup.

**`content/popups/newsletter.popup`**:

```
---
popup_enabled: true
id: newsletter-signup
exit_intent: true
timer: 5
popup_blocked_for: 30
---

# Join our Newsletter!

Get the latest updates directly to your inbox.

{{ form('newsletter') }}
```

**Frontmatter Options:**

- `popup_enabled` (required): Set to `true` to enable this popup.
- `id` (optional): Unique identifier. Defaults to the filename.
- `exit_intent` (optional): `true` to trigger when the user mouses out of the viewport.
- `timer` (optional): Seconds to wait before showing the popup.
- `popup_blocked_for` (optional): Days to hide the popup after it has been shown (default: 30).
- `url` (optional): Overrides the `provider_url` defined in `siteconfig.yaml` for this specific popup's form.

**Overriding the Form URL**

While `siteconfig.yaml` defines the default `provider_url` for your forms, you may have a specific popup that needs to submit data to a different endpoint (e.g., a different newsletter list or a specific campaign handler).

To do this, simply add the `url` key to your popup's frontmatter:

```
---
popup_enabled: true
id: special-campaign
url: "https://hooks.zapier.com/hooks/catch/123456/abcdef/"
---
```

When this popup is rendered, the form action will use this URL instead of the global one defined in your configuration.

### Step 3: Create the Templates

[](#step-3-create-the-templates)

You need Twig templates to control the HTML structure of your popups.

**A. The Popup Container (`templates/popup.html.twig`)**This template wraps your popup content. It handles the overlay and the close button.

```

        ×

            {{ popup.content | raw }}

```

*Note: You can create specific templates for individual popups by naming them `templates/{popup-id}.html.twig`.*

**B. The Form Template (`templates/_popup_form.html.twig`)**If you used `{{ form() }}` in Step 2, you **must** create this template to render the form fields.

```

    {% for field in fields %}

            {{ field.label }}

    {% endfor %}
    {{ submit_text }}

```

### Step 4: Add Styling

[](#step-4-add-styling)

The feature automatically looks for CSS files to style your popup.

1. **Global Styles**: Create `content/assets/css/popup.css`. This file is automatically injected on pages with popups.
2. **Specific Styles**: Create `content/assets/css/{popup-id}.css` for styles specific to one popup.

**Example `content/assets/css/popup.css`**:

```
.sf-popup-overlay {
    position: fixed;
    top: 0; left: 0; width: 100%; height: 100%;
    background: rgba(0,0,0,0.7);
    z-index: 1000;
    display: flex;
    justify-content: center;
    align-items: center;
}
.sf-popup-content {
    background: white;
    padding: 2rem;
    border-radius: 8px;
    position: relative;
    max-width: 500px;
    width: 90%;
}
.close-popup {
    position: absolute;
    top: 10px;
    right: 10px;
    border: none;
    background: none;
    font-size: 1.5rem;
    cursor: pointer;
}
```

### Step 5: Enable on a Page

[](#step-5-enable-on-a-page)

Finally, tell StaticForge which pages should display the popup by adding the `popup` key to the page's frontmatter.

**`content/index.md`**:

```
---
title: Home Page
popup: newsletter-signup
---

Welcome to my website!
```

You can also attach multiple popups:

```
popup:
  - newsletter-signup
  - special-offer
```

Requirements
------------

[](#requirements)

- PHP 8.4+
- StaticForge
- jQuery (Automatically injected if not present)

License
-------

[](#license)

MIT

###  Health Score

42

—

FairBetter than 90% of packages

Maintenance87

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~12 days

Recently: every ~19 days

Total

9

Last Release

63d ago

Major Versions

1.2.0 → 2.0.02026-03-17

### Community

Maintainers

![](https://www.gravatar.com/avatar/af70e3d71b3fb87f45c1025d3a21149958da1a416cabbebd4f450e18f920babc?d=identicon)[calevans](/maintainers/calevans)

---

Top Contributors

[![calevans](https://avatars.githubusercontent.com/u/426938?v=4)](https://github.com/calevans "calevans (15 commits)")

### Embed Badge

![Health badge](/badges/calevans-staticforge-popup/health.svg)

```
[![Health](https://phpackages.com/badges/calevans-staticforge-popup/health.svg)](https://phpackages.com/packages/calevans-staticforge-popup)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)