GCal Days

This plugin provides a shortcode and a set of functions to return the number of days since the most recent past event in your Google Calendar matching specified search terms. The shortcode can also be used to return the number of days until the closest upcoming event matching specified search terms.

The Shortcode

[gcal-days search="" type="" id=""]

The shortcode name is gcal-days. It has three attributes, but only one of which is absolutely necessary:

• search: (Required.) The search term.
• type: (Optional.) The direction in time to search. Defaults to “since”, which searches past events. “until” will search future events.
• id: (Conditionally optional.) The ID of the calendar to search. You can discover the IDs of calendars via the plugin’s settings page. This shortcode attribute can only be optionally omitted from shortcodes if you define a default calendar in the plugin’s settings.

The shortcode outputs a number representing the number of days until a matching event. If no event is found, a -1 will be displayed.

Examples: [gcal-days search="dentist"], [gcal-days type="until" search="vacation" id="test_lkjsadf987asdf24@group.calendar.google.com"]

Links: Plugin Homepage | Plugin Directory Page | Author Homepage

Functions

The plugin provides two functions for use in your theme templates, functions.php, or in plugins.

Functions

• <?php function gcal_days_since( $search, $calendar_id = '' ) ?>
• <?php function gcal_days_until( $search, $calendar_id = '' ) ?>

Arguments

• $search (string)
  Required. The word or phrase to search for

• $calendar_id (string)
  Optional. The ID for the Google Calendar. Check the plugin’s settings page for calendar IDs. This argument is only optional if you have defined a default calendar via the plugin’s settings.

Return Value

An integer value of the number of days since/until the matching event. -1 is returned if no event was found or an error was encountered.

Examples

• <?php // Days until next dentist appointment
$days_until = gcal_days_until( 'dentist' );
?>

• <?php
// Get the days since my last day off
$days_since = gcal_days_since( 'day off' );
// Echo a message using that number
if ( -1 == $days_since ) {
echo "You've never had a day off?! Take one soon!";
} else {
printf( _n( 'Your last day off was %d day ago.', 'Your last day off was $d days ago.', $days_since ), $days_since );
}
?>

1. Unzip gcal-days.zip inside the /wp-content/plugins/ directory for your site (or install via the built-in WordPress plugin installer).
2. Activate the plugin through the ‘Plugins’ admin menu in WordPress.
3. Visit the plugin’s setting page, ‘Settings’ -> ‘GCal Days’, and follow the link to obtain an authorization code from Google that permits the plugin access to your Google Calendar data.
4. Use the provided shortcode or functions, as per instructions.

Does that mean I am granting you (the plugin author) access to my Google Calendar data?

No. Google’s API allows for an app (such as this plugin) to be granted specific access (see next question). The access token is requested by the plugin and stored in your database. The data is only communicated back and forth between your site and Google via HTTPS.

What sort of access from Google is the plugin requesting?

The plugin is only requesting read-only access to Google Calendars. As such, the plugin will not be able to make any changes to your calendars, nor will it be able to access data associated with other Google services.

Why isn’t a calendar change I just made in Google Calendar being recognized by the plugin?

To avoid the expense of making network connections to Google for every page load, information is cached for a short period of time. You may have to wait a few minutes after calendar changes before expecting to see those changes reflected in the plugin.