Google Calendar List View

The plugin is to create a shortcode for displaying the list view of a public Google Calendar.  If you want to use a multi-Google Calendar later,  you can specify them in the shortcode options.

Google Calendar List View

Latest version

  • 28 Feb, 2023: Update 7.1.0(PHP8.2 compatible).
    Changes include. The handling of ${} variables such as ${html_tag_class} has been deprecated in PHP8.2, so the description method has been changed to something like {$html_tag_class}.


  • <ul>[gc_list_view]</ul>

If you only use a public Google calendar, you can use the setting values of "Google Calendar API Key" and "Google Calendar ID".If you want to use multi Google Calendar later,  you can specify them in the shortcode options. Version 4.0 supports the multi Google Calendars. If you want to add 2 or more Google Calendars, set g_id_*** shortcode option. You can set an unique key as ***. If you want to set an Google Calendar API key on each Google Calendar ID, set g_api_key_*** with g_id_***.
In case of using the default values, please put the shortcode as Text mode because it needs to use <ul> tag. If you use "p" value on html_tag, you can use Visual mode.

  • [gc_list_view html_tag="p"]

Or if you want to customize the output values, please use the following hook.

Options on Shortcode (Version 6.8)

The shortcode is to display the list (default 10 items) of public Google Calendars from now (start_date)  to the future.  The default date format is YYYY.MM.DD. The sort is the ascending on start_date.

  • [gc_list_view start_date="YYYY-MM-DD/ALL" end_date="YYYY-MM-DD" date_format="Y.m.d" orderbysort="descending/ascending" g_id="Google Calendar ID" g_api_key="Google Calendar API Key" max_view=10 max_display="" html_tag="li/p/dd/lip/li2/li-month" html_tag_class="" id="" hook_secret_key="" lang="" enable_view_category="" g_id_***="Additional Google Calendar ID" g_api_key_***="Additional Google Calendar API Key with g_id_***" view_location="" no_event_message="" view_location_name="" no_event_link="" view_end_date=""]

The following shortcode option is priority than setting values.

  • start_date  is the value of "Start Date" (Default value is empty (= current date)). If "ALL" value is setting up, start_date value become to be unlimited.  Supported the datetime date format. Various date formats for datetime, such as "now", "+1 days", "-2 days", "yesterday", "-1 week", and so on can be used. date format is supported. "-2 days" means 2 days ago from current time. "+1 days" means 1 day later from current time.
  • end_date is the value of "End Date". (datetime  date format is supported.) If you want to specify up to today, you can use the setting end_date="now".
  • date_format is the date format (Y.m.d = YYYY.MM.DD). The format style is date format. If it changes d-m-Y,  it can display DD-MM-YYYY.
  • orderbysort can select "ascending" or descending" (default = "descending"). It behaves like ordersort by Google Calendar API v2.
  • g_id is Google Calendar ID. If you use multi Google Calendar, set this value.
  • g_api_key isGoogle Calendar API Key. If you use multi Google Calendar API Key, set this value.
  • max_view is the maximum number of view. Default is 10 (same as maxResults value in Google Calendar API Settings).
  • max_display : Default is empty. The option isn’t needed if "lang" option isn’t used.  "max_view" is for getting the number of items from Google Calendars. "max_display" is for displaying the number of items. If "max_display" isn’t set, "max_display" is automatically set the value of "max_view" value. If there are mixed events (1.2.3. events in Japanese, 5.6.7. events in English) and set "max_view=5", lang="en", 5. and 6. events are only displayed. Therefore, you need to set "max_view" is 6 or more and "max_display" is 5. By these shortcut options, the plugin gets 6 or more events and picks up 5 events in English among 6 or more events.
  • html_tag is a specifies the display template for each event. li, p, dd, lip, li2, and li-month can be specified, and if any other value is set, <li> will be set. If any other value is set, <li> will be set. class="list-view-google-calendar"> will be set. li2 will display a group of events with the same style and date as the li tag. li-month can be displayed by month. If you want to customize the display, you can use the hooks described below.
  • html_tag_class is html_tag class. Default is list-view-google-calendar (<html_tag class="list-view-google-calendar">***</html_tag>).
  • id is an unique key for the plugin hooks. If you want to customize the value using a hook each a shortcode, id can use a unique key.
  • hook_secret_key is for safely using a hook. If you use this plugin’s hook, please set this key and return ‘hook_secret_key’ in the hook. In detail, please see ‘Hook’ section in this document.
  • lang is for outputting only specific events including #lang [value] in a description on a event. If you want to output  events in English from only a Google Calendar, write #lang en in the description on a event and setting up lang="en" on shortcode.
  • enable_view_category = If the value is not empty, the category is displayed for #type and #organizer tag (ex. 22/10/2017 Category Organizer Title)
  • g_id_*** = If you want to add 2 or more Google Calendars, set the key. You can set an unique key as ***.
  • g_api_key_*** = If you want to set an Google Calendar API key on each Google Calendar ID, set g_api_key_*** with g_id_***.
  • view_location = If the value is not empty, the "location" in the calendar event is displayed on the next line after the title.
  • no_event_message = Sets the message when there are no events. If unset the option or empty, the message “There are no events. If none is set, the setting will be hidden.
  • view_location_name = Changes the title name that is displayed when the view_location option is enabled (non-empty value). If the value is empty, the default value (Location:) will be set.
  • no_event_link = If the “no_event_link” option is enabled (a non-empty value), the link to the event will be removed.
  • view_end_date = If the view_end_date value isn’t empty, the end date is displayed, using the value of view_end_date as the delimiter string after the start date.

How to create Google Calendar API Key

I think I don’t need to explain it because above document is very nice! Please keep in mind that there is query limitation (Google Calendar API Usage Limits).

How to find Google Calendar ID

Please see above document, you can find it!

For example

In the following example, two sample google calendars  "Public Calendar 1" and "Public Calendar 2"

Public Calendar 1

  • 2017.04.07 TEST Event 3 on Public Calendar 1
  • 2017.04.04 TEST Event 2 on Public Calendar 1
  • 2017.04.02 TEST Event 1 on Public Calendar 1

Public Calendar 2

  • 2017.04.14 TEST Event 3 on Public Calendar 2
  • 2017.04.11 TEST Event 2 on Public Calendar 2
  • 2017.04.10-12 TEST Event 1 on Public Calendar 2


If you input the following code on Text mode to a Page or a Post (Tested on April 9, 2017).

「Public Calendar 1」
[gc_list_view g_id="◯◯" start_date="ALL" orderbysort="descending"]
「Public Calendar 2」
<dt>List View of Google Calendar Events</dt>
[gc_list_view g_id="◯◯" orderbysort="descending" html_tag="dd"]

The following content is displayed.

If you click each link, a detail page of the Google Calendar event is displayed as new window.

"Public Calendar 1" is all past data on April 9, 2017, so it needs to set start_date="ALL" or start_date="2017-04-01" option if you want to display the past events.

What’s kind of settings?

There are settings on "Google Calendar List View Settings" in the setting menu of the administration dashboard.

Google Calendar API Settings

Output Settings

Hooks & Notice

How to use Hooks

The following codes were tested on functions.php in the theme.
Please keep in mind that the output data can be changed from the following hooks.
Therefore, please pay attention the security countermeasure.


Array for a Hook

Since version 5.9, the reference of the original resources in Google Calendar event are available from the hook. If you want to refer the resources, you specify add_filter( 'lvgc_each_output_data', 'function name', 10, 3 ); and function function-name ($out, $out_atts, $gc_value) .

$out_atts use in each hook.
if you use "extract($out_atts);", you can use the following variables.

  • $start_date_num = Event Start date  (Ymd)
  • $start_date_value = Event Start date (Converted date_format)
  • $end_date_num = Event End date (Ymd)
  • $end_date_value = Event End date (Converted date_format)
  • $today_date_num = Today (Ymd)
  • $holding_flag = true/false (If the today is held on the event, the value is true.)
  • $gc_link = Link for Google Calendar Event of each event
  • $gc_title = Event Title
  • $gc_description = Event Description (supported HTML tag escaped wp_kses_post.
  • $gc_location = Event Location
  • $plugin_name = Plugin Name
  • $html_tag_class = Base of HTML tag class
  • $html_tag_class_c = HTML tag class (If a event is been holding today, the class is set {$html_tag_class}_holding. Else the class is set $html_tag_class.)
  • $id = id on shortcode option
  • $lang = lang on shortcode option
  • $hash_tags = Hash tag data on each event ( array( "hash_tag"=>array("value"=>"", "title"=>""), ..); )
  • $hash_tags_type_title = hash_tag_title value (= $hash_tags['type']['title']) in #type on each event (#type hash_tag_category hash_tag_title)
  • $hash_tags_type_organizer = the has_tag_name value(= $hash_tags['organizer']['value']) in #type on each event (#organizer has_tag_name)
  • $output_category_temp = IF the shortcode option "enable_view_category" is not empty, the html tag for displaying #type, #category items is set (default is empty)
  • $hash_tags_display_value = hash_tags_display_value value (= $hash_tags['display']['value']) in #display none or #display off on the each event. When “#display none” or “#display off” in the event description, the event isn’t displayed.
  • $element_count = The element count for using the “lvgc_each_output_data” hook.
  • $gc_description_title = Excerpt of event description (max 1024 bytes).
  • $view_location_name = Used to specify the title name to be displayed when the view_location option is enabled (non-empty value).
  • $no_event_link = Used to determine if an event link is unnecessary.
  • $start_date_month_value = numeric data of the month of the event (YYYYmm format)
  • $pre_start_date_month_value = Numeric data of the month of the previous event (YYYYmm format)
  • $month_value = Name of the month of the event (in English).
  • $translate_month_values = event month name (translated by WordPress Core) – array format.
  • $view_end_date = delimiter string for separating start date and end date



The hook can change the output data in each item.

Default output is as below:

  • <class="list-view-google-calendar_item"><li class="list-view-google-calendar"><span class="list-view-google-calendar_date">Date</span> (In case of setting up #type or #organizer)<a class="list-view-google-calendar_link" href="Google Calendar Link" target="_blank" title="Excerpt from the event description">Title</a></li>
    (In case of setting up #type or #organizer) = <span class="list-view-google-calendar_category">"#type"’s second argument </span><span class="list-view-google-calendar_organizer">"#organizer"’s first argument</span>

Let’s code the above output data on a hook.

Firstly, please set "hook_secret_key" on a shortcode.

  • [gc_list_view *******  hook_secret_key="hogehoge"]

Then, add the following code to the functions.php in a theme.


If you want to refer original resources in Google Calendar event, please see the sample code.

If you want do a different change on each shortcode, you add "id" option in the shortcode and use the following code.

[gc_list_view g_id="hogehoge" id="99" hook_secret_key="hogehoge"]

[gc_list_view g_id="hoge" id="hoge" hook_secret_key="hogehoge"]

More Customizing

If you want to customize, please utilize above the attribution for the hook.
Ex. The following code is the "lip" template tag file.

* Output HTML

  • Code in functions.php (refer to this plugin folder/includes/tags/lip.php)

Notes on customizing li-month

When customizing using hooks, refer to library/tags/li-month.php, and use the traditional <ul> tag, please put </ul> in the next line of the shortcode to close it. This is because the hooks process each event, and you cannot set a closing tag at the end of the hooks when you put together monthly events.

The month name is limited to English because it uses the datetime function. If you want to make it in other languages, please write the code for that.
The following is a sample code for Japanese and Dutch-based on library/tags/li-month.php.


Notice: coding timezone

WordPress forcibly processes the date as UTC timezone. In other words, "date" and "i18_date" function don’t work on  WordPress if you want to code other timezone except UTC.  Therefore, you need to use WordPress date functions "current_time" and "get_date_from_gmt" instead of date and i18_date.

Get current time & convert date format

  • $current_time = currentitme("d-m-Y");  (03-04-2017 means April 3, 2017)

Convert date format: get_date_from_gmt

  • $start_date = get_date_from_gmt($item[‘start’][‘dateTime’], "d-m-Y");

The following example is to convert $start_date to the setting timezone on WordPress.

Change history (past version)

  • Nov 05, 2022: Update 7.0.0(Changed API acquisition method)
  • Mar 31, 2022: Update 6.9.2
  • Mar 30, 2022: Update 6.9, 6.9.1
  • Mar 27, 2022: Update 6.8
  • Feb 10, 2022: Update 6.7.2
  • Feb 7, 2022: Update 6.7.1
  • Feb 4, 2022: Update 6.7
  • Nov 21, 2021: Update 6.6
  • Apr 22, 2021: Update 6.5.2
  • Apr 21, 2021: Update 6.5.1
  • Apr 21, 2021: Update 6.5(Added “no_event_link” shortcode option.)
  • Apr 18, 2021: Update 6.4, 6.4.1(Add shortcode option view_location_name.)
  • Apr 16, 2021: Update 6.3(Added the ability to show excerpt of event description (max 1024 bytes) when you mouse over the event link)
  • Mar 20, 2021: Update 6.2
  • Mar 16, 2021: Update 6.1
  • Mar 15, 2021: Update 6.0
  • Mar 05, 2021: Update 5.9.1
  • May 14, 2020: Update 5.9
  • Mar 08, 2020: Update 5.8
  • Feb 26, 2020: Update 5.7
  • Feb 04, 2020: Update 5.6
  • Jan 24, 2020: Update 5.5
  • Dec 13, 2019: Update 5.4
  • Nov 26, 2019: Update 5.3
  • Nov 11, 2019: Update 5.2
  • Jul 19, 2019: Update 5.1
  • Feb 14, 2019: Update 5.0
  • Sep 27, 2018: Updated 4.6
  • Sep 26, 2018: Updated 4.5 and 4.5.1
  • Sep 18, 2018: Updated 4.4
  • Jul 11, 2018: Updated 4.3
  • Nov 11, 2017: Updated 4.2
  • Oct 19, 2017: Updated 4.1
  • Sep 17, 2017: Updated 4.0
  • Aug 31, 2017: Updated 3.1
  • Aug 25, 2017: Updated 3.0
  • Aug 24, 2017: Updated 2.2
  • Jul 21, 2017: Updated 2.1
  • Jun 26, 2017: Updated 2.0
  • Jun 25, 2017: Updated 1.5, 1.51
  • Apr 18, 2017: Updated 1.3, 1.4, 1.41, and 1.42.
  • Apr 11, 2017: Updated 1.2.
  • Apr 10, 2017: Updated 1.1.
  • Apr 09, 2017: Released 1.0.

November 21, 2021 Fixed the documentation for version 6.6.
April 21, 2021 Fixed the documentation for version 6.5.
April 18, 2021 Fixed the documentation for version 6.4, 6.4.1.
April 16, 2021 Fixed the documentation for version 6.3.
March 16, 2021 Fixed the documentation for version 6.1.
March 15, 2021 Fixed the documentation for version 6.0.
August 25, 2017  Fixed the documentation for version 3.0.
August 24, 2017  Fixed the documentation for version 2.2.
July 21, 2017 Fixed the documentation for version 2.1.
June 26, 2017  Fixed the documentation for version 2.0.
June 25, 2017 @kimipooh