Theater for WordPress Code Reference
  • Package
  • Class

Packages

  • Theater
    • Abstracts
    • Events

Classes

  • Theater_Event
  • Theater_Event_Date
  • Theater_Event_Date_Link
  • Theater_Event_Date_List
  • Theater_Event_Field
  • Theater_Event_List

Class Theater_Event_Date_List

Handles event dates lists.

Use this class to retrieve a list of event dates or a fully formatted HTML list of event dates.

Basic usage

// Retrieve a list of all dates.
$dates = new Theater_Dates;
foreach ( $dates() as $date ) {
    // $date is a Theater_Date object.
    echo $date->title();
}
// Output a formatted list of all dates.
$dates = new Theater_Dates;
echo $dates;

Filtered lists

You can pass extra filter arguments to customize the events that are in the list:

// Retrieve a list of upcoming dates.
$dates = new Theater_Dates( array( 'start' => 'now' ) );
// Retrieve a list of dates for a single event.
$dates = new Theater_Dates( array( 'event' => 123 ) );
// Retrieve a list of upcoming dates for a single event.
$dates = new Theater_Dates( array( 'event' => 123, 'start' => 'now' ) );

See Theater_Dates::get() for a full list of accepted arguments.

Customized output

You can also formatting arguments to customize the HTML output of the list:

// Retrieve a list of upcoming dates.
$dates = new Theater_Dates( array( 'start' => 'now' ) );

See Theater_Dates::get_html() for a full list of accepted arguments.

Theater_List
Extended by Theater_Event_Date_List
Package: Theater\Events
Since: 0.5
Since: 0.10 Complete rewrite, while maintaining backwards compatibility.
Since: 0.16 Another rewrite.
Located at functions/event/class-theater-event-date-list.php

Methods summary

public Theater_Date[]
# get( array[string] $filters = array() )

Gets a list of event dates.

Gets a list of event dates.

Usage

// Retrieve a list of all dates.
Theater_Dates::get();
// Retrieve a list of upcoming dates for a single event.
Theater_Dates::get( array( 'event' => 123, 'start' => 'now' ) );

Shorthand

This method is also used if you call the Theater_Dates class as a function:

// Retrieve a list of all dates.
$dates = new Theater_Dates;
foreach ( $dates() as $date ) {
    // $date is a Theater_Date object.
    echo $date->title();
}

Parameters

$filters

An array of filter arguments. Optional.

Possible argument values:

argument type description
cat int|string Category ID or comma-separated list of IDs.
category_name string Category slug.
category__and string An array of category IDs (AND in).
category__in int[] An array of category IDs (OR in, no children).
category__not_in int[] An array of category IDs (NOT in).
tag string Tag slug. Comma-separated (either), Plus-separated (all).
end string A date/time string. Only show event dates that start before this date.
Valid formats are explained in
Date and Time Formats.
event int|array Event ID of an array of event IDs. Only show dates of one or more events.
limit int Number of dates to return. Use -1 to show all event dates.
order string The order in which to return the event dates. Either ASC or DESC.
post__in int[] Array of event date IDs.
post__not_in int[] Array of event date IDs.
season int Season ID. Only show event dates for this season
s string Search keyword(s). Prepending a term with a hyphen will
exclude events matching that term. Eg, 'pillow -sofa' will
return events containing 'pillow' but not 'sofa'.
start string A date/time string. Only show event dates that start after this date.
Valid formats are explained in
Date and Time Formats.
status array Array of post statusses. Only show event dates of events with these
statuses.

Returns

Theater_Date[]
An array of events.

Since

0.5

0.10 Renamed method from load() to get(). Added 'order' to $args.


0.10.14 Preload events with their productions. This dramatically decreases the number of queries needed to show a listing of events.


0.10.15 'Start' and 'end' $args now account for timezones. Fixes #117.


0.11.8 Support for 'post__in' and 'post__not_in'. Fixes #128.


0.13 Added support for multiple productions.

0.13.1 'Start' and 'end' filter explicitly set to 'NUMERIC'. Fixes #168.


0.15 Added support for 's' (keyword search).
0.16 Replaced the production filter with the event filter.

Uses

Theater_Dates::$default_args
WPT_Order::meta_key to get the key to filter when the 'start' or 'end' filter is used.
Theater_Date::post_type_name to get the event date post type.

WPT_Production::post_type_name to get the events post type if the 'event' or 's' (keyword search) filter is used.


WPT_Season::post_type_name to get the seasons post type if the 'season' filter is used.
WPT_Productions::get() to find productions if the 's' (keyword search) filter is used.
Theater_Date to create a new event date object for each event in the list.

Used by

Theater_Event::get_event_dates()
to get the event dates of an event.

Overrides

Theater_List::get
public array[string]string
# get_categories( array $filters = array() )

Gets an array of all categories for an event dates list.

Gets an array of all categories for an event dates list.

Parameters

$filters
See Theater_Dates::get() for possible values.

Returns

array[string]string
An array of category slug => name pairs.

Since

0.5
0.10 Renamed method from categories() to get_categories().
0.10.2 Now returns the slug instead of the term_id as the array keys.
0.10.14 Significally decreased the number of queries used.

Uses

Theater_Dates::get() to get a list of all event dates for a list.
protected array
# get_classes_for_html( array $args = array() )

Gets the CSS classes for an event dates list.

Gets the CSS classes for an event dates list.

Parameters

$args
See Theater_Dates::get_html() for possible values. Default: array().

Returns

array
The CSS classes.

Since

0.10
0.14.7 Added $args to parent::get_classes_for_html().

Uses

Theater_Lists::get_classes_for_html() to retrieve the default classes for a list.

Overrides

Theater_List::get_classes_for_html
public array
# get_days( array $filters = array() )

Gets an array of all days with event dates.

Gets an array of all days with event dates.

Parameters

$filters
See Theater_Dates::get() for possible values.

Returns

array
Days.

Since

0.8

0.10 No longer limits the output to days with upcoming events. See: https://github.com/slimndap/wp-theatre/issues/75 Renamed method from days() to get_days().


0.10.1 Removed custom sorting. Rely on the sorting order of the events instead.

0.10.6 Added custom sorting again. Can't rely on sorting order of events, because historic events have no _wpt_order set.


Uses

Theater_Dates::get() to get a list of all event dates for a list.
public string
# get_html( array[string] $args = array() )

Gets a fully formatted list of event dates in HTML.

Gets a fully formatted list of event dates in HTML.

The list of dates is compiled using filter arguments that are part of $args.

Basic usage

// Output an HTML list with all dates.
echo Theater_Dates::get_html();
// Output an HTML list with upcoming dates.
echo Theater_Dates::get_html( array( 'start' => 'now' ) );

See Theater_Dates::get() for possible values for $args.

Customized output

Additionally, it is possible to customize the output using formatting argument:

// Output an HTML list with a 'category' filter at the top.
echo Theater_Dates::get_html( array( 'paginateby' => 'category' ) );
// Output an HTML list with upcoming dates.
echo Theater_Dates::get_html( array( 'start' => 'now' ) );

The event dates can be shown on a single page or be cut up into multiple pages by setting $paginateby. If $paginateby is set then a page navigation is added to the top of the listing.

The dates can be grouped inside the pages by setting $groupby.

Parameters

$args

An array of arguments. Optional.

The possible argument are identical to Theater_Dates::get(), plus the following formatting arguments:

Possible argument values:

argument type description
paginateby string[] Array of field names to paginate the list by.
Possible values: day, month, year and category.
groupby string Field name to group the list by.
Possible values: day, month, year and category.
template string Template to use for the individual event dates.

Returns

string
A fully formatted list of event dates in HTML.

Since

0.5

0.10 Moved parts of this method to seperate reusable methods. Renamed method from html() to get_html(). Rewrote documentation.


Uses

Theater_List::get_html()
to generate the HTML for an event dates list.

Overrides

Theater_List::get_html
protected string
# get_html_for_category( string $category_slug, array $args = array() )

Gets a list of event dates in HTML for a single category.

Gets a list of event dates in HTML for a single category.

Parameters

$category_slug
Slug of the category.
$args
See Theater_Dates::get_html() for possible values.

Returns

string
The HTML.

Since

0.10
0.10.2 Category now uses slug instead of term_id.

Uses

Theater_Dates::get_html_grouped();
protected string
# get_html_for_day( string $day, array $args = array() )

Gets a list of event dates in HTML for a single day.

Gets a list of event dates in HTML for a single day.

Parameters

$day
The day in YYYY-MM-DD format.
$args
See Theater_Dates::get_html() for possible values.

Returns

string
The HTML.

Since

0.10

Uses

Theater_Dates::get_html_grouped();
protected string
# get_html_for_month( string $month, array $args = array() )

Gets a list of event dates in HTML for a single month.

Gets a list of event dates in HTML for a single month.

Parameters

$month
$day The month in YYYY-MM format.
$args
See Theater_Dates::get_html() for possible values.

Returns

string
The HTML.

Since

0.10

Uses

Theater_Dates::get_html_grouped();
protected string
# get_html_for_year( string $year, array $args = array() )

Gets a list of event dates in HTML for a single year.

Gets a list of event dates in HTML for a single year.

Parameters

$year
$day The year in YYYY format.
$args
See Theater_Dates::get_html() for possible values.

Returns

string
The HTML.

Since

0.10

Uses

Theater_Dates::get_html_grouped();
protected string
# get_html_for_page( array $args = array() )

Gets a list of event dates in HTML for a page.

Gets a list of event dates in HTML for a page.

Parameters

$args
See Theater_Dates::get_html() for possible values.

Returns

string
The HTML.

Since

0.10

Uses

Theater_Dates::get_html_grouped()
Theater_Dates::get_html_for_year()
Theater_Dates::get_html_for_month()
Theater_Dates::get_html_for_day()
Theater_Dates::get_html_for_category()

Overrides

Theater_List::get_html_for_page
protected string
# get_html_grouped( array $args = array() )

Gets a grouped list of event dates in HTML.

Gets a grouped list of event dates in HTML.

The event dates can be grouped inside a page by setting $groupby. If $groupby is not set then all events are show in a single, ungrouped list.

Parameters

$args
See Theater_Dates::get_html() for possible values.

Returns

string
The HTML.

Since

0.10
0.14.7 Added $args to $event->html().

Uses

Theater_Dates::$default_args_for_html
Theater_Dates::html()
Theater_Dates::get_html_for_month()
Theater_Dates::get_html_for_day()
Theater_Dates::get_html_for_category()
Theater_Dates::get()
Theater_Dates::preload_dates_with_events()
Theater_Date::get_html() to get the HTML output of an event date.
protected string
# get_html_page_navigation( array $args = array() )

Gets the page navigation for an event dates list in HTML.

Gets the page navigation for an event dates list in HTML.

Parameters

$args

The arguments being used for the event listing. See Theater_Dates::get_html() for possible values.

Returns

string
The HTML for the page navigation.

Since

0.10

0.13.4 Show the pagination filters in the same order as the the 'paginateby' argument.


Uses

Theater_Dates::get_pagination_filters()
Theater_List::filter_pagination()

Overrides

Theater_List::get_html_page_navigation
public array
# get_months( array $filters = array() )

Gets all months that have events.

Gets all months that have events.

Parameters

$filters
See Theater_Dates::get() for possible values.

Returns

array
Months.

Since

0.5

0.10 No longer limits the output to months with upcoming events. See: https://github.com/slimndap/wp-theatre/issues/75 Renamed method from months() to get_months().


0.10.1 Removed custom sorting. Rely on the sorting order of the events instead.

0.10.6 Added custom sorting again. Can't rely on sorting order of events, because historic events have no _wpt_order set.


Uses

Theater_Dates::get() to get a list of all event dates for a list.
Theater_Date::datetime()
protected array
# get_pagination_filters( )

Gets the pagination filters for an event listing.

Gets the pagination filters for an event listing.

Returns

array
The pagination filters for an event listing.

Since

0.13.4

Uses

Theater_Dates::get_pagination_filters()

Overrides

Theater_List::get_pagination_filters
public array
# get_years( array $filters = array() )

Gets all distincs years for an event dates list.

Gets all distincs years for an event dates list.

Parameters

$filters
See Theater_Dates::get() for possible values.

Returns

array
Years.

Since

0.10
0.10.1 Removed custom sorting. Rely on the sorting order of the events instead.

0.10.6 Added custom sorting again. Can't rely on sorting order of events, because historic events have no _wpt_order set.


Uses

Theater_Dates::get() to get a list of all event dates for a list.
Theater_Date::datetime()
protected Theater_Date[]
# preload_dates_with_events( Theater_Date[] $dates )

Preloads dates with their events.

Preloads dates with their events.

Sets the event of a each date in a list of event dates with a single query. This dramatically decreases the number of queries needed to show a list of event dates.

Parameters

$dates
$events An array of Theater_Date objects.

Returns

Theater_Date[]
An array of Theater_Date objects, with the event preloaded.

Since

0.10.14

Uses

WPT_Production::post_type_name
Theater_Date::$ID
Theater_Date::$production
WPT_Production
public
# categories( $filters = array() )

Deprecated

0.10

See

Theater_Dates::get_categories()
public
# days( $filters = array() )

Deprecated

0.10

See

Theater_Dates::get_days()
public Theater_Date|boolean
# last( )

Gets the last event date.

Gets the last event date.

Deprecated

0.16

Returns

Theater_Date|boolean
The last event date or if no event date is found.

Since

0.8
public
# months( $filters = array() )

Deprecated

0.10

See

Theater_Dates::get_months()

Methods inherited from Theater_List

__construct(), __invoke(), __toString(), add_query_vars(), filter_pagination()

Properties summary

protected array[string] $default_args

The default filter arguments for event dates lists.

The default filter arguments for event dates lists.
# array( 'cat' => false, 'category_name' => false, 'category__and' => false, 'category__in' => false, 'category__not_in' => false, 'tag' => false, 'end' => false, 'event' => false, 'limit' => false, 'order' => 'asc', 'past' => false, 'post__in' => false, 'post__not_in' => false, 'production' => false, 'season' => false, 's' => false, 'start' => false, 'status' => array( 'publish' ), 'template' => '', 'upcoming' => false, )

Properties inherited from Theater_List

$default_args_for_html

Theater for WordPress Code Reference API documentation generated by ApiGen