1 <?php
2
3 /**
4 * Abstract Theater Lists class.
5 *
6 * @abstract
7 * @package Theater/Abstracts
8 */
9 abstract class Theater_List {
10
11 protected $default_args = array();
12
13 /**
14 * Default arguments for all HTML methods.
15 *
16 * @since 0.10
17 *
18 * @var array
19 * @access protected
20 */
21 protected $default_args_for_html = array(
22 'groupby' => false,
23 'paginateby' => array(),
24 'template' => null,
25 );
26
27 /**
28 * Sets the default filter arguments for a list.
29 *
30 * @since 0.16
31 * @param array[string] $default_args Optional. Custom default filter arguments for this list.
32 * @return void
33 * @uses Theater_Dates::$default_args to merge the built-in filter argument defaults with custom filter argument defaults.
34 */
35 function __construct ( $default_args = array() ) {
36 if (!empty( $default_args )) {
37 $this->default_args = wp_parse_args($default_args, $this->default_args);
38 }
39
40 }
41
42 /**
43 * Retrieves a list of items if the class is called as a function.
44 *
45 * @uses Theater_Lists::get() to return an array of event dates.
46 *
47 * @since 0.16
48 * @return Theater_Item[] An array of items.
49 */
50 function __invoke() {
51 return (array) $this->get();
52 }
53
54 /**
55 * Gets a fully formatted list of items in HTML if this class is treated like a string.
56 *
57 * @uses Theater_Lists::get_html() to return a formatted HTML list of items.
58 *
59 * @since 0.16
60 * @return string Formatted HTML list of items.
61 */
62 function __toString() {
63 return $this->get_html();
64 }
65
66 /**
67 * Adds the page selectors to the public query vars.
68 *
69 * This is needed to make `$wp_query->query_vars['wpt_category']` work.
70 * Override this method to add your own page selectors.
71 *
72 * @since 0.10
73 *
74 * @param array $vars The current public query vars.
75 * @return array The new public query vars.
76 */
77 static function add_query_vars( $vars ) {
78 return $vars;
79 }
80
81 /*
82 * Generate navigation for a listing filter.
83 *
84 * @see WPT_Productions::get_html()
85 * @see WPT_Events::get_html()
86 *
87 * @since 0.8
88 * @since 0.10.4 Added an extra class to the filter tabs.
89 * The class is based on $field and the tab.
90 * Useful for styling and automated tests.
91 * @since 0.10.10 XSS Vulnerability fix. See:
92 * https://make.wordpress.org/plugins/2015/04/20/fixing-add_query_arg-and-remove_query_arg-usage/
93 *
94 * @access protected
95 */
96
97 protected function filter_pagination( $field, $options, $args = array() ) {
98 global $wp_query;
99
100 $args = wp_parse_args( $args, $this->default_args_for_html );
101
102 $html = '';
103
104 $query_var = 'wpt_'.$field;
105 $paginate = in_array( $field,$args['paginateby'] );
106
107 /**
108 * Bail if:
109 * - pagination is not active for this $field and
110 * - no query_var is set for this $field.
111 */
112
113 if (
114 ! $paginate &&
115 empty( $wp_query->query_vars[ $query_var ] )
116 ) {
117 return $html;
118 };
119
120 /*
121 * Build the base url for all filters
122 */
123 $current_url = $_SERVER['REQUEST_URI'];
124
125 if ( ! empty( $args[ $field ] ) ) {
126 $current_url = add_query_arg( $query_var,$args[ $field ],$current_url );
127 }
128
129 foreach ( $options as $slug => $name ) {
130
131 $url = remove_query_arg( $query_var, $current_url );
132 $classes = array(
133 'wpt_listing_filter',
134 $field.'-'.$slug,
135 );
136
137 /**
138 * Check if $option is the current tab.
139 */
140
141 $is_current_page = false;
142 if (
143 isset( $wp_query->query_vars[ $query_var ] ) &&
144 $slug == $wp_query->query_vars[ $query_var ]
145 ) {
146 $is_current_page = true;
147 }
148
149 if ( $is_current_page ) {
150 $classes[] = 'wpt_listing_filter_active';
151 } else {
152 if ( ! $paginate ) {
153 continue;
154 }
155 $url = add_query_arg( $query_var, $slug , $url );
156 }
157
158 /**
159 * Filter the name of an option in the navigation for a listing filter.
160 *
161 * @since 0.10.10
162 *
163 * @param string $name The name of the option.
164 * @param string $field The field being filtered.
165 * Eg. 'month' or 'category'.
166 * @param string $slug The slug op the option.
167 */
168 $name = apply_filters( 'wpt_listing_filter_pagination_option_name', $name, $field, $slug );
169 $name = apply_filters( 'wpt_listing_filter_pagination_'.$field.'_option_name', $name, $slug );
170
171 /**
172 * Filter the url of an option in the navigation for a listing filter.
173 *
174 * @since 0.10.10
175 *
176 * @param string $url The url of the option.
177 * @param string $field The field being filtered.
178 * Eg. 'month' or 'category'.
179 * @param string $name The name of the option.
180 * @param string $slug The slug op the option.
181 */
182 $url = apply_filters( 'wpt_listing_filter_pagination_option_url', $url, $field, $name, $slug );
183 $url = apply_filters( 'wpt_listing_filter_pagination_'.$field.'_option_url', $url, $name, $slug );
184
185 /**
186 * @deprecated 0.10.10
187 * Use 'wpt_listing_filter_pagination_option_url'.
188 */
189 $url = apply_filters( 'wpt_listing_filter_pagination_url', $url );
190
191 $option_html = '<span class="'.implode( ' ',$classes ).'"><a href="'.htmlentities( $url ).'">'.$name.'</a></span> ';
192
193 /**
194 * Filter the html of an option in the navigation for a listing filter.
195 *
196 * @since 0.10.10
197 *
198 * @param string $html The html of the option.
199 * @param string $field The field being filtered.
200 * Eg. 'month' or 'category'.
201 * @param string $name The name of the option.
202 * @param string $slug The slug op the option.
203 */
204 $option_html = apply_filters( 'wpt_listing_filter_pagination_option_html', $option_html, $field, $name, $slug );
205 $option_html = apply_filters( 'wpt_listing_filter_pagination_'.$field.'_option_html', $option_html, $name, $slug );
206
207 $html .= $option_html;
208
209 }
210
211 /**
212 * Filter the HTML of the navigation for a listing filter.
213 *
214 * @since 0.13.3
215 * @since 0.13.4 Added the listing object to the filter variables.
216 * @since 0.16 Removed listing object from the filter params.
217 *
218 * @param string $html The HTML of the navigation for a listing filter.
219 * @param string $field The field being filtered.
220 * Eg. 'month' or 'category'.
221 * @param array $options The possible values for the filter.
222 * @param array $args The arguments used for the listing.
223 */
224 $html = apply_filters( 'wpt/listing/pagination/filter/html',$html, $field, $options, $args );
225 $html = apply_filters( 'wpt/listing/pagination/filter/html/field='.$field, $html, $options, $args );
226
227 return '<div class="wpt_listing_filter_pagination '.$field.'">'.$html.'</div>';
228
229 }
230
231 /**
232 * Gets the classes of a listing.
233 *
234 * @since 0.?
235 * @since 0.14.7 Added a new 'wpt/listing/classes' filter.
236 * Deprecated the 'wpt_listing_classes' filter.
237 * @param array $args The listing args.
238 * @return array The classes of a listing.
239 */
240 protected function get_classes_for_html( $args = array() ) {
241
242 $classes = array( 'wpt_listing' );
243
244 /**
245 * Filters the classes of a listing
246 *
247 * @since 0.14.7
248 * @param array $classes The classes of a listing.
249 * @param array $args The listing args.
250 */
251 $classes = apply_filters( 'wpt/listing/classes',$classes, $args );
252
253 /**
254 * @deprecated 0.14.7
255 */
256 $classes = apply_filters( 'wpt_listing_classes',$classes );
257
258 return $classes;
259 }
260
261 /**
262 * Gets a list in HTML.
263 *
264 * @since 0.10
265 * @since 0.15.2 Added actions directly before and after the HTML is generated.
266 * Used by WPT_Context() to give set the context for a listing.
267 *
268 * @see WPT_Listing::get_html_pagination()
269 * @see WPT_Listing::get_html_for_page()
270 *
271 * @access protected
272 * @param array $args {
273 * An array of arguments. Optional.
274 *
275 * These can be any of the arguments used in the $filters of WPT_Listing::load(), plus:
276 *
277 * @type string $groupby Field to group the listing by.
278 * @see WPT_Listing::get_html_grouped() for possible values.
279 * Default <false>.
280 * @type array $paginateby Fields to paginate the listing by.
281 * @see WPT_Listing::get_html_pagination() for possible values.
282 * Default <[]>.
283 * @type string $template Template to use for the individual list items.
284 * Default <NULL>.
285 * }
286 * @return string HTML.
287 */
288 protected function get_html( $args = array() ) {
289
290 ob_start();
291
292 /*
293 * Runs before the listing HTML is generated.
294 *
295 * @since 0.15.2
296 * @param array $args The listing arguments.
297 */
298 do_action('wpt/listing/html/before', $args);
299
300 $html_page_navigation = $this->get_html_page_navigation( $args );
301 $html_for_page = $this->get_html_for_page( $args );
302
303 if ( ! empty( $html_page_navigation ) || ! empty( $html_for_page ) ) {
304 ?><div class="<?php echo implode( ' ',$this->get_classes_for_html( $args ) ); ?>"><?php
305 echo $html_page_navigation.$html_for_page;
306 ?></div><?php
307 }
308
309 /*
310 * Runs after the listing HTML is generated.
311 *
312 * @since 0.15.2
313 * @param array $args The listing arguments.
314 */
315 do_action('wpt/listing/html/after', $args);
316
317 $html = ob_get_clean();
318 $html = apply_filters( 'wpt_listing_html', $html, $args );
319
320 return $html;
321 }
322
323 /**
324 * Gets the pagination filters for a listing.
325 *
326 * @since 0.13.4
327 * @return array The pagination filters for a listing.
328 */
329 protected function get_pagination_filters() {
330
331 /**
332 * Filter the pagination filters for a listing.
333 *
334 * @since 0.13.4
335 * @param array The current pagination filters for a listing.
336 */
337 $filters = apply_filters( 'wpt/listing/pagination/filters', array() );
338
339 return $filters;
340 }
341
342 /**
343 * Gets the page navigation for a listing in HTML.
344 *
345 * Override this method to create your own page navigation
346 * using WPT_Listing::filter_pagination() helper method.
347 *
348 * @see WPT_Listing::filter_pagination()
349 *
350 * @since 0.10
351 *
352 * @access protected
353 * @param array $args The arguments being used for the event listing.
354 * See WPT_Listing::get_html() for possible values.
355 * @return string The HTML for the page navigation.
356 */
357 protected function get_html_page_navigation( $args = array() ) {
358
359 }
360
361 /**
362 * Gets a list of events in HTML for a page.
363 *
364 * Override this method to assemble your own page content.
365 *
366 * @since 0.10
367 *
368 * @access protected
369 * @param array $args See WPT_Listing::get_html() for possible values.
370 * @return string The HTML.
371 */
372 protected function get_html_for_page( $args = array() ) {
373
374 }
375
376 /**
377 * Gets a list of events.
378 *
379 * @since 0.8
380 *
381 * @return array An array of WPT_Event objects.
382 */
383 function get($filters = array()) {
384
385 }
386 }