JQUERY RESPONSIVE COUNTDOWN

If you have any questions that are beyond the scope of this help file, please feel free to email via my user page contact form here.

Table of Contents

1. Description
2. Quick Start Guide
3. Add Some Basic Options
4. Advanced Usage
5. Features
6. Options
7. Methods
8. Events

Description - top

This is a javascript based tool that uses the canvas object to animate SVG defined drawings. The tool uses a flip animation to display the remaining time to or the elapsed time from a target date. The tool detects change of width and height of its container object and responds accordingly. Since it uses vector data to draw the digits and the panels of the countdown, there is no change in the quality of the displayed drawings when it gets resized. The tool features around 30 options to customize but it can also be used in a simple configuration.

Quick Start Guide - top

1. In order to play, the tool needs to execute on a div that is relatively or absolutely positioned, because the tool creates layers of canvas objects within the div that are absolutely positioned. The div needs to have an id attribute in order to be easily selected. The div may have width defined with percent values. Every resize of browser will get detected by the tool and it will redraw accordingly. The height of the div is not important, because the tool will change it in order to draw the countdown. There is a parameter though that defines the maximum height the tool can have. Here is an example of a div object that can be used:

<div id="first_countdown" style="position: relative; width: 100%; height: 50px;"></div>

2. After you have created the div element you will need to import some Javascript files. These are jQuery, and the countdown plugin. In my demos, I add these in the header of the document.

<script src="http://code.jquery.com/jquery-1.9.1.js"></script>
<script type="text/javascript" src="jquery.responsive_countdown.js"></script>

3. Lastly you need to select the div element and run the countdown. It is possible to not specify any options and the default ones will be used.

<script>
 jQuery(document).ready(function($){  
  $('#first_countdown').ResponsiveCountdown();
 });  
</script>

Add Some Basic Options - top

The power of the tool comes with the setting of its wide array of options. The most important are the target date and the time zone.

1. Target date and time zone. It is possible to set a date in the future and handle the moment of reaching that date, or just count from a date. In example #4 of the demo I am setting the target date like this: target_date: new Date(); which means now, and also I set the time zone to time_zone = target_date.getTimezoneOffset()/(-60); which gets the time zone the user is in. If also the target_future option is set to false that gives you a counter starting from 00:00, no matter where the user is - also it will not listen for end event. Of course it is possible to just set a target date like this: target_date:"2020/10/25 00:00:00";. If target_future is set to true it will check for end event - it will also trigger if the countdown page is loaded after the end event.

jQuery("#first_countdown").ResponsiveCountdown({
  target_date:"2020/1/1 00:00:00",
  time_zone:0,target_future:true
});

2. Managing the groups. It is possible to show/hide the days, hours, minutes and seconds simply by using the show_dd, show_hh, show_mm, show_ss options. Also the number of day places can be set using the day_digits option.

jQuery("#first_countdown").ResponsiveCountdown({
  show_ss:true,show_mm:false,
  show_hh:false,show_dd:true,
  day_digits:4
});

3. Setting the label captions. User can change the captions of long and short labels for each group. When there is not enough space to show the long caption the tool shows the short caption. User can hide or show labels by setting the show_labels option.

jQuery("#first_countdown").ResponsiveCountdown({
  show_labels:true,
  days_long:"days",days_short:"dd",
  hours_long:"hours",hours_short:"hh",
  mins_long:"minutes",mins_short:"mm",
  secs_long:"seconds",secs_short:"ss"
});

4. Setting the colors. There are 8 colors that can be set and used in the tool. Two color groups are formed that alternate when more than one group is displayed. Each group has 3 colors. One for the digits (fillStyleSymbol1, fillStyleSymbol2) and 2 for color gradeint that is used for the panel (fillStylesPanel_g1_1, fillStylesPanel_g1_2, fillStylesPanel_g2_1, fillStylesPanel_g2_2). The last two colors define the color of the labels and minimal glow effect (text_color, text_glow). The colors can be set only by using the RGBA format. Transparency is not taken into account though for performance reasons.

jQuery("#first_countdown").ResponsiveCountdown({
  fillStyleSymbol1:"rgba(22, 47, 56, 1)",
  fillStyleSymbol2:"rgba(83, 173, 212, 1)",
  fillStylesPanel_g1_1:"rgba(56, 149, 163, 1)",
  fillStylesPanel_g1_2:"rgba(158, 245, 255, 1)",
  fillStylesPanel_g2_1:"rgba(0,0,0,1)",
  fillStylesPanel_g2_2:"rgba(20,61,85,1)",
  text_color:"rgba(83, 173, 212,1)",
  text_glow:"rgba(83, 173, 212,1)"
});

5. The height of the tool varies depending on the available width and the options selected for the tool. It is possible to set maximum height though which will limit the overall size of the tool.

jQuery("#first_countdown").ResponsiveCountdown({
  max_height:300
});

6. It is possible to space the groups (seconds, minutes, hours, days) of the countdown tool. To do that the groups_spacing option must be set. If set to 0, the space between groups is equal to the space between digits. If set to 1 additional digit space is added between groups. If set to five then 5x digit space is added between groups. It can also be a float number.

jQuery("#first_countdown").ResponsiveCountdown({
  groups_spacing:3
});

7. The groups can be divided further more by using symbols. The spacer option can be set to "none", "squares" or "circles" in order to place dividers as in digital clock. The spacer symbols use the color and glow of the labels. In the custom mode usage the spacer can be set to "custom", which shows thousand groups comma separator.

jQuery("#first_countdown").ResponsiveCountdown({
  spacer:"squares"
});

8. Labels look very pixelated in some mobile browsers, so I added a subtle glow. It can be turned off or set to custom integer value. Use 0 to turn it off.

jQuery("#first_countdown").ResponsiveCountdown({
  text_blur:2
});

Advanced Usage - top

The tool allows the use of few public methods, also the setting of complete event handler. Some other options concerning the font used for labels are available together with digit set definition and type of perspective.

1. There are six public methods. Two of them can pause and resume the animation. It is only the animation that is paused - the actual counting is still running. One method exists that can destroy the tool. Two methods are available for getting and setting options. To set options an array is send which alternates the name of the option and the value of the option. To get an option value only the name of the option is passed. One method is used to drive the tool in the so called custom mode.

var fc = jQuery('#first_countdown').ResponsiveCountdown();
fc.pause_anim();
fc.play_anim();
fc.set_options(["day_digits", 4, "max_height", 120]);
fc.get_option("day_digits");
fc.destroy_countdown();
fc.set_custom_state("00331245");

2. Setting of complete event handler. The tool gets destroyed on complete event, but user can define additional function to execute upon completion.

jQuery('#first_countdown').ResponsiveCountdown({
  complete: function(){alert('Hello world')}
});

3. Type of perspective. There are two types of perspective possible. "Single" type uses each digit individually to calculate the 3D view. The "group" type uses the countdown as a whole to determine the 3D projection.

jQuery("#first_countdown").ResponsiveCountdown({
  type3d:"group"
});

var fc = jQuery("#first_countdown").ResponsiveCountdown();
fc.set_options(["type3d, "group"]);

4. Digit sets. There are two sets of digits available. These are SVG definitions for the 0..9 symbols in 150x150 pixels rectangle split into two parts vertically. Oswald and Federation fonts are used. Also there are three panels defined. To set these option use set_id and pan_id variables.

jQuery("#first_countdown").ResponsiveCountdown({
  set_id:0,pan_id:0
});

5. Font options. I used 3 fonts in my demo - "Arial", "Verdana" and "Courier" to set the f_family option. It is good to use fonts that are widely used. To setup the font size the font_to_digit_ratio option is used. It defines the font size based on the size of the digits of the tool. Recommended values vary from 0.1 to 0.3, which stands for 10% to 30% of digits height. The labels_space options is used to define the total space used by labels and top padding to digits. Acceptable values for this option start from 1 and end around 1.25. If 1.2 is taken for example it will define 20% gap above the labels, where the percentage is based on the labels font size. If 1 is chosen that will mean no gap, because all the space (100%) will be taken by the labels. The space that is left for labels shows only below the tool. In previous versions, the space also was showing above the tool. While the tool is resized it calculates the font size, but you can define minimum and maximum font size with the min_f_size and max_f_size options.

jQuery("#first_countdown").ResponsiveCountdown({
  f_family:"Verdana",
  min_f_size:9,max_f_size:15,
  font_to_digit_ratio: 0.125, labels_space: 1.2
});

6. Using the public method get_option with counter_width parameter it is possible to get the width of the area that is actually used to draw the tool in the canvas objects.

var fc = jQuery('#first_countdown').ResponsiveCountdown();
var actual_width = fc.get_option("counter_width");

7. It is possible to use the tool in the so called custom mode. In this mode the tool does not act as a timer. It will wait for the use of the set_custom_state public method. It passes the value that will set the new_custom_state option in string format. This value is used to set the state of the digits. In this mode only the day digits group is used. It is needed to match the number of day digits day_digits to the number of symbols in the parameter passed by the set_custom_state method - for example if 5 day digits are used then parameter passed should look like this - "23045". It is required by the user to decide when the tool will change its state and pass the new state. In this mode the tool is only used for presentation. It is possible to divide the thousand groups with comma symbol. To use the custom mode use_custom_update must be passed with true value, initial custom state (new_custom_state option) must be passed in string format, day_digits option must be set and its value has to match the string length of new_custom_state, set show_labels to false to hide the labels, use spacer with "custom" value if you want to show thousand groups dividers. After setting the tool in custom mode you will have to call the set_custom_state to change the state of the digits.

c1 = jQuery("#first_countdown").ResponsiveCountdown({
  use_custom_update:true,new_custom_state:"0000099",
  set_id:0,pan_id:0,day_digits:7,
  show_labels:false,
  min_f_size:11,max_f_size:36,
  spacer:"custom",groups_spacing:5,text_blur:2
});
...
...
c1.set_custom_state("0000108");

8. The tool can be used with time settings that come from a server script. The server_now_date option can be used to pass the current date/time taken from the server. This option is used when the tool is created. The tool reads the client now date and uses the difference to calculate the remaining time from or to the target date. Note that if the time/date on the client is changed deliberately a reload of the page is needed in order for the tool to synchronize with the server time again. The example below uses a static value for server_now_date. In your live code you will have to put there a variable that holds the server now date - server_now_date:"<?php echo $server_time ?>" can be a possible usage.

c1 = jQuery("#first_countdown").ResponsiveCountdown({
  server_now_date:"2019/1/1 12:30:50",
  target_date:"2020/1/1 00:00:00"
});

Features - top

• Responsive behavior. The tool scales according to available width.
• Visual tool that assist you to create your unique countdown.
• Infinite color combinations. Solid color for the digits. Gradient color for the panels.
• Show hide groups.
• Two perspective modes.
• Two sets of digits. Three sets of panels.
• Setting of time zone.
• Setting of label captions.
• Setting of labels font, weight and size.
• Groups spacing. Groups divider - circles or squares.
• Usage of time settings coming from a server. Synchronization takes place only during the initialization of the tool.
• Custom mode, that allows setting of the digits by the usage of a public method.

Options - top

Methods - top

Events - top