Week view refactor in 3.10: what you need to know

What's New

Jun 04 2015 Updated Mar 10 2022

Events Calendar Pro 3.10 will ship with a refactored Week view. This refactor was done so that Week view would be easier to understand under the hood, easier to customize, and more extensible. We’ve also added a couple new features.

Why We Did This

You may be wondering why we did this. Here is a list of the goals we wanted to accomplish with this refactor:

Make the code in the week view template class easy to follow. The naming conventions and logic in there were very complex and convoluted.
Take all logic out of the templates so that they are clean and easy to read for people who just want to make changes to their design.
Make sure all the template tags are sensibly named, so you can ideally tell what they do just by reading the names. Make sure they are consistently named (they all start with “tribe_events_week_” now)
Bring the week view template structure and general concept in line with how month view is done, I.E. create and make available an array of days to loop through, and a set of template tags that can be used to create a “week view loop” that nests to loop through each day in the week, and each day loops through each event in the day. This was sort of half implemented previously but didn’t really match up with the month view style exactly.
Add two new features that have been requested by the community (ideally adding new features will be much easier with the new cleaned up code structure): the ability to hide weekends on week view via a new setting, and the ability to specify a specific hour range that shows on week view via a new filterable array of hours.

What You Should Know

Here are the major takeaways that you should be aware of

CSS and markup changes have been very minimal, you will likely have no problems if your customizations are done through CSS only
Customizations that have Week view template overrides will likely no longer function correctly. We have taken care to ensure that there will be no fatal errors on your site, but you may not see any events on your Week view after you update, if you do not update your templates to use the new code.
If you have existing customizations, you will likely see a lot of deprecated notices if you have WP_DEBUG enabled.
The script that creates the custom scrollbar on the Week view layout has been changed to nanoscroller

Template Changes

Here’s an overview of what’s changed in each Week view template part:

Template Part	What’s Changed
pro/week.php	No change
pro/week/content.php	tribe_events_the_header_attributes( ‘week-header’ ) is now simply tribe_events_the_header_attributes()
pro/week/loop-grid-allday.php	Remove tribe_events_week_set_loop_type( ‘allday’ ) from the top of the template Remove $all_day_map = tribe_events_week_get_all_day_map(); from the top of the template Replace $all_day_array = array_filter( $all_day_map[0], “is_numeric” ); if ( ! empty($all_day_array) )with a simple check for $day[‘has_all_day_events’] Placeholder cells are now outputted in this file (when there are no all day events) Inside the week view loop, add $day = tribe_events_get_current_week_day(). $day is an array that holds all the information you need about the current day in the loop tribe_events_week_reset_the_day_map() is no longer needed Loop through $day[‘all_day_events’] and include the pro/week/single-event.php template, passing the current $event via the 3rd argument
pro/week/loop-grid-hourly.php	Remove tribe_events_week_set_loop_type( ‘hourly’ ); from the top of the template Remove the $hour_format definition from the top of the template Add $hours = tribe_events_get_week_hours(); to the top of the template Remove logic to determine $display_hour based on the EOD cutoff Loop through the $hours array to output the hour row headers and hour blocks Inside the week view loop, add $day = tribe_events_get_current_week_day(). $day is an array that holds all the information you need about the current day in the loop Loop through $day[‘hourly_events’] and include the pro/week/single-event.php template, passing the current $event via the 3rd argument
pro/week/loop-grid.php	New function tribe_events_week_day_header_classes() used to output classes on the day of week headers, no conditionals needed New function tribe_events_week_day_header() outputs the text inside the day of week header, no longer a need to check if day view is enabled New conditional check if ( tribe_events_week_has_all_day_events() ) before including the loop-grid-allday template part
pro/week/mobile.php	New dateDisplay expression replaces the need to check and output startTime and endTime separately
pro/week/nav.php	tribe_previous_week_link() is renamed to tribe_events_week_previous_link() tribe_next_week_link() is renamed to tribe_events_week_next_link()
pro/week/single-event.php	New file replaces both pro/week/single-event-allday.php and pro/week/single-event-hourly.php (you can still keep them separate if you want and they will load) “Placeholder” cells are no longer part of this file It’s no longer necessary to pass $event to tribe_events_week_event_attributes() Div wrapping h3.entry-title has been removed
pro/week/tooltip.php	No change
pro/week/single-event-allday.php	Removed in favor of pro/week/single-event.php
pro/week/single-event-hourly.php	Removed in favor of pro/week/single-event.php

Deprecated Stuff

Here’s a list of what’s been deprecated:

Deprecated Item	Replacement	Notes
tribe_events_week_is_current_today()	no replacement	You can achieve the same conditional check with this code: $current_day = tribe_events_week_get_current_day(); $current_day[‘is_today’];
tribe_events_week_set_loop_type()	no replacement	“loop type” concept has been removed, there is no longer a need for this template tag
tribe_events_week_the_day_map()	tribe_events_week_the_day()	tribe_events_week_the_day() will increment the counter for the current day in the week view loop, similar to what the_post() does for a WordPress query
tribe_events_week_reset_the_day_map()	Tribe_Events_Pro_Week_Template::rewind_days();	this function is no longer necessary in your templates
tribe_events_week_get_the_day_display()	tribe_events_week_day_header()	tribe_events_week_day_header() will output all the text needed in your day header cells
tribe_events_week_get_all_day_map()	no replacement	this function is no longer necessary in your templates
tribe_events_week_get_hourly()	no replacement	this function is no longer necessary in your templates
tribe_events_week_setup_event()	no replacement	this function is no longer necessary in your templates
tribe_events_week_get_event_id()	no replacment	you can get the current event id from the global $post
tribe_events_week_is_all_day_placeholder()	no replacement	this function is no longer necessary in your templates
tribe_events_week_get_event()	no replacement	you can get the current event from the global $post
tribe_events_current_week_day_has_events()	tribe_events_week_get_current_day()	tribe_events_week_get_current_day() returns an array with information about the current day. you can simply check the ‘has_events’ element of that array
tribe_events_the_week_event_attributes()	echo tribe_events_week_event_attributes()
tribe_previous_week_link()	tribe_events_week_previous_link()	renamed for consistency
tribe_events_week_next_link()	tribe_events_week_next_link()	renamed for consistency

New Template Tags

Here’s a list of the new template tags we’ve added:

Function	What it does
tribe_event_is_on_date()	Given a $date and an $event, returns true or false if the event is happening on that date This function properly adjusts for the EOD cutoff and multi-day events
tribe_events_week_get_current_day()	Return current day in the week loop. Returned array has the following data: ‘date’ => date formatted Y-m-d ‘day_number’ => 0 – 6; 0 = Sunday, 6 = Saturday ‘formatted_date’ => date formatted for display (the format can be changed in events settings) ‘is_today’ => whether the day is today ‘is_past’ => whether the day has passed ‘is_future’ => whether the day is in the future ‘hourly_events’ => an array of the hourly events on this day ‘all_day_events’ => an array of the all day events on this day ‘has_events’ => boolean whether there are any events on this day, either all day or hourly
tribe_events_week_has_all_day_events()	Check if there are any all day events this week
tribe_events_week_get_hours()	Return the hours to display on week view. Optionally return formatted, first, or last hour.
tribe_events_week_get_days()	Return the range of days to display on week view.
tribe_events_week_day_header_classes()	Return the classes used on each week day header.
tribe_events_week_day_header()	Return the text used in week day headers wrapped in a <span> tag and data attribute needed for mobile js
tribe_events_the_week_event_attributes()	Echo html attributes required for proper week view js functionality

New Features

As was mentioned under “Why we did this”, we have added two new features to the Week view. Those are:

An option to hide weekends. This comes in the form of a new checkbox on the Events > Settings > Display tab called “Hide weekends on Week View”.
The ability to customize what hours are displayed on the Week View grid. This can be done via a filter called ‘tribe_events_week_get_hours’. If you hook into that filter, you will receive an array of the 24 hours of the day. You can remove hours you don’t want to display and return the array. The array should be such that the keys are the hour, from 0 to 23, and the values are the hours in the format you would like to display them. For example, see this gist

UI Improvements

In addition to making the new week view easier to customize, we made a few small enhancements and corrected some bugs from the old week view. Here is a list of those changes:

Tweak – Updated tooltip positioning logic for week view to account for more edge cases
Tweak – Updated week view to better handle very short events and long titles (thanks to csikimacko for the heads up!)
Bug – Fixed issues with all day multiday events in Week View when Week Starts On was changed (thanks to Mark Root-Wiley for reporting this!)
Bug – Fixed a bug where resizing browser window caused Week View header to expand its height
Bug – Fixed a bug with the tooltip improperly HTML escaping characters twice (thanks to evertramos on the dot-org forums for the report!)