* Milestone Countdown Widget
* @package automattic/jetpack
use Automattic\Jetpack\Assets;
if ( ! defined( 'ABSPATH' ) ) {
class Milestone_Widget extends WP_Widget {
* Holding array for widget configuration and localization.
private static $config_js = array();
* Available time units sorted in descending order.
protected $available_units = array(
* Milestone_Widget constructor.
public function __construct() {
'classname' => 'milestone-widget',
'description' => __( 'Display a countdown to a certain date.', 'jetpack' ),
/** This filter is documented in modules/widgets/facebook-likebox.php */
apply_filters( 'jetpack_widget_name', __( 'Milestone', 'jetpack' ) ),
add_action( 'wp_enqueue_scripts', array( __CLASS__, 'enqueue_template' ) );
add_action( 'admin_enqueue_scripts', array( __CLASS__, 'enqueue_admin' ) );
add_action( 'wp_footer', array( $this, 'localize_script' ) );
if ( is_active_widget( false, false, $this->id_base, true ) || is_active_widget( false, false, 'monster', true ) || is_customize_preview() ) {
add_action( 'wp_head', array( __CLASS__, 'styles_template' ) );
* @param string $hook_suffix Hook suffix provided by WordPress.
public static function enqueue_admin( $hook_suffix ) {
if ( 'widgets.php' === $hook_suffix ) {
wp_enqueue_style( 'milestone-admin', plugin_dir_url( __FILE__ ) . 'style-admin.css', array(), '20201113' );
Assets::get_file_url_for_environment(
'_inc/build/widgets/milestone/admin.min.js',
'modules/widgets/milestone/admin.js'
* Enqueue the frontend JS.
public static function enqueue_template() {
if ( class_exists( 'Jetpack_AMP_Support' ) && Jetpack_AMP_Support::is_amp_request() ) {
Assets::get_file_url_for_environment(
'_inc/build/widgets/milestone/milestone.min.js',
'modules/widgets/milestone/milestone.js'
* Output the frontend styling.
public static function styles_template() {
--milestone-text-color: <?php echo self::sanitize_color_hex( $colors['text'] ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped ?>;
--milestone-bg-color: <?php echo self::sanitize_color_hex( $colors['bg'] ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped ?>;
--milestone-border-color:<?php echo self::sanitize_color_hex( $colors['border'] ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped ?>;
* Ensure that a string representing a color in hexadecimal
* notation is safe for use in css and database saves.
* @param string $hex Hexademical code to sanitize.
* @param string $prefix Prefix for the hex code.
* @return string Color in hexadecimal notation on success - the string "transparent" otherwise.
public static function sanitize_color_hex( $hex, $prefix = '#' ) {
/* Strip recognized prefixes. */
if ( str_starts_with( $hex, '#' ) ) {
$hex = substr( $hex, 1 );
} elseif ( str_starts_with( $hex, '%23' ) ) {
$hex = substr( $hex, 3 );
if ( 0 !== preg_match( '/^[0-9a-fA-F]{6}$/', $hex ) ) {
* Localize Front-end Script.
* Print the javascript configuration array only if the
* current template has an instance of the widget that
* is still counting down. In all other cases, this
* function will dequeue milestone.js.
* Hooks into the "wp_footer" action.
public function localize_script() {
if ( class_exists( 'Jetpack_AMP_Support' ) && Jetpack_AMP_Support::is_amp_request() ) {
if ( empty( self::$config_js['instances'] ) ) {
wp_dequeue_script( 'milestone' );
self::$config_js['api_root'] = esc_url_raw( rest_url() );
wp_localize_script( 'milestone', 'MilestoneConfig', self::$config_js );
* Return an associative array of default values
* These values are used in new widgets.
* @return array Array of default values for the Widget's options.
public function defaults() {
$now = current_datetime();
$now_timestamp = $now->getTimestamp();
'event' => __( 'The Big Day', 'jetpack' ),
'message' => __( 'The big day is here.', 'jetpack' ),
'day' => gmdate( 'd', $now_timestamp ),
'month' => gmdate( 'm', $now_timestamp ),
'year' => gmdate( 'Y', $now_timestamp ),
* @param array $args Widget args.
* @param array $instance Widget instance.
public function widget( $args, $instance ) {
$instance = wp_parse_args( $instance, $this->defaults() );
$this->enqueue_scripts();
echo $args['before_widget']; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
/** This filter is documented in wp-includes/widgets/class-wp-widget-pages.php */
$title = apply_filters( 'widget_title', $instance['title'] );
if ( ! empty( $title ) ) {
echo $args['before_title'] . $title . $args['after_title']; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
$widget_id = ! empty( $args['widget_id'] ) ? $args['widget_id'] : 'milestone_widget';
$data = $this->get_widget_data( $instance );
'message' => $data['message'],
'refresh' => $data['refresh'],
* Sidebars may be configured to not expose the `widget_id`. Example: `twentytwenty` footer areas.
* We need our own unique identifier.
$config['content_id'] = $widget_id . '-content';
self::$config_js['instances'][] = $config;
printf( '<div id="%s" class="milestone-content">', esc_html( $config['content_id'] ) );
echo '<div class="milestone-header">';
echo '<strong class="event">' . esc_html( $instance['event'] ) . '</strong>';
echo '<span class="date">' . esc_html( date_i18n( get_option( 'date_format' ), $data['milestone'] ) ) . '</span>';
echo wp_kses_post( $data['message'] );
echo '</div><!--milestone-content-->';
echo $args['after_widget']; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
/** This action is documented in modules/widgets/gravatar-profile.php */
do_action( 'jetpack_stats_extra', 'widget_view', 'milestone' );
public function enqueue_scripts() {
plugins_url( 'milestone-widget.css', __FILE__ ),
* Getter for the widget data.
* @param array $instance Widget instance.
public function get_widget_data( $instance ) {
$instance = $this->sanitize_instance( $instance );
$milestone = mktime( $instance['hour'], $instance['min'], 0, $instance['month'], $instance['day'], $instance['year'] );
$now = (int) current_time( 'timestamp' ); // phpcs:ignore WordPress.DateTime.CurrentTimeTimestamp.Requested
$type = $instance['type'];
if ( 'since' === $type ) {
$diff = (int) floor( $now - $milestone );
$diff = (int) floor( $milestone - $now );
$data['unit'] = $this->get_unit( $diff, $instance['unit'] );
// Setting the refresh counter to equal the number of seconds it takes to flip a unit.
$refresh_intervals = array(
0, // should be YEAR_IN_SECONDS, but doing setTimeout for a year doesn't seem to be logical.
0, // same goes for MONTH_IN_SECONDS.
$data['refresh'] = $refresh_intervals[ array_search( $data['unit'], $this->available_units, true ) ];
$data['milestone'] = $milestone;
if ( ( 1 > $diff ) && ( 'until' === $type ) ) {
$data['message'] = '<div class="milestone-message">' . $instance['message'] . '</div>';
$data['refresh'] = 0; // No need to refresh, the milestone has been reached.
$interval_text = $this->get_interval_in_units( $diff, $data['unit'] );
$interval = (int) $interval_text;
if ( 'since' === $type ) {
switch ( $data['unit'] ) {
$data['message'] = sprintf(
/* translators: %s is the number of year(s). */
'<span class="difference">%s</span> <span class="label">year ago.</span>',
'<span class="difference">%s</span> <span class="label">years ago.</span>',
$data['message'] = sprintf(
/* translators: %s is the number of month(s). */
'<span class="difference">%s</span> <span class="label">month ago.</span>',
'<span class="difference">%s</span> <span class="label">months ago.</span>',
$data['message'] = sprintf(
/* translators: %s is the number of days(s). */
'<span class="difference">%s</span> <span class="label">day ago.</span>',
'<span class="difference">%s</span> <span class="label">days ago.</span>',
$data['message'] = sprintf(
/* translators: %s is the number of hours(s). */
'<span class="difference">%s</span> <span class="label">hour ago.</span>',
'<span class="difference">%s</span> <span class="label">hours ago.</span>',
$data['message'] = sprintf(
/* translators: %s is the number of minutes(s). */
'<span class="difference">%s</span> <span class="label">minute ago.</span>',
'<span class="difference">%s</span> <span class="label">minutes ago.</span>',
$data['message'] = sprintf(
/* translators: %s is the number of second(s). */
'<span class="difference">%s</span> <span class="label">second ago.</span>',
'<span class="difference">%s</span> <span class="label">seconds ago.</span>',
switch ( $this->get_unit( $diff, $instance['unit'] ) ) {
$data['message'] = sprintf(
/* translators: %s is the number of year(s). */
'<span class="difference">%s</span> <span class="label">year to go.</span>',
'<span class="difference">%s</span> <span class="label">years to go.</span>',
$data['message'] = sprintf(
/* translators: %s is the number of month(s). */
'<span class="difference">%s</span> <span class="label">month to go.</span>',
'<span class="difference">%s</span> <span class="label">months to go.</span>',
$data['message'] = sprintf(
/* translators: %s is the number of days(s). */
'<span class="difference">%s</span> <span class="label">day to go.</span>',
'<span class="difference">%s</span> <span class="label">days to go.</span>',
$data['message'] = sprintf(
/* translators: %s is the number of hour(s). */
'<span class="difference">%s</span> <span class="label">hour to go.</span>',
'<span class="difference">%s</span> <span class="label">hours to go.</span>',
$data['message'] = sprintf(
/* translators: %s is the number of minute(s). */
'<span class="difference">%s</span> <span class="label">minute to go.</span>',
'<span class="difference">%s</span> <span class="label">minutes to go.</span>',
$data['message'] = sprintf(
/* translators: %s is the number of second(s). */
'<span class="difference">%s</span> <span class="label">second to go.</span>',
'<span class="difference">%s</span> <span class="label">seconds to go.</span>',
$data['message'] = '<div class="milestone-countdown">' . $data['message'] . '</div>';
* Return the largest possible time unit that the difference will be displayed in.
* @param Integer $seconds the interval in seconds.
* @param String $maximum_unit the maximum unit that will be used. Optional.
* @return String $calculated_unit
protected function get_unit( $seconds, $maximum_unit = 'automatic' ) {
if ( $seconds >= YEAR_IN_SECONDS * 2 ) {
// more than 2 years - show in years, one decimal point.
} elseif ( $seconds >= YEAR_IN_SECONDS ) {
if ( 'years' === $maximum_unit ) {
// automatic mode - showing months even if it's between one and two years.
} elseif ( $seconds >= MONTH_IN_SECONDS * 3 ) {
// fewer than 2 years - show in months.
} elseif ( $seconds >= MONTH_IN_SECONDS ) {
if ( 'months' === $maximum_unit ) {
// automatic mode - showing days even if it's between one and three months.