SSP — Seasonal Countdown Bar (Docs)

SSP Documentation

Seasonal Countdown Bar

Admin Screen

The plugin adds a top-level menu item Countdown Bar (clock icon) with a comprehensive settings page featuring live preview:

Key Sections

Live Preview

Real-time countdown display
Theme colors and styling
Updates automatically on setting changes
Shows error messages if theme unavailable

Status & Timer

Enable/disable toggle
Hide from admin users option
Three countdown modes
Manual duration configuration
Reset timer button

Theme Controls

Include/exclude seasons and holidays
Auto vs Exact theme source
Global holiday trigger mode
Custom per-item rules table
Bulk actions for quick setup

Menu Location	Countdown Bar (dashicons-clock) at priority 58
Settings Page	admin.php?page=scb-settings
Permissions	Requires `manage_options` capability
Options Key	`scb_options`

Countdown Modes

The plugin offers three distinct countdown timer modes to fit different use cases:

Auto Option A

Always show next theme

Checks month-based holidays first
Then checks window-based holidays
Falls back to current season
If no season active, shows next upcoming holiday
Never hides – always finds something to count down to

Auto Option B

Current month only

Only shows themes in current calendar month
Checks month-based holidays first
Falls back to current season if active
Can hide if no theme matches current month
More restrictive but seasonal-accurate

Manual

Fixed duration timer

Uses configured days/hours/minutes
Starts from deadline stored in database
When timer ends, can hide or roll to new deadline
Theme determined by other settings
Best for limited-time promotions

Manual Duration Settings

Days	0-999+ (no maximum)
Hours	0-240
Minutes	0-59
Minimum	If all values are 0, defaults to 1 minute
Storage	Global deadline stored as Unix timestamp (ms) in `scb_global_deadline_ms`

Reset Timer Button: Clicking “Reset Timer Now” sets a new deadline from current time + configured duration. Useful after changing duration values or for testing.

Theme System

The plugin includes 14 built-in themes with custom color gradients and automatic date-based activation:

Available Themes

Seasons (4)

Spring	Mar 20 – Jun 20 \| Green gradient
Summer	Jun 21 – Sep 22 \| Orange/yellow gradient
Fall	Sep 23 – Dec 20 \| Brown/orange gradient
Winter	Dec 21 – Mar 19 \| Blue gradient

Holidays (10)

New Year	Jan 1 \| Blue/gold
Valentine’s	Feb 14 \| Pink/red
St. Patrick’s	Mar 17 \| Green
Easter	Computed date \| Pastel
Independence Day	Jul 4 \| Red/white/blue
Labor Day	1st Mon Sep \| Blue
Halloween	Oct 31 \| Black/orange
Thanksgiving	4th Thu Nov \| Brown/orange
Black Friday	Day after Thanksgiving \| Black/red
Christmas	Dec 25 \| Red/green

Theme Source Modes

Auto (Dynamic)

Automatically selects theme based on date logic:

Check if any holiday matches (month or window mode)
If no holiday, use current season
Option A: if no season, show next upcoming holiday
Option B: if no season, hide bar

Exact (Fixed)

Forces a specific theme regardless of date:

Choose any of the 14 themes
Ignores date-based logic entirely
Useful for year-round promotions
Still respects include/exclude settings

Include / Exclude

Control which themes are available for Auto mode selection:

Seasons: Toggle each of 4 seasons individually
Holidays: Toggle each of 10 holidays individually
Disabled themes are never shown in Auto mode
Exact mode can still select disabled themes

Per-Item Rules (Custom Timing)

Override global holiday trigger settings for individual themes with granular control:

Activation

Enable per-item rules: Check “Override with custom rules for each theme” under Theme Source section to activate the per-item table.

Rule Types

Window (Holidays)	Show theme when within X days of the holiday Example: Set Christmas to 30 days → bar appears Dec 1-25 Configurable days value (0-999)
Month (Holidays)	Show theme during entire month of holiday Example: Halloween set to Month → bar appears all of October Days value ignored for this mode
Auto (Seasons only)	Use natural season boundaries Cannot be changed – seasons always use auto mode Days value ignored

Bulk Actions

Quick-set all themes at once with bulk controls above the table:

Window: Sets all holidays to Window mode with specified days value
Month: Sets all holidays to Month mode
Reset Seasons: Sets all seasons back to Auto mode with 0 days

Global vs Per-Item Logic

When per-item rules are DISABLED:

Global holiday trigger mode applies to all holidays
Global window days applies to all window-based holidays

When per-item rules are ENABLED:

Each theme uses its own row settings
Global settings are ignored
Allows mixing window and month modes for different holidays

Example Configurations

Conservative	Set all holidays to 7-day windows – bars appear 1 week before events
Aggressive	Set all holidays to Month mode – bars appear all month long
Custom Mix	Christmas: 30 days, Halloween: Month, Valentine’s: 14 days, etc.

Position & Layout

Position Modes

Fixed (Default)

Bar stays at top of viewport
Pushes page content down
Adds html.scb-pushed class
Sets --scb-offset CSS variable
Adjusts for admin bar automatically
Uses ResizeObserver for dynamic height

Sticky

Bar sits in normal document flow
Sticks to top when scrolling
Does not push content
Better for already-sticky headers
No ResizeObserver needed

Responsive Behavior

Desktop (>950px)	Single row layout, badge + message + timer + CTA horizontal
Tablet (600-950px)	Two-row layout, badge/message on top, timer/CTA on bottom
Mobile (347-600px)	Stacked layout, message hidden, smaller timer segments
Tiny (<347px)	2×2 grid for timer segments, further reduced padding

Additional Options

Stop push after end	When timer ends, remove `scb-pushed` class and disconnect ResizeObserver Frees up vertical space after countdown completes Only applies to Fixed position mode
Allow close	Shows × (close) button in top-right Clicking stores `scb_dismissed=1` in sessionStorage Bar stays hidden until browser session ends
Hide for admin	Completely hides bar for users with `manage_options` capability Useful for testing without affecting admin workflow

Call to Action (CTA)

The CTA button appears on the right side of the bar (or bottom on mobile) and drives traffic to your offer:

CTA Modes

Shop	Uses site’s shop URL (typically /shop/) URL field value used as destination Best for WooCommerce or ecommerce sites
Custom	Uses any URL you specify Enter full URL including https:// Perfect for landing pages, external offers, campaigns
None	Hides CTA button entirely Bar shows only badge, message, and timer Use for awareness-only campaigns

Configuration

Destination URL	Full URL (https://example.com/landing) – defaults to `home_url('/shop/')`
Button Text	Text displayed on button – defaults to “Buy Plugins”
HTML Attributes	URL is properly escaped, text is sanitized

Styling

CTA button inherits theme colors via CSS custom properties:

Background: Gradient using --scb-c1 and --scb-c2
Rounded pill shape (border-radius: 9999px)
Box shadow with theme-colored glow
Hover effect: subtle translateY and brightness boost
White text with high contrast

Frontend Behavior

Rendering

Hook	`wp_footer` priority 1
Styles	`wp_head` priority 1 (inline CSS)
Scripts	`wp_footer` priority 1 (inline JS)
DOM Element	`#scb-root.scb` injected at body start

Client-Side Theme Resolution

JavaScript handles all theme selection logic client-side for performance:

Parse configuration passed from PHP
Determine current date and time
Run theme resolution algorithm (Auto A, Auto B, or Exact)
Compute deadline based on theme and mode
Apply theme CSS class to #scb-root
Start countdown timer interval
Re-resolve theme if timer ends in Auto mode

Timer Updates

Interval	1000ms (every second)
Format	Days (no padding), Hours/Minutes/Seconds (zero-padded to 2 digits)
Segments	4 segments: DAYS, HOURS, MINUTES, SECONDS
Ended State	Adds `.scb-ended` class, optionally hides or rolls to next theme

JavaScript API

The plugin exposes a global API for advanced integrations:

window.SCB = {
  deadlineMs: 1234567890000,        // Current deadline timestamp
  getDeadlineMs: function() { },    // Get current deadline
  getTheme: function() { }          // Get current theme key
}

Storage

sessionStorage	`scb_dismissed` – Set to “1” when user closes bar
WordPress Options	`scb_options` – All settings, `scb_global_deadline_ms` – Manual mode deadline

Troubleshooting

Bar doesn’t appear on frontend

Verify “Enable bar” is checked in Status & Timer section
Check “Hide for admin” – if enabled and you’re logged in as admin, bar is hidden
Inspect browser sessionStorage – if scb_dismissed=1, open incognito or clear storage
For Auto Option B, ensure current month has an active theme (or switch to Auto Option A)
Check browser console for JavaScript errors
Verify theme CSS loaded – search page source for “#scb-root”

Preview shows error: “No enabled themes”

This happens when:

All seasons and holidays are unchecked in Include / Exclude
Using Auto Option A mode
Solution: Enable at least one season or holiday

Preview shows error: “Auto Option B: No holiday/season found”

This is expected behavior when:

Using Auto Option B (current month only)
Current month has no matching holiday
Current date is not within an active season
Solution: Switch to Auto Option A, or add a matching holiday/season

Wrong theme appears

Check Theme Source – if Exact mode, it forces the selected theme regardless of date
Verify per-item rules are configured correctly
For window mode, check the days value – may be too short or too long
Check include/exclude settings – disabled themes can’t be selected in Auto mode
Inspect browser console – theme key logged during initialization

Timer shows negative time or wrong countdown

Click “Reset Timer Now” to resync deadline with current settings
Check server timezone matches expected timezone
Verify duration fields aren’t set to extreme values
For Auto modes, deadline is calculated from theme’s natural end date

Bar overlaps header or looks broken on mobile

Switch from Sticky to Fixed position mode
Check for CSS conflicts with z-index: 999999
Ensure viewport meta tag is present: <meta name="viewport" content="width=device-width, initial-scale=1">
Test responsive breakpoints: 950px, 600px, 347px
Clear browser cache and site caching plugins

Page content not pushed down properly

Ensure using Fixed position mode (not Sticky)
Check html.scb-pushed class is applied
Verify --scb-offset CSS variable is set
Look for theme CSS overriding body { margin-top }
Check if ResizeObserver is supported (all modern browsers)

Close button doesn’t work

Verify “Allow close” is enabled
Check browser console for JavaScript errors
Ensure sessionStorage is not blocked by browser privacy settings
Try in incognito mode to rule out extension conflicts

Bulk actions don’t update table

Bulk action buttons update form values but don’t save automatically:

Click bulk action button (Window/Month/Reset Seasons)
Verify table rows updated
Scroll down and click “Save Changes” button
Preview should update immediately

Testing & Verification

Quick Test Checklist

Enable bar and verify preview appears in admin
Check frontend (logged out or incognito) to see actual bar
Test close button – bar should disappear and stay hidden in same session
Open new incognito window – bar should reappear
Test mobile responsive at 950px, 600px, 347px breakpoints
Verify CTA button links to correct destination
Check timer updates every second
Test “Hide for admin” option while logged in

Testing Different Modes

Manual Mode

Set countdown mode to Manual
Set duration to 0 days, 0 hours, 2 minutes
Click “Reset Timer Now”
Verify countdown starts from 2:00 and counts down
Wait for timer to reach 0:00
If “stop push after end” enabled, verify page push removed

Auto Modes

Set countdown mode to Auto Option A
Select exact theme (e.g., Summer)
Verify preview shows Summer theme
Switch to Auto theme source
Verify theme changes based on current date
Try Auto Option B – may hide if no theme matches month

Testing Per-Item Rules

Enable “Override with custom rules for each theme”
Set Christmas to Window with 30 days
Set Halloween to Month mode
If testing in December, Christmas theme should appear 30 days before Dec 25
If testing in October, Halloween theme should appear all month
Check preview error messages if no theme matches

Testing Responsive Design

Desktop Test	Resize browser to 1200px+ and verify single-row horizontal layout
Tablet Test	Resize to 800px and verify two-row layout (badge/message, then timer/CTA)
Mobile Test	Resize to 450px and verify message hidden, smaller timer segments
Tiny Mobile Test	Resize to 320px and verify 2×2 timer grid

Testing Easter Date

Easter uses a computed algorithm (Gauss Easter algorithm):

Easter 2024: March 31
Easter 2025: April 20
Easter 2026: April 5
Test by temporarily setting system date or using browser dev tools

Pro Tip: Use browser DevTools to test different viewport sizes without manually resizing. Open DevTools, click device toolbar icon, and select various devices.