How to Add a Countdown Timer to Events in Brilliant Directories (Step-by-Step)

Introduction

Hi there! Here's a step-by-step tutorial on how to add a countdown timer for your events. I hope you enjoy implementing it and find it useful for your directory.

How it works

The code grabs the start date and time of the event and displays a countdown timer.

💡

Note: If no time is provided, the code will default to 12:00 AM.

Just in case it doesn't work with recurring events, the code includes a validation to avoid displaying the timer for those.

Creating the Custom Widgets

First, we need to create the widgets. Technically, it could be just one, but to make things easier for both of us, let's create two — one for the search page and another for the detail page. This way, we can keep the styles separate for each case.

Let's get started with the first widget:

Visit managemydirectory and go to Toolbox > Widget Manager in the left sidebar.
Click the New Widget button.
Name the widget countdown-event-details.
Copy and paste the code below to add all the functionality and design.

<?php
/**
 * Simple Countdown Timer
 *
 * This script generates a customizable countdown timer based on a start date and time.
 * It's designed to be easily embedded and supports multiple timers on the same page.
 */
 
/*
 * Only display the countdown if the 'recurring_type' is 0.
 * This ensures that the timer only appears for non-recurring events.
 */
if (isset($post['recurring_type']) && $post['recurring_type'] == 0):
 
/*
 * Customizable options.
 * Users can change these values to alter the countdown's appearance.
 */
$backgroundColor = '#000000'; /* The background color of the countdown container. */
$fontFamily = 'Arial, sans-serif'; /* The font for the text. */
$fontSize = '12px'; /* The font size for the labels (Days, Hours, etc.). The numbers will be larger. */
$fontColor = '#ffffff'; /* The color of the text. */
$borderRadius = '5px'; /* The roundness of the container's corners. */
$padding = '20px'; /* The padding of the countdown container. */
 
/*
 * The start date and time for the event.
 * In a real scenario, this would come from a database or post meta.
 * For this example, we use the values you provided.
 */
$start_date = $post['post_start_date']; /* Example Date: YYYYMMDD */
$start_time = $post['start_time']; /* Example Time: H:MM AM/PM */
 
/*
 * Validate start_time.
 * If it's empty or not provided, default to 12:00 AM.
 */
if (empty($start_time)) {
    $start_time = '12:00 AM';
}
 
/*
 * We generate a unique ID for each countdown timer.
 * This is crucial for ensuring that if multiple countdowns are on the same page,
 * their scripts do not conflict with each other.
 */
$unique_id = 'countdown_' . uniqid();
 
/*
 * Create a DateTime object from the start date and time.
 * This helps in converting the date to a format that JavaScript can easily understand.
 * We're converting it to ISO 8601 format (e.g., "2025-06-03T08:00:00+00:00").
 */
$datetime_string = $start_date . ' ' . $start_time;
$datetime_object = DateTime::createFromFormat('Ymd g:i A', $datetime_string);
$iso_datetime = $datetime_object ? $datetime_object->format('c') : '';
 
?>
 
<!--
 * The HTML structure for our countdown timer.
 * We use the unique ID generated earlier.
 * Inline styles are applied based on the customizable PHP variables.
 * A data-target-date attribute is used to pass the event date to our JavaScript.
-->
<div id="<?php echo $unique_id; ?>"
     class="countdown-container"
     style="background-color: <?php echo htmlspecialchars($backgroundColor); ?>;
            font-family: <?php echo htmlspecialchars($fontFamily); ?>;
            font-size: <?php echo htmlspecialchars($fontSize); ?>;
            color: <?php echo htmlspecialchars($fontColor); ?>;
            border-radius: <?php echo htmlspecialchars($borderRadius); ?>;
            padding: <?php echo htmlspecialchars($padding); ?>;
            text-align: center;
            width: 100%;
            box-sizing: border-box;
            margin: 10px 0;"
     data-target-date="<?php echo htmlspecialchars($iso_datetime); ?>">
 
    <div class="countdown-item" style="display: inline-block; margin: 0 10px;">
        <span class="days" style="display: block; font-weight: bold; font-size: 3em; line-height: 1;">0</span>
        <div>Days</div>
    </div>
    <div class="countdown-item" style="display: inline-block; margin: 0 10px;">
        <span class="hours" style="display: block; font-weight: bold; font-size: 3em; line-height: 1;">0</span>
        <div>Hours</div>
    </div>
    <div class="countdown-item" style="display: inline-block; margin: 0 10px;">
        <span class="minutes" style="display: block; font-weight: bold; font-size: 3em; line-height: 1;">0</span>
        <div>Minutes</div>
    </div>
    <div class="countdown-item" style="display: inline-block; margin: 0 10px;">
        <span class="seconds" style="display: block; font-weight: bold; font-size: 3em; line-height: 1;">0</span>
        <div>Seconds</div>
    </div>
</div>
 
<script>
/*
 * This is the JavaScript function that powers the countdown.
 * It is designed to be self-contained and reusable for any countdown on the page.
 */
function initializeCountdown(containerId) {
    /* Get the HTML element that holds our countdown timer. */
    var countdownContainer = document.getElementById(containerId);
    if (!countdownContainer) {
        /* If the element doesn't exist, stop the script to prevent errors. */
        return;
    }
 
    /* Read the target date from the 'data-target-date' attribute we set in our HTML. */
    var targetDateStr = countdownContainer.getAttribute('data-target-date');
    if (!targetDateStr) {
        /* If the date is not provided, stop the script. */
        return;
    }
 
    var targetDate = new Date(targetDateStr).getTime();
 
    /* Find the elements where we will display the numbers (days, hours, minutes, seconds). */
    var daysEl = countdownContainer.querySelector('.days');
    var hoursEl = countdownContainer.querySelector('.hours');
    var minutesEl = countdownContainer.querySelector('.minutes');
    var secondsEl = countdownContainer.querySelector('.seconds');
 
    /*
     * This function will be called every second to update the displayed time.
     */
    var updateCountdown = function() {
        /* Get the current date and time. */
        var now = new Date().getTime();
 
        /* Calculate the difference in time between now and the target date. */
        var distance = targetDate - now;
 
        /* If the countdown is finished, display all zeros. */
        if (distance < 0) {
            clearInterval(interval); /* Stop the countdown. */
            daysEl.innerHTML = 0;
            hoursEl.innerHTML = 0;
            minutesEl.innerHTML = 0;
            secondsEl.innerHTML = 0;
            return;
        }
 
        /* Time calculations for days, hours, minutes and seconds. */
        var days = Math.floor(distance / (1000 * 60 * 60 * 24));
        var hours = Math.floor((distance % (1000 * 60 * 60 * 24)) / (1000 * 60 * 60));
        var minutes = Math.floor((distance % (1000 * 60 * 60)) / (1000 * 60));
        var seconds = Math.floor((distance % (1000 * 60)) / 1000);
 
        /* Update the HTML with the new values. */
        daysEl.innerHTML = days;
        hoursEl.innerHTML = hours;
        minutesEl.innerHTML = minutes;
        secondsEl.innerHTML = seconds;
    };
 
    /*
     * Run the updateCountdown function every 1 second (1000 milliseconds).
     */
    var interval = setInterval(updateCountdown, 1000);
 
    /* Run it once immediately so we don't see a delay. */
    updateCountdown();
}
 
/*
 * Call the function with the unique ID of our countdown timer.
 * This starts the countdown.
 */
initializeCountdown('<?php echo $unique_id; ?>');
 
</script>
<?php endif; /* End of recurring_type check */ ?>

Finally, click Save Changes.

Second Widget

Follow the same steps as above, but name the widget countdown-event-loop.
Copy and paste the same code we used before.
Finally, click Save Changes.

Adding the Widget to the Event Feature

Now we need to add the widgets to the feature. There are two places where we need to insert the widget.

Let's start with the first one:

Visit managemydirectory and go to My Content > Edit Post Settings in the left sidebar.
Find the Events feature and click Edit.
Click on the Search Results Design tab, then click the Click To View/Edit Code button.

Scroll down to the Page Loop Code section.

Here we need to add the widget using this code: [widget=countdown-event-loop]. This part is a bit tricky, because where you place the countdown depends on where you want it to appear. In my case, I added the code right after the title.

Let's move on to the second place:

On the same page, scroll up and click on the Detail Page Design tab.
Then click the Click To View/Edit Code button.

Here we face the same situation — where you want the countdown to appear will determine where you need to place the code: [widget=countdown-event-details]. In my case, I added it at the top of the page.

And finally, click the Save Changes button.

The Code

At this point, both widgets use the same code. The code is well-commented so you can read and understand it in case you want to get your hands dirty and make some changes.

Here are a few things you can tweak without modifying the core logic — just for styling purposes:

$backgroundColor = '#000000'; /* The background color of the countdown container. */
$fontFamily = 'Arial, sans-serif'; /* The font for the text. */
$fontSize = '12px'; /* The font size for the labels (Days, Hours, etc.). The numbers will be larger. */
$fontColor = '#ffffff'; /* The color of the text. */
$borderRadius = '5px'; /* The roundness of the container's corners. */
$padding = '20px'; /* The padding of the countdown container. */

As you can see, you can display the countdown timer differently in each case.

You're free to change as much as you want, but I've tried to keep things simple for you.

If you want to customize the code but don't know much about coding, just copy and paste it into ChatGPT or Gemini and ask for the changes you want.

Best case? You get exactly what you were looking for and learn how to use AI to help you code.

Worst case? No worries — just come back here and copy the original code again 😅

QA

I hope you've made it this far — now comes the fun part: checking that everything is working!

Make sure you have some live events so you can test it properly. There are three places where the countdown will be displayed:

The event search results
The member profile page under the Events tab
The event detail page

Conclusion

Congratulations! You've now implemented a countdown timer for your events.

I hope this is helpful for both you and your users. If you run into any issues, feel free to let me know in the comments of this tutorial on my Facebook page. I'll be adding a comment section here in the future.

I truly hope you enjoyed this tutorial as much as I enjoyed creating it. I put a lot of heart into it, and I'd love it if you considered signing up! 🙌