WPListCal Documentation

WPListCal allows you to list upcoming events on your blog in a list or table format.  It plugs straight into the WordPress admin pages to let you keep track of events just like posts and pages.  You can then list events on a page or post using a shortcode, show events in your sidebar with a widget, or incorporate events into your theme files using a PHP function call.

Version Guide

WordPress 2.7 or later → Use WPListCal 1.3.5 (current stable release)
WordPress 2.5-2.6.3 → Use WPListCal 1.0.8.2
WordPress 2.0.3-2.3.3 → Use WPListCal 1.0.2

The Future

WPListCal is no longer under active development. Read more here.

Installation

1. Upload the wplistcal folder to the /wp-content/plugins/ directory
2. Activate the plugin through the ‘Plugins’ menu in WordPress

Upgrade

1. DO NOT DEACTIVATE THE PREVIOUS VERSION OF THE PLUGIN! Doing so could remove all your events.
2. Upload the wplistcal folder to the /wp-content/plugins/ directory
3. Deactivate and then activate the plugin in the ‘Plugins’ menu in WordPress

Usage

1. Change the default settings on the WPListCal options page
2. If you want to list your events on a page or post, use the [wplistcal] shortcode. Use the parameters in the example below. Leave out parameters to default to the options defined in the WPListCal settings page. (1.2 or later only)
   • Example: [wplistcal display_mode="list" event_format="%NAME%" date_format="M j, Y g:ia" max_events="-1" show_past_events="false" advance_days="-1" event_order="asc" hide_same_date="true" date2_time_format="g:ia" no_events_msg="No events!"]
3. If you want to list your events on a page or post, insert the tag <!--wplistcal--> in the body of the page/post
4. If you want to list your events somewhere in your theme files, insert <?php echo wplc_show_events(); ?>. You can set special parameters to overwrite the default options if you use the PHP function call. All parameters are optional, but you must preserve the ordering by passing in `null` for options that you want to use defaults for.
   • Display Mode (string): 'list' or 'table'
   • Event Format (string): The format of the list entries if Display Mode is set to 'list'. You can use the following variables: %NAME%, %LINK%, %LINKEDNAME%, %START%, %END%, %DESCRIPTION%, %AUTHOR%, and %EXPORTURL%.
   • Date Format (string): The format to display the start and end date and time. Uses the same date formatting that WordPress uses.
   • Max. Events (int): The maximum number of events to display, -1 for unlimited.
   • Show Past Events (boolean): true to show all events, false to show only current and future events
   • Maximum Advanced Notice (int): How many days in advance to display events, -1 for unlimited.
   • Event Order (string): ‘asc’ to show the closest event first or ‘desc’ to show the furthest event first.
   • Hide Same Date (boolean): Format the end date with the format string defined in the next parameter if it is on the same day as the start date.
   • Date 2 Time Format (string): If Hide Same Date is enabled, use this format string for the end date.
   • No Events Message (string): If there are no events, show this string instead, leave blank for none.
   • Example: <?php echo wplc_show_events('list', '%LINKEDNAME%: %START% - %END%{
%DESCRIPTION%} <a href="%EXPORTURL%">(export)</a>', 'M j, Y g:ia', -1, false, 30, 'asc', true, 'g:ia', 'Sorry, no events'); ?>

Dependent Statements (1.2 or later only)

You can make a statement dependent on the existence of a variable by wrapping it in curly brackets. By default, the statement will only print if the first variable in the statement is not empty. You cannot have nested dependent statements.

Example 1:

The statement in the curly brackets won’t print if %LOCATION% is empty

%TITLE%{ at %LOCATION%} on %START%

Example 2:

To print a literal curly bracket, escape it with ‘^’

%NAME%{ at %LOCATION} ^{new^}

Example 3:

To skip a variable when determining the dependent variable, escape its ‘%’ characters with ‘^’. This method also works to print a literal ‘%’ inside a dependent statement. In this example, the statement in the curly brackets will print if %LOCATION% is not empty. Note that %AUTHOR% will be properly substituted even though it is escaped.

%NAME%{ hosted by ^%AUTHOR^% at %LOCATION%}

Example 4: (invalid)

This example is invalid. You cannot have nested dependent statements.

%NAME%{ at %LOCATION%{ on %START%}}

Example 5:

However, you can have multiple dependent statements in a format.

%NAME%{ hosted by %AUTHOR%}{ at %LOCATION} on %START%

Example 6:

You can also make a statement dependent on a variable without printing the variable. To do so, wrap the variable name in square brackets “[]“. You can escape the square brackets with ‘^’. In this example, the “more” link will only print if there is a description:

%NAME%{[%DESCRIPTION%] <a href="#">more</a>}

Frequently Asked Questions

Where does WPListCal store events?

On activation time, the plugin adds a table called <prefix>_wplistcal that stores all your events.

What happens to my events when I deactivate the plugin?

On deactivation, the events table is dropped, so if you want to save your event data, back up the table before deactivating the plugin.

As of version 1.0.6, deactivation does nothing to your settings and events.

Why is WPListCal different from other WordPress calendar plugins?

WPListCal is specialized to provide clean list or table based output for you to style or reparse any way you’d like. Other calendar plugins force you to use a gregorian calendar view which may be inappropriate for many applications.

Why do some of my events show N/A for author and create date?

Events created before upgrading to version 1.1 did not have those values set, therefore WPListCal marks them as N/A.

I am unable to make events that start or end past January 19, 2038 at 3:14:08am

This is a known bug in PHP (id# 44209) and was fixed in version 5.2.6. The specific issue was that strtotime() did not support 64-bit timestamps.

Does WPListCal use any 3rd party libraries?

Yes, WPListCal is packaged with iCalcreator which is released under the GNU LGPL

My event times are all wrong after upgrading to WordPress 2.9.

Go to WordPress General settings and reset your timezone to a city rather than a manual UTC offset.

I love WPListCal and I’d like to buy you a beer to thank you.

Awesome, thanks. Just click the big orange Donate button above

Changelog

1.3.5

• FIXED: WordPressMU support on options page (thanks Gabriel Mazetto for the patch)
• FIXED: Multiple i18n bugs, now using date_i18n to allow localized dates (thanks Jonas for the patch)

1.3.4

• FIXED: Event cleanup link was pointed incorrectly and didn’t work properly
• FIXED: Linked “events” in the dashboard to match other dashboard counters

1.3.3

• FIXED: Updated compatible version to 2.9 (no code changes)

1.3.2

• FIXED: timezone_abbreviations_list() error

1.3.1

• FIXED: Event Operations page had an invalid link for Export

1.3

• NEW: Export single events from event listing (%EXPORTURL%)
• NEW: Refactored export and cleanup into one admin page
• FIXED: Resolved an issue where the upload settings are not updated on each activation of the plugin

1.2.2

• FIXED: WordPress 2.8 compatibility
• FIXED: Cursor is no longer ‘move’ for section headers in the event edit page since you can’t drag anyway

1.2.1

• FIXED: Table view didn’t show events
• NEW: Added POT file for translation

1.2

• NEW: Event cleanup
• FIXED: Updated admin menus to use WordPress Capabilities instead of user levels (fixes settings page bug)
• NEW: Conditional format strings (i.e. bracketed statements)
• NEW: Shortcode support
• FIXED: All timestamps are now based on the WordPress timezone option instead of server time

1.1.1

• FIXED: Moved the timezone functions into a PHP5-only block for back-compat
• FIXED: Load scripts only when we’re on a WPListCal page

1.1

• NEW: Updated all styles and elements for WordPress 2.7
• NEW: Menus refactored to fit into the new WordPress 2.7 menu structure
• NEW: Dashboard now shows number of events published
• NEW: Location field
• NEW: Widget support
• FIXED: Refactored code into separate files
• FIXED: Replaced a non-localizable string literal in the options page
• NEW: Event export
• NEW: Added link to the WordPress 2.7 admin favorites menu

1.0.8.2

• FIXED: Removed a 2.7-only function that caused PHP warnings on 2.6
• FIXED: Re-enabled media upload buttons since they now work right

1.0.8.1

• FIXED: Options page warning

1.0.8

• FIXED: Visual editor was broken (again)

1.0.7

• NEW: Option to use a different date format for the end date if the event starts and ends on the same day
• NEW: Option to display a message if there are no events to show
• NEW: Option to set rel=’nofollow’ on links in the event listing
• NEW: Option to display events in reverse order

1.0.6

• NEW: Link field on events
• FIXED: Description box now has the correct tab index on the new &amp; edit pages
• FIXED: Table view now uses properly cleaned fields
• FIXED: Past events option now defaults to “Only show current and future events” if it is not set
• FIXED: Deactivating the plugin no longer deletes all WPListCal settings and data
• FIXED: Write section tab now named Event instead of Add Event for consistency with WordPress

1.0.5

• FIXED: Return of the WPListCal options tab
• FIXED: the visual editor didn’t work
• FIXED: htmlspecialchars_decode function threw error
• FIXED: Plugin now works on servers with short_open_tag disabled

1.0.4

• FIXED: Edit & options links to work when wplistcal.php is in a subfolder
• FIXED: Removed options link from edit & new event pages if the user doesn’t have permissions to view it
• FIXED: Settings tab no longer appears to users who do not have permissions to it
• FIXED: Visual editor now works properly (also fixes switcheditors not defined error)

1.0.3

• FIXED: Options bug introduced by WordPress 2.5
• NEW: Restyled admin menus to look like WordPress 2.5
• FIXED: Localized a few hardcoded strings
• NEW: 24hr time support for the admin area
• NEW: Advanced notice limit option
• NEW: Every other event in both the list and table view has the css class wplc_alt applied to it to allow alternating row formatting
• FIXED: Maximum events setting on wplc_show_events was broken
• FIXED: Event titles containing single quotes printed wrong

1.0.2

• FIXED: Maximum Events option always defaulted to show all events

1.0.1

• FIXED: Added definition for str_ireplace() for servers not running PHP5

1.0

• Initial Release