# Catch Popup — Plugin Instructions

## Table of Contents

1. [Overview](#overview)
2. [Installation](#installation)
3. [Quick Start](#quick-start)
4. [Creating a Popup](#creating-a-popup)
   - [Popup Content](#popup-content)
   - [Triggers Tab](#triggers-tab)
   - [Display Tab](#display-tab)
   - [Close Tab](#close-tab)
   - [Targeting Tab](#targeting-tab)
5. [Popup Themes](#popup-themes)
   - [Built-in Themes](#built-in-themes)
   - [Theme Settings](#theme-settings)
6. [Displaying a Popup](#displaying-a-popup)
   - [Shortcode](#shortcode)
   - [Gutenberg Block](#gutenberg-block)
7. [Reference: All Settings](#reference-all-settings)
8. [Tips & Common Use Cases](#tips--common-use-cases)
9. [Frequently Asked Questions](#frequently-asked-questions)

---

## Overview

Catch Popup lets you create unlimited fully customisable popups on your WordPress site. Each popup is a custom post with its own trigger, appearance, size, position, close behaviour, and page-targeting rules. A separate **Popup Theme** controls the visual style (colours, fonts, borders, shadows) and can be reused across multiple popups.

---

## Installation

### Via WordPress Dashboard (recommended)

1. Go to **Plugins › Add New**.
2. Search for **Catch Popup**.
3. Click **Install Now**, then **Activate**.

### Via FTP

1. Download and unzip the plugin.
2. Upload the `catch-popup` folder to `/wp-content/plugins/`.
3. Go to **Plugins** in your dashboard and click **Activate** next to Catch Popup.

> **On first activation** the plugin automatically installs five built-in popup themes (Default, Theme Border, Theme Blue, Theme Light, Theme Round) into your database.

---

## Quick Start

1. Go to **Catch Popup › Add New** in the left menu.
2. Give the popup a title and add your content in the editor.
3. In the **Popup Settings** meta box below the editor, choose your trigger, appearance, and targeting options.
4. Click **Publish**.
5. Use a shortcode or block to attach a click trigger, **or** leave the trigger set to **Auto Open** to show the popup automatically on page load.

---

## Creating a Popup

Navigate to **Catch Popup › Add New**. The standard WordPress editor handles the popup's title and body content. Below the editor you will find the **Popup Settings** meta box with four tabs.

### Popup Content

| Area | What it controls |
|---|---|
| **Title** (post title field) | Displayed as the popup heading |
| **Body** (post editor) | The main content — supports any blocks, HTML, shortcodes, images, forms, etc. |
| **Featured Image** | Optional image displayed above the body content inside the popup |

---

### Triggers Tab

Controls **how and when** the popup opens.

#### How to Show Popup

| Option | Behaviour |
|---|---|
| **Auto Open / Time Delay** | Popup opens automatically after the page loads (uses the Delay setting below) |
| **Click Open** | Popup only opens when a visitor clicks a trigger element added via shortcode or block |

#### Delay *(Auto Open only)*

A slider and number input from **0 ms to 10,000 ms** (0 = immediately on page load).

> **Example:** Set to `3000` to open the popup 3 seconds after the page loads.

---

### Display Tab

Controls the **visual appearance, size, and position** of the popup window. Four sub-tabs:

#### Appearance

| Setting | Description |
|---|---|
| **Popup Theme** | Select which Popup Theme to apply. Themes control colours, fonts, borders, and shadows. See [Popup Themes](#popup-themes). |

#### Size

| Setting | Description | Default |
|---|---|---|
| **Window Size** | Preset responsive size or custom dimensions | Medium (60%) |
| **Min Width** | Minimum width as a percentage (0–100%) | 0% |
| **Max Width** | Maximum width as a percentage (0–100%) | 100% |
| **Width** *(Custom only)* | Exact width with unit selection (px / % / em / rem) | 640 px |
| **Auto Adjust Height** *(Custom only)* | Checkbox — popup height matches content automatically | Checked |
| **Height** *(Custom only, auto off)* | Exact height with unit selection | 0 px |

**Responsive size presets:**

| Name | Width |
|---|---|
| Nano | 10% |
| Micro | 20% |
| Tiny | 30% |
| Small | 40% |
| Medium | 60% |
| Normal | 70% |
| Large | 80% |
| X-Large | 95% |
| Auto | Shrinks to content width (set Min/Max Width) |
| Custom | Exact px / % / em / rem dimensions |

#### Position

| Setting | Description | Default |
|---|---|---|
| **Location** | Where on screen the popup appears | Top Center |
| **Top / Right / Bottom / Left** | Offset in pixels from the chosen edge (shown only when relevant to the chosen location) | 100 px (top) |

**Available locations:** Top Left, Top Center, Top Right, Middle Left, Middle Center, Middle Right, Bottom Left, Bottom Center, Bottom Right.

#### Advanced

| Setting | Description | Default |
|---|---|---|
| **Z-Index** | CSS stacking order (0–200,000). Increase if the popup appears behind other elements. | 10,000 |

---

### Close Tab

Controls how visitors can **dismiss** the popup. Two sub-tabs:

#### Button

| Setting | Description | Default |
|---|---|---|
| **Button Text** | Custom label shown next to (or instead of) the × icon on the close button. Leave blank to show the × only. | *(blank)* |
| **Close Button Delay** | How many milliseconds to wait before the close button becomes clickable (0–10,000 ms). Useful to ensure visitors read the content first. | 0 ms |

#### Alternative Methods

| Setting | Description | Default |
|---|---|---|
| **Click Overlay to Close** | Closes popup when visitor clicks the dark overlay surrounding it | Off |
| **Press ESC to Close** | Closes popup when visitor presses the Escape key | Off |
| **Press F4 to Close** | Closes popup when visitor presses the F4 key | Off |

---

### Targeting Tab

Controls **which pages** the popup appears on. By default (no conditions added) the popup shows on every page of your site.

Click **+ Add more** to add a condition row. Each row contains:

1. **And / Or** connector *(from the second row onwards)* — whether all conditions must match (And) or any one is enough (Or).
2. **Condition** — select from the dropdown what type of page to target:

| Condition | Shows popup on… |
|---|---|
| Home | The front/home page |
| Search | Search results pages |
| 404 | 404 error pages |
| All Posts | Every single post |
| Selected Posts | Specific posts you choose |
| All Pages | Every static page |
| Selected Pages | Specific pages you choose |
| With Categories | Posts belonging to selected categories |
| With Tags | Posts with selected tags |
| Blog Index | The blog posts index page |

Click the **Remove** link (×) on any row to delete that condition.

> **Tip:** Leave the Targeting section empty (no rows) to display the popup site-wide. Add rows to restrict it to specific areas.

---

## Popup Themes

A **Popup Theme** is a separate post type that defines the visual design — overlay colour, container background, typography, close button style, drop shadows, and borders. One theme can be applied to many popups, so changing the theme updates all linked popups at once.

### Built-in Themes

Five themes are installed automatically on first activation:

| Theme | Character |
|---|---|
| **Default** | Clean white container, dark close button, Open Sans font |
| **Theme Border** | Gold/tan background with white border frame |
| **Theme Blue** | Bright blue background, white text, teal close button |
| **Theme Light** | Light grey tones, yellow close button, dark text |
| **Theme Round** | Green background, rounded corners, Dancing Script font |

### Managing Themes

- Go to **Catch Popup Themes** in the left menu.
- Click an existing theme to edit it, or click **Add New** to create your own.
- Give the theme a title, then configure it in the **Popup Theme Settings** meta box.

### Theme Settings

#### Overlay

| Setting | Description |
|---|---|
| **Color** | Background colour of the semi-transparent overlay behind the popup |
| **Opacity** | How opaque the overlay is (0 = fully transparent, 100 = fully opaque) |

#### Container

Split across four sub-tabs:

- **Container** — Padding (px) and Border Radius (px)
- **Background** — Background colour and opacity
- **Border** — Style (None / Solid / Dotted / Dashed / Double / Groove / Inset / Outset / Ridge), colour, and thickness
- **Drop Shadow** — Horizontal position, vertical position, blur radius, spread, colour, opacity, and inset toggle

#### Title

| Setting | Options |
|---|---|
| Font Color | Color picker |
| Font Family | 40+ choices including Open Sans, Roboto, Montserrat, Oswald, Lora, Georgia, etc. |
| Font Size | px |
| Font Weight | 100 – 900 |
| Font Style | Normal / Italic |
| Line Height | px |
| Alignment | Left / Center / Right / Justify |
| Text Shadow | Horizontal, vertical, blur, colour, opacity |

#### Content

| Setting | Options |
|---|---|
| Font Color | Color picker |
| Font Family | Same 40+ choices as Title |
| Font Weight | 100 – 900 |
| Font Style | Normal / Italic |

#### Close Button

| Setting | Description |
|---|---|
| Button Text | Default label inside the close button |
| Position Outside Container | Places the close button outside (above) the popup container |
| Location | Where the button sits: Top Left, Top Center, Top Right, Middle Left, Middle Right, Bottom Left, Bottom Center, Bottom Right |
| Top / Right / Bottom / Left | Offset in px from the chosen corner |
| Padding | Inner padding of the close button |
| Width / Height | Dimensions of the close button in px |
| Border Radius | Rounds the button corners |
| Background Color & Opacity | Fill colour of the button |
| Font Color, Size, Weight, Style, Line Height, Family | Typography of the button label |
| Border | Style, colour, thickness |
| Drop Shadow | Shadow behind the button |
| Text Shadow | Shadow on the button text |

---

## Displaying a Popup

### Shortcode

When the popup trigger is set to **Click Open**, you need a clickable element on the page that opens it. Use the `[catch-popup]` shortcode to wrap any text or HTML:

```
[catch-popup id="123" html_tag="button"]Open Popup[/catch-popup]
```

| Attribute | Description | Default | Allowed values |
|---|---|---|---|
| `id` | The ID of the popup post to open (required) | *(empty)* | Any published popup ID |
| `html_tag` | The HTML element to wrap the trigger text in | `span` | `a`, `button`, `div`, `span` |
| `popup_class` | Extra CSS class(es) to add to the trigger element | *(empty)* | Any valid CSS class name |

**How to find the popup ID:**
Go to **Catch Popup**, hover over the popup name — the ID appears in the URL shown in the browser status bar (e.g. `post=123`). Or you can install the plugin "<a href="https://wordpress.org/plugins/catch-ids/" target="_blank">Catch Ids</a>" and it will show ID.

**Examples:**

```
[catch-popup id="42" html_tag="button" popup_class="my-btn"]Subscribe Now[/catch-popup]
```

```
[catch-popup id="42" html_tag="a"]Click here for our offer[/catch-popup]
```

> **Note:** The shortcode generates a cursor-pointer element. Style it further with your theme CSS or the `popup_class` attribute.

---

### Gutenberg Block

1. In the block editor, click **+** to add a new block.
2. Search for **Catch Popup**.
3. Select the **Catch Popup** block.
4. In the block settings panel enter:
   - **Select Popup** — Select which popup you want to open
   - **HTML Tag** — `a`, `button`, `div`, or `span`
   - **CPopup Class** — optional extra CSS class
   - **Button Text** — the visible trigger label (defaults to "Click Me")

The block renders the same shortcode output on the front end.

---

## Reference: All Settings

### Popup Defaults

| Setting | Default value |
|---|---|
| Trigger style | Auto Open |
| Delay | 0 ms |
| Size | Medium (60%) |
| Min Width | 0% |
| Max Width | 100% |
| Auto Height | On |
| Location | Top Center |
| Top offset | 100 px |
| Z-Index | 10,000 |
| Close button delay | 0 ms |
| Overlay close | Off |
| ESC close | Off |
| F4 close | Off |
| Targeting | All pages (no conditions) |

---

## Tips & Common Use Cases

### Newsletter signup popup (auto, timed)
1. Create a popup with an email form in the body.
2. Set trigger to **Auto Open**, delay to `5000` (5 seconds).
3. Leave Targeting empty so it appears site-wide, or add a condition for **Home** only.

### Promotional banner (click trigger, specific page)
1. Create a popup with an offer image and CTA button.
2. Set trigger to **Click Open**.
3. In the page or post you want, add a button using the Gutenberg **Catch Popup** block or the `[catch-popup]` shortcode with the popup ID.
4. Under Targeting, add **Selected Pages** and choose that specific page so the popup HTML is only loaded there.

### Cookie/GDPR notice (auto, all pages, close delay)
1. Create a popup with your notice text.
2. Set trigger to **Auto Open**, delay to `0` ms.
3. Set **Close Button Delay** to `3000` ms so visitors must read for 3 seconds before dismissing.
4. Enable **Click Overlay to Close** as a fallback.
5. Leave Targeting empty.

### Reusing a visual style
1. Go to **Catch Popup Themes** and edit the **Default** theme (or create a new one).
2. Set your brand colours, fonts, and borders once.
3. Go to each popup and select that theme under **Display › Appearance › Popup Theme**.

### Stacking multiple conditions
- Use **Or** to show the popup on either of two different page types (e.g. Home **Or** Search).
- Use **And** to require both conditions to be true simultaneously (e.g. All Posts **And** With Categories = "News").

---

## Frequently Asked Questions

**Q: The popup isn't showing — what should I check?**
1. Make sure the popup is **Published** (not Draft).
2. If trigger is **Click Open**, confirm the shortcode or block has the correct popup ID.
3. If trigger is **Auto Open**, check whether a Targeting condition is restricting it to a page you aren't on.
4. Check that the popup has a **Popup Theme** selected under Display › Appearance.

**Q: How do I show a popup on every page except one?**
Catch Popup's targeting rules are "show on" conditions only. The simplest workaround is to add every other page type (Home, All Posts, All Pages) as separate **Or** conditions, omitting the page you want to exclude.

**Q: Can I use HTML or a contact form inside a popup?**
Yes. The popup body is the standard WordPress block editor. You can embed any shortcode, contact form plugin block, image, video, or HTML.

**Q: Can I have multiple popups on the same page?**
Yes. Each popup is independent. Multiple popups can target the same page. Click-triggered popups only open when their individual trigger is clicked; auto-open popups each follow their own delay.

**Q: My popup appears behind other elements. How do I fix it?**
Increase the **Z-Index** under **Display › Advanced**. A value higher than whatever Z-index your theme or other plugins use (common values are 100–9999) will bring the popup to the front.

**Q: How do I create my own visual theme?**
Go to **Catch Popup Themes › Add New**, give it a name, and configure the overlay, container, title, content, and close-button settings. Then select your new theme in any popup under **Display › Appearance › Popup Theme**.

**Q: Where are the generated CSS and JS files stored?**
The plugin writes `catch-popup-styles.css` and `catch-popup.js` into `wp-content/uploads/catch-popup/`. These files are regenerated automatically whenever a page loads. Do not edit them manually — changes will be overwritten.

**Q: The plugin won't activate when Catch Popup Pro is installed.**
The free and Pro versions cannot be active at the same time. Deactivate the free version before activating Pro, or vice versa.