churn: fixes

Author: TBarregren

README.md

@@ -1,4 +1,5 @@
 # Kntnt Popup
+
 [![License: GPL v2+](https://img.shields.io/badge/License-GPLv2+-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 [![Requires PHP: 8.2+](https://img.shields.io/badge/PHP-8.2+-blue.svg)](https://php.net)
 [![Requires WordPress: 6.8+](https://img.shields.io/badge/WordPress-6.8+-blue.svg)](https://wordpress.org)
@@ -10,6 +11,7 @@ WordPress plugin that provides shortcode for creating popups.
 Kntnt Popup is a lightweight, customizable WordPress plugin that provides an easy-to-use shortcode for creating modal popups on your website. With this plugin, you can create popups triggered by various user actions without writing any JavaScript or HTML code.
 
 ### Key Features:
+
 - Simple shortcode implementation with extensive customization options
 - Multiple trigger options: exit intent, time delay, scroll position
 - Customizable animations for opening and closing
@@ -21,21 +23,45 @@ Kntnt Popup is a lightweight, customizable WordPress plugin that provides an eas
 - Built with modern PHP and JavaScript practices
 
 ## Installation
+
 1. [Download the plugin zip archive.](https://github.com/Kntnt/kntnt-popup/releases/latest/download/kntnt-popup.zip)
 2. Go to WordPress admin panel → Plugins → Add New.
 3. Click "Upload Plugin" and select the downloaded zip archive.
 4. Activate the plugin.
 
 ## Usage
+
 The plugin provides a shortcode `[popup]...[/popup]` where the content between the opening and closing tags will be displayed in the popup. This content is processed normally, meaning you can include text, images, HTML, and even other shortcodes inside the popup.
 
 Basic usage:
+
 ```
-[popup show-after-time="5"]
-Your popup content here. Can include text, images, forms, and even other shortcodes.
-[/popup]
+[popup show-after-time="5"]Your popup content here. Can include text, images, forms, and even other shortcodes.[/popup]
 ```
 
+In addition to the automatic triggers (time delay, scroll position, exit intent), you can also launch a popup by clicking any HTML element (like a link or button) on the page.
+
+1. **Define the popup:** First, you must have defined the popup on the same page using the shortcode with a unique ID:
+   ```
+   [popup id="my-unique-popup"]Popup content…[/popup]
+   ```
+
+2. **Create the trigger element (link/button):** Next, add an HTML element where you want your trigger. This element must have the data attribute `data-popup-open` set to the ID of the popup you want to open.
+
+   **Example using a link:**
+   ```html
+   <a href="#" data-popup-open="my-unique-popup">Open My Popup</a>
+   ```
+
+   **Example using a button:**
+   ```html
+   <button data-popup-open="my-unique-popup">Open My Popup</button>
+   ```
+
+   When a user clicks the element with `data-popup-open`, the plugin's JavaScript will automatically open the corresponding popup.
+
+*Important:* Both the popup shortcode and the HTML element with `data-popup-open` must exist on the same page.
+
 ## Parameters
 
 The shortcode accepts various parameters to customize the popup's behavior and appearance. Parameters can be used in three different ways:
@@ -61,6 +87,7 @@ Controls whether the popup shows when the user moves their cursor to leave the p
 *Default value:* `false`
 
 *Examples:*
+
 * `[popup shown-on-exit-intent="true"]`: Triggers popup when user attempts to leave the page
 * `[popup shown-on-exit-intent]`: Same as above since flag value is `true`
 * `[popup]`: Won't trigger popup when user attempts to leave the page since default value is `false`
@@ -78,6 +105,7 @@ Controls whether the popup shows after a specified number of seconds.
 *Note:* This parameter expects a numeric value without units, representing seconds.
 
 *Examples:*
+
 * `[popup show-after-time="5"]`: Triggers popup after 5 seconds
 * `[popup show-after-time]`: Triggers popup after 30 seconds (flag value)
 * `[popup]`: Won't trigger popup based on time since default value is `false`
@@ -95,6 +123,7 @@ Controls whether the popup shows after the user has scrolled a certain percentag
 *Note:* This parameter expects a numeric value without units, representing percentage (0-100).
 
 *Examples:*
+
 * `[popup show-after-scroll="50"]`: Triggers popup after scrolling 50% of the page
 * `[popup show-after-scroll]`: Triggers popup after scrolling 80% of the page (flag value)
 * `[popup]`: Won't trigger popup based on scrolling since default value is `false`
@@ -112,6 +141,7 @@ Sets a custom ID attribute for the popup's wrapper div.
 *Default value:* Automatically generated ID
 
 *Examples:*
+
 * `[popup id="newsletter-popup"]`: Sets the popup ID to "newsletter-popup"
 * `[popup]`: Assigns an automatically generated ID
 
@@ -126,6 +156,7 @@ Adds custom CSS classes to the popup element.
 *Default value:* None (no additional classes)
 
 *Examples:*
+
 * `[popup class="custom-theme large-popup"]`: Adds "custom-theme" and "large-popup" classes
 * `[popup]`: No additional CSS classes
 
@@ -140,6 +171,7 @@ Adds inline CSS for the overlay element.
 *Default value:* None (no inline styles)
 
 *Examples:*
+
 * `[popup style-overlay="backdrop-filter: blur(5px);"]`: Adds a blur effect to the overlay
 * `[popup]`: No additional inline styles for the overlay
 
@@ -154,6 +186,7 @@ Adds inline CSS for the dialog element.
 *Default value:* None (no inline styles)
 
 *Examples:*
+
 * `[popup style-dialog="box-shadow: 0 25px 50px -12px rgba(0,0,0,0.25);"]`: Adds shadow
 * `[popup]`: No additional inline styles for the dialog
 
@@ -168,6 +201,7 @@ Adds inline CSS for the close button element.
 *Default value:* None (no inline styles)
 
 *Examples:*
+
 * `[popup style-close-button="font-size: 24px; color: #ff0000;"]`: Creates a larger, red close button
 * `[popup style-close-button="background-color: #333; border-radius: 50%; color: white;"]`: Creates a dark circular close button
 * `[popup]`: No additional inline styles for the close button
@@ -183,10 +217,11 @@ Adds inline CSS for the popup content area.
 *Default value:* None (no inline styles)
 
 *Examples:*
+
 * `[popup style-content="color: #333; font-size: 16px;"]`: Styles text in the popup content
 * `[popup style-content="background-color: #f9f9f9; padding: 10px;"]`: Adds background and padding to content area
 * `[popup]`: No additional inline styles for the content area
- 
+
 ### Layout and Positioning Parameters
 
 #### `position`
@@ -200,6 +235,7 @@ Determines the popup position on the screen.
 *Default value:* `center`
 
 *Examples:*
+
 * `[popup position="top"]`: Positions the popup at the top center
 * `[popup position="bottom-right"]`: Positions the popup at the bottom right
 * `[popup]`: Centers the popup (default position)
@@ -217,6 +253,7 @@ Sets the desired width of the popup.
 *Default value:* `clamp(300px, 90vw, 800px)`
 
 *Examples:*
+
 * `[popup width="500px"]`: Sets popup width to 500 pixels
 * `[popup width="50%"]`: Sets popup width to 50% of viewport width
 * `[popup]`: Uses the default responsive width
@@ -232,6 +269,7 @@ Sets the maximum height of the popup before scrolling is activated.
 *Default value:* `95vh`
 
 *Examples:*
+
 * `[popup max-height="80vh"]`: Sets maximum height to 80% of viewport height
 * `[popup max-height="600px"]`: Sets maximum height to 600 pixels
 * `[popup]`: Uses the default maximum height (95% of viewport)
@@ -247,6 +285,7 @@ Sets the internal padding of the popup.
 *Default value:* `clamp(20px, calc(5.2vw - 20px), 160px)`
 
 *Examples:*
+
 * `[popup padding="30px"]`: Sets padding to 30 pixels on all sides
 * `[popup padding="20px 40px"]`: Sets vertical padding to 20px and horizontal to 40px
 * `[popup]`: Uses the default responsive padding
@@ -262,6 +301,7 @@ Sets the color of the overlay behind the popup.
 *Default value:* `rgba(0,0,0,80%)`
 
 *Examples:*
+
 * `[popup overlay-color="rgba(0,0,50,70%)"]`: Sets a semi-transparent dark blue overlay
 * `[popup overlay-color="#000000cc"]`: Sets a semi-transparent black overlay
 * `[popup]`: Uses the default semi-transparent black overlay
@@ -279,6 +319,7 @@ Displays a close button with the specified character.
 *Default value:* `false`
 
 *Examples:*
+
 * `[popup close-button="×"]`: Shows a close button with the × character
 * `[popup close-button]`: Shows a close button with the default ✖ character
 * `[popup]`: No close button is displayed
@@ -294,6 +335,7 @@ Determines whether clicking outside the popup area closes it.
 *Default value:* `false`
 
 *Examples:*
+
 * `[popup close-outside-click="true"]`: Clicking outside the popup closes it
 * `[popup close-outside-click]`: Same as above (using flag value)
 * `[popup]`: Clicking outside doesn't close the popup
@@ -309,6 +351,7 @@ Controls whether the popup behaves as a modal dialog.
 *Default value:* `false`
 
 *Examples:*
+
 * `[popup modal="true"]`: Creates a modal popup (focus trapped, background scrolling prevented, overlay added)
 * `[popup modal]`: Same as above (using flag value)
 * `[popup]`: Creates a non-modal popup (focus not trapped, background scrolling not prevented, overlay not added)
@@ -326,12 +369,14 @@ Controls how long before the popup can appear again after being closed.
 *Note:* This parameter is converted to seconds internally. For example, "30s" becomes 30 seconds, "2h" becomes 7,200 seconds, etc.
 
 *Examples:*
+
 * `[popup reappear-delay="4h"]`: Popup won't reappear for 4 hours after being closed
 * `[popup reappear-delay="30s"]`: Popup won't reappear for 30 seconds after being closed
 * `[popup reappear-delay]`: Popup won't reappear for 1 day after being closed (flag value)
 * `[popup]`: Popup can reappear immediately after being closed
 
 Time values can use these units:
+
 - No unit or `s`: seconds (e.g., `30` or `30s`)
 - `m`: minutes (e.g., `5m`)
 - `h`: hours (e.g., `2h`)
@@ -350,6 +395,7 @@ Sets the animation used when the popup appears.
 *Default value:* `false` (no animation)
 
 *Examples:*
+
 * `[popup open-animation="fade-in"]`: Popup fades in when appearing
 * `[popup open-animation="slide-in-top"]`: Popup slides in from the top
 * `[popup open-animation]`: Uses the tada animation (flag value)
@@ -368,6 +414,7 @@ Sets the animation used when the popup closes.
 *Default value:* `false` (no animation)
 
 *Examples:*
+
 * `[popup close-animation="fade-out-top"]`: Popup fades out toward the top when closing
 * `[popup close-animation="slide-out-bottom"]`: Popup slides out to the bottom
 * `[popup close-animation]`: Popup fades out (flag value)
@@ -388,6 +435,7 @@ Overrides the default duration of the open animation.
 *Note:* This parameter expects a numeric value representing milliseconds.
 
 *Examples:*
+
 * `[popup open-animation="fade-in" open-animation-duration="500"]`: Fade in animation lasts 500ms
 * `[popup open-animation="slide-in-top"]`: Uses the default duration for slide-in-top
 
@@ -404,6 +452,7 @@ Overrides the default duration of the close animation.
 *Note:* This parameter expects a numeric value representing milliseconds.
 
 *Examples:*
+
 * `[popup close-animation="fade-out" close-animation-duration="300"]`: Fade out animation lasts 300ms
 * `[popup close-animation="slide-out-bottom"]`: Uses the default duration for slide-out-bottom
 
@@ -420,6 +469,7 @@ Sets the ARIA label for the popup element.
 *Default value:* `"Popup"` (localized if translations are available)
 
 *Examples:*
+
 * `[popup aria-label-popup="Newsletter Signup"]`: Sets a custom ARIA label
 * `[popup]`: Uses the default "Popup" label (translated if available)
 
@@ -434,6 +484,7 @@ Sets the ARIA label for the close button.
 *Default value:* `"Close popup"` (localized if translations are available)
 
 *Examples:*
+
 * `[popup aria-label-close="Dismiss newsletter"]`: Sets a custom ARIA label for close button
 * `[popup]`: Uses the default "Close popup" label (translated if available)
 
@@ -454,6 +505,7 @@ In this example, the popup will appear when the user tries to leave the page, OR
 ### Examples
 
 Show a popup after 5 seconds with a close button:
+
 ```
 [popup show-after-time="5" close-button]
 <h2>Welcome to our site!</h2>
@@ -462,6 +514,7 @@ Show a popup after 5 seconds with a close button:
 ```
 
 Show a popup on exit intent with custom width and position:
+
 ```
 [popup shown-on-exit-intent width="400px" position="top"]
 <h2>Wait before you go!</h2>
@@ -470,6 +523,7 @@ Show a popup on exit intent with custom width and position:
 ```
 
 Show a popup after scrolling 50% with fade-in animation:
+
 ```
 [popup show-after-scroll="50" open-animation="fade-in" close-outside-click]
 <h2>You're halfway there!</h2>
@@ -478,6 +532,7 @@ Show a popup after scrolling 50% with fade-in animation:
 ```
 
 Show a popup containing a contact form (using Contact Form 7 shortcode as an example):
+
 ```
 [popup show-after-time="10" close-button position="center" width="600px"]
 <h2>Contact Us!</h2>
@@ -493,7 +548,9 @@ The plugin provides a few hooks for developers to customize the popup behavior:
 ### WordPress Filters:
 
 #### `kntnt-popup-shortcode-atts`
+
 Modifies shortcode attributes before they're processed.
+
 ```php
 add_filter('kntnt-popup-shortcode-atts', function($attributes) {
     // Modify attributes based on conditions
@@ -505,7 +562,9 @@ add_filter('kntnt-popup-shortcode-atts', function($attributes) {
 ```
 
 #### `kntnt-popup-content`
+
 Filters the popup content before it's displayed.
+
 ```php
 add_filter('kntnt-popup-content', function($content, $popup_id) {
     // Personalize content for logged-in users
@@ -518,7 +577,9 @@ add_filter('kntnt-popup-content', function($content, $popup_id) {
 ```
 
 #### `kntnt-popup-armed`
+
 Determines whether a popup should be shown at all.
+
 ```php
 add_filter('kntnt-popup-armed', function($armed) {
     // Disable popups for administrators
@@ -534,7 +595,9 @@ add_filter('kntnt-popup-armed', function($armed) {
 ```
 
 #### `kntnt-popup-shortcode`
+
 Filters the entire popup HTML output.
+
 ```php
 add_filter('kntnt-popup-shortcode', function($output, $atts, $content) {
     // Modify the final HTML
@@ -549,22 +612,26 @@ add_filter('kntnt-popup-shortcode', function($output, $atts, $content) {
 Event listeners should be added before the popup is initialized:
 
 #### `kntnt_popup:before_open`
+
 Triggered before a popup is opened.
+
 ```javascript
-document.addEventListener('kntnt_popup:before_open', function(event) {
+document.addEventListener('kntnt_popup:before_open', function (event) {
   // Pause videos when popup opens
-  document.querySelectorAll('video').forEach(function(video) {
+  document.querySelectorAll('video').forEach(function (video) {
     video.pause();
   });
 });
 ```
 
 #### `kntnt_popup:after_close`
+
 Triggered after a popup is closed.
+
 ```javascript
-document.addEventListener('kntnt_popup:after_close', function(event) {
+document.addEventListener('kntnt_popup:after_close', function (event) {
   // Resume background content after popup closes
-  document.querySelectorAll('.background-video').forEach(function(video) {
+  document.querySelectorAll('.background-video').forEach(function (video) {
     video.play();
   });
 });
@@ -638,18 +705,23 @@ Now you have the necessary JavaScript file in place, and the plugin should funct
 ## Questions & Answers
 
 ### How can I get help?
+
 If you have questions about the plugin and cannot find an answer here, start by looking at issues and pull requests on our GitHub repository. If you still cannot find the answer, feel free to ask in the plugin's issue tracker on GitHub.
 
 ### How can I report a bug?
+
 If you have found a potential bug, please report it on the plugin's issue tracker on GitHub.
 
 ### How can I contribute?
+
 Contributions to the code or documentation are much appreciated.
 If you are familiar with Git, please do a pull request.
 If you are not familiar with Git, please create a new ticket on the plugin's issue tracker on GitHub.
 
 ## Changelog
+
 ### 1.0.0 (2025-04-19)
+
 - Initial release
 - Added shortcode functionality with comprehensive parameter options
 - Implemented multiple trigger mechanisms (exit intent, time delay, scroll position)