Widget_Abstract.php
875 lines
| 1 | <?php |
| 2 | |
| 3 | namespace Tribe\Widget; |
| 4 | |
| 5 | use Tribe__Utils__Array as Arr; |
| 6 | use Tribe__Template; |
| 7 | |
| 8 | /** |
| 9 | * The abstract base without Views that all widgets should implement. |
| 10 | * |
| 11 | * @since 4.12.12 |
| 12 | * |
| 13 | * @package Tribe\Widget |
| 14 | */ |
| 15 | abstract class Widget_Abstract extends \WP_Widget implements Widget_Interface { |
| 16 | /** |
| 17 | * Prefix for WordPress registration of the widget. |
| 18 | * |
| 19 | * @since 4.13.0 |
| 20 | * |
| 21 | * @var string |
| 22 | */ |
| 23 | const PREFIX = 'tribe-widget-'; |
| 24 | |
| 25 | /** |
| 26 | * Slug of the current widget. |
| 27 | * |
| 28 | * @since 4.13.0 |
| 29 | * |
| 30 | * @var string |
| 31 | */ |
| 32 | protected static $widget_slug; |
| 33 | |
| 34 | /** |
| 35 | * If this Widget was rendered on the screen, often useful for Assets. |
| 36 | * |
| 37 | * Every widget needs this to be defined internally otherwise it wont work. |
| 38 | * |
| 39 | * @since 4.13.0 |
| 40 | * |
| 41 | * @var boolean |
| 42 | */ |
| 43 | protected static $widget_in_use; |
| 44 | |
| 45 | /** |
| 46 | * An instance of template. |
| 47 | * |
| 48 | * @since 4.12.14 |
| 49 | * |
| 50 | * @var Tribe__Template |
| 51 | */ |
| 52 | protected $admin_template; |
| 53 | |
| 54 | /** |
| 55 | * Default arguments to be merged into final arguments of the widget. |
| 56 | * |
| 57 | * @since 4.12.12 |
| 58 | * |
| 59 | * @var array<string,mixed> |
| 60 | */ |
| 61 | protected $default_arguments = []; |
| 62 | |
| 63 | /** |
| 64 | * Sidebar arguments passed to the widget. |
| 65 | * |
| 66 | * @since 4.13.0 |
| 67 | * |
| 68 | * @var array<string,mixed> |
| 69 | */ |
| 70 | protected $sidebar_arguments = []; |
| 71 | |
| 72 | /** |
| 73 | * Array map allowing aliased widget arguments. |
| 74 | * |
| 75 | * The array keys are aliases of the array values (i.e. the "real" widget attributes to parse). |
| 76 | * Example array: [ 'alias' => 'canonical', 'from' => 'to', 'that' => 'becomes_this' ] |
| 77 | * Example widget usage: [some_tag alias=17 to='Fred'] will be parsed as [some_tag canonical=17 to='Fred'] |
| 78 | * |
| 79 | * @since 4.12.12 |
| 80 | * |
| 81 | * @var array<string,string> |
| 82 | */ |
| 83 | protected $aliased_arguments = []; |
| 84 | |
| 85 | /** |
| 86 | * Array of callbacks for validation of arguments. |
| 87 | * |
| 88 | * @since 4.12.12 |
| 89 | * |
| 90 | * @var array<string,callable> |
| 91 | */ |
| 92 | protected $validate_arguments_map = []; |
| 93 | |
| 94 | /** |
| 95 | * Arguments of the current widget. |
| 96 | * |
| 97 | * @since 4.12.12 |
| 98 | * |
| 99 | * @var array<string,mixed> |
| 100 | */ |
| 101 | protected $arguments = []; |
| 102 | |
| 103 | /** |
| 104 | * Current set of Admin Fields used on the admin form. |
| 105 | * |
| 106 | * @since 4.13.0 |
| 107 | * |
| 108 | * @var array<string,mixed> |
| 109 | */ |
| 110 | protected $admin_fields = []; |
| 111 | |
| 112 | /** |
| 113 | * HTML content of the current widget. |
| 114 | * |
| 115 | * @since 4.12.12 |
| 116 | * |
| 117 | * @var string |
| 118 | */ |
| 119 | protected $content; |
| 120 | |
| 121 | /** |
| 122 | * {@inheritDoc} |
| 123 | */ |
| 124 | public function __construct( $id_base = '', $name = '', $widget_options = [], $control_options = [] ) { |
| 125 | /** |
| 126 | * For backwards compatibility purposes alone. |
| 127 | * @todo remove after 2021-08-01 |
| 128 | */ |
| 129 | $this->slug = static::get_widget_slug(); |
| 130 | |
| 131 | parent::__construct( |
| 132 | $this->parse_id_base( $id_base ), |
| 133 | $this->parse_name( $name ), |
| 134 | $this->parse_widget_options( $widget_options ), |
| 135 | $this->parse_control_options( $control_options ) |
| 136 | ); |
| 137 | } |
| 138 | |
| 139 | /** |
| 140 | * Parse the ID base sent to the __construct method. |
| 141 | * |
| 142 | * @since 4.13.0 |
| 143 | * |
| 144 | * @param string $id_base The ID base that we will use for this Widget instance. |
| 145 | * |
| 146 | * @return string|null Parsed value given by the __construct. |
| 147 | */ |
| 148 | protected function parse_id_base( $id_base = null ) { |
| 149 | // When empty use the one default to the widget. |
| 150 | if ( empty( $id_base ) ) { |
| 151 | $id_base = static::PREFIX . static::get_widget_slug(); |
| 152 | } |
| 153 | |
| 154 | return $id_base; |
| 155 | } |
| 156 | |
| 157 | /** |
| 158 | * Parse the ID base sent to the __construct method. |
| 159 | * |
| 160 | * @since 4.13.0 |
| 161 | * |
| 162 | * @param string $name The ID base that we will use for this Widget instance. |
| 163 | * |
| 164 | * @return string Parsed value given by the __construct. |
| 165 | */ |
| 166 | protected function parse_name( $name = null ) { |
| 167 | // When empty use the one default to the widget. |
| 168 | if ( empty( $name ) ) { |
| 169 | $name = static::get_default_widget_name(); |
| 170 | } |
| 171 | |
| 172 | return $name; |
| 173 | } |
| 174 | |
| 175 | /** |
| 176 | * Sets up the Widget name, |
| 177 | * |
| 178 | * @since 4.13.0 |
| 179 | * |
| 180 | * @return string Returns the default widget name. |
| 181 | */ |
| 182 | public static function get_default_widget_name() { |
| 183 | return __( 'Widget', 'tribe-common' ); |
| 184 | } |
| 185 | |
| 186 | /** |
| 187 | * Parse the widget options base sent to the __construct method. |
| 188 | * |
| 189 | * @since 4.13.0 |
| 190 | * |
| 191 | * @param array $widget_options The widget options base that we will use for this Widget instance. |
| 192 | * |
| 193 | * @return array Widget options that will be passed to the __construct. |
| 194 | */ |
| 195 | protected function parse_widget_options( $widget_options = [] ) { |
| 196 | // When empty use the one default to the widget. |
| 197 | if ( empty( $widget_options ) ) { |
| 198 | $widget_options = static::get_default_widget_options(); |
| 199 | } |
| 200 | |
| 201 | return $widget_options; |
| 202 | } |
| 203 | |
| 204 | /** |
| 205 | * Gets the default widget options. |
| 206 | * |
| 207 | * @since 4.13.0 |
| 208 | * |
| 209 | * @return array Default widget options. |
| 210 | */ |
| 211 | public static function get_default_widget_options() { |
| 212 | return []; |
| 213 | } |
| 214 | |
| 215 | /** |
| 216 | * Parse the control options base sent to the __construct method. |
| 217 | * |
| 218 | * @since 4.13.0 |
| 219 | * |
| 220 | * @param array $control_options The base control options passed to the construct method. |
| 221 | * |
| 222 | * @return array Parsed value given by the __construct. |
| 223 | */ |
| 224 | protected function parse_control_options( $control_options = [] ) { |
| 225 | // When empty use the one default to the widget. |
| 226 | if ( empty( $control_options ) ) { |
| 227 | $control_options = static::get_default_control_options(); |
| 228 | } |
| 229 | |
| 230 | return $control_options; |
| 231 | } |
| 232 | |
| 233 | /** |
| 234 | * Gets the default control options. |
| 235 | * |
| 236 | * @since 4.13.0 |
| 237 | * |
| 238 | * @return array Default control options. |
| 239 | */ |
| 240 | public static function get_default_control_options() { |
| 241 | return []; |
| 242 | } |
| 243 | |
| 244 | /** |
| 245 | * {@inheritDoc} |
| 246 | */ |
| 247 | public static function get_widget_slug() { |
| 248 | return static::$widget_slug; |
| 249 | } |
| 250 | |
| 251 | /** |
| 252 | * {@inheritDoc} |
| 253 | */ |
| 254 | public static function is_widget_in_use() { |
| 255 | return static::$widget_in_use; |
| 256 | } |
| 257 | |
| 258 | /** |
| 259 | * {@inheritDoc} |
| 260 | */ |
| 261 | public static function widget_in_use( $toggle = true ) { |
| 262 | static::$widget_in_use = tribe_is_truthy( $toggle ); |
| 263 | } |
| 264 | |
| 265 | /** |
| 266 | * Setup the widget. |
| 267 | * |
| 268 | * @since 5.2.1 |
| 269 | * @since 4.13.0 include $args and $instance params. |
| 270 | * |
| 271 | * @param array $args Display arguments including 'before_title', 'after_title', |
| 272 | * 'before_widget', and 'after_widget'. |
| 273 | * @param array $instance The settings for the particular instance of the widget. |
| 274 | * |
| 275 | * @return mixed |
| 276 | */ |
| 277 | abstract public function setup( $args = [], $instance = [] ); |
| 278 | |
| 279 | /** |
| 280 | * {@inheritDoc} |
| 281 | */ |
| 282 | public function form( $instance ) { |
| 283 | $this->setup( [], $instance ); |
| 284 | |
| 285 | // Specifically on the admin we force the admin fields into the arguments. |
| 286 | $this->arguments['admin_fields'] = $this->get_admin_fields(); |
| 287 | |
| 288 | $this->toggle_hooks( true ); |
| 289 | |
| 290 | $html = $this->get_admin_html( $this->get_arguments() ); |
| 291 | |
| 292 | $this->toggle_hooks( false ); |
| 293 | return $html; |
| 294 | } |
| 295 | |
| 296 | /** |
| 297 | * {@inheritDoc} |
| 298 | */ |
| 299 | public function widget( $args, $instance ) { |
| 300 | // Once the widget is rendered we trigger that it is in use. |
| 301 | static::widget_in_use( true ); |
| 302 | |
| 303 | $this->setup( $args, $instance ); |
| 304 | |
| 305 | $this->toggle_hooks( true ); |
| 306 | |
| 307 | $html = $this->get_html(); |
| 308 | |
| 309 | $this->toggle_hooks( false ); |
| 310 | |
| 311 | echo $html; |
| 312 | |
| 313 | return $html; |
| 314 | } |
| 315 | |
| 316 | /** |
| 317 | * Returns the rendered View HTML code. |
| 318 | * |
| 319 | * @since 4.12.12 |
| 320 | * |
| 321 | * @return string |
| 322 | */ |
| 323 | abstract public function get_html(); |
| 324 | |
| 325 | /** |
| 326 | * {@inheritDoc} |
| 327 | */ |
| 328 | public function set_aliased_arguments( array $alias_map ) { |
| 329 | $this->aliased_arguments = Arr::filter_to_flat_scalar_associative_array( (array) $alias_map ); |
| 330 | } |
| 331 | |
| 332 | /** |
| 333 | * {@inheritDoc} |
| 334 | */ |
| 335 | public function get_aliased_arguments() { |
| 336 | return $this->aliased_arguments; |
| 337 | } |
| 338 | |
| 339 | /** |
| 340 | * {@inheritDoc} |
| 341 | */ |
| 342 | public function parse_arguments( array $arguments ) { |
| 343 | $arguments = Arr::parse_associative_array_alias( (array) $arguments, (array) $this->get_aliased_arguments() ); |
| 344 | |
| 345 | return $this->validate_arguments( $arguments ); |
| 346 | } |
| 347 | |
| 348 | /** |
| 349 | * {@inheritDoc} |
| 350 | */ |
| 351 | public function validate_arguments( array $arguments ) { |
| 352 | $validate_arguments_map = $this->filter_validated_arguments_map( $this->get_validated_arguments_map() ); |
| 353 | |
| 354 | // Only overwrite methods that have a validation, the rest stay as-is. |
| 355 | foreach ( $validate_arguments_map as $key => $callback ) { |
| 356 | $arguments[ $key ] = $callback( Arr::get( $arguments, $key, null ) ); |
| 357 | } |
| 358 | |
| 359 | return $arguments; |
| 360 | } |
| 361 | |
| 362 | /** |
| 363 | * {@inheritDoc} |
| 364 | */ |
| 365 | public function get_validated_arguments_map() { |
| 366 | return $this->validate_arguments_map; |
| 367 | } |
| 368 | |
| 369 | /** |
| 370 | * {@inheritDoc} |
| 371 | */ |
| 372 | public function filter_validated_arguments_map( $validate_arguments_map = [] ) { |
| 373 | /** |
| 374 | * Applies a filter to the validation map for instance arguments. |
| 375 | * |
| 376 | * @since 4.12.12 |
| 377 | * |
| 378 | * @param array<string,callable> $validate_arguments_map Current set of callbacks for arguments. |
| 379 | * @param static $instance The widget instance we are dealing with. |
| 380 | */ |
| 381 | $validate_arguments_map = apply_filters( 'tribe_widget_validate_arguments_map', $validate_arguments_map, $this ); |
| 382 | |
| 383 | $widget_slug = static::get_widget_slug(); |
| 384 | |
| 385 | /** |
| 386 | * Applies a filter to the validation map for instance arguments for a specific widget. Based on the widget slug of the widget |
| 387 | * |
| 388 | * @since 4.12.12 |
| 389 | * |
| 390 | * @param array<string,callable> $validate_arguments_map Current set of callbacks for arguments. |
| 391 | * @param static $instance The widget instance we are dealing with. |
| 392 | */ |
| 393 | $validate_arguments_map = apply_filters( "tribe_widget_{$widget_slug}_validate_arguments_map", $validate_arguments_map, $this ); |
| 394 | |
| 395 | return $validate_arguments_map; |
| 396 | } |
| 397 | |
| 398 | /** |
| 399 | * Sets up the widgets default admin fields. |
| 400 | * |
| 401 | * @since 4.12.14 |
| 402 | * |
| 403 | * @return array<string,mixed> The array of widget admin fields. |
| 404 | */ |
| 405 | abstract protected function setup_admin_fields(); |
| 406 | |
| 407 | /** |
| 408 | * {@inheritDoc} |
| 409 | */ |
| 410 | public function get_admin_fields() { |
| 411 | $fields = $this->setup_admin_fields(); |
| 412 | $arguments = $this->get_arguments(); |
| 413 | $fields = $this->filter_admin_fields( $fields ); |
| 414 | |
| 415 | foreach ( $fields as $field_name => $field ) { |
| 416 | $fields[ $field_name ] = $this->get_admin_data( $arguments, $field_name, $field ); |
| 417 | } |
| 418 | |
| 419 | return $fields; |
| 420 | } |
| 421 | |
| 422 | /** |
| 423 | * {@inheritDoc} |
| 424 | */ |
| 425 | public function filter_admin_fields( $admin_fields ) { |
| 426 | /** |
| 427 | * Applies a filter to a widget's admin fields. |
| 428 | * |
| 429 | * @since 4.12.14 |
| 430 | * |
| 431 | * @param array<string,mixed> $admin_fields The array of widget admin fields. |
| 432 | * @param static $instance The widget instance we are dealing with. |
| 433 | */ |
| 434 | $admin_fields = apply_filters( 'tribe_widget_admin_fields', $admin_fields, $this ); |
| 435 | |
| 436 | $widget_slug = static::get_widget_slug(); |
| 437 | |
| 438 | /** |
| 439 | * Applies a filter to a widget's admin fields based on the widget slug of the widget. |
| 440 | * |
| 441 | * @since TBE |
| 442 | * |
| 443 | * @param array<string,mixed> $admin_fields The array of widget admin fields. |
| 444 | * @param static $instance The widget instance we are dealing with. |
| 445 | */ |
| 446 | $admin_fields = apply_filters( "tribe_widget_{$widget_slug}_admin_fields", $admin_fields, $this ); |
| 447 | |
| 448 | return $admin_fields; |
| 449 | } |
| 450 | |
| 451 | /** |
| 452 | * {@inheritDoc} |
| 453 | */ |
| 454 | public function filter_updated_instance( $updated_instance, $new_instance ) { |
| 455 | /** |
| 456 | * Applies a filter to updated instance of a widget. |
| 457 | * |
| 458 | * @since 4.12.14 |
| 459 | * |
| 460 | * @param array<string,mixed> $updated_instance The updated instance of the widget. |
| 461 | * @param array<string,mixed> $new_instance The new values for the widget instance. |
| 462 | * @param static $instance The widget instance we are dealing with. |
| 463 | */ |
| 464 | $updated_instance = apply_filters( 'tribe_widget_updated_instance', $updated_instance, $new_instance, $this ); |
| 465 | |
| 466 | $widget_slug = static::get_widget_slug(); |
| 467 | |
| 468 | /** |
| 469 | * Applies a filter to updated instance of a widget arguments based on the widget slug of the widget. |
| 470 | * |
| 471 | * @since 4.12.14 |
| 472 | * |
| 473 | * @param array<string,mixed> $updated_instance The updated instance of the widget. |
| 474 | * @param array<string,mixed> $new_instance The new values for the widget instance. |
| 475 | * @param static $instance The widget instance we are dealing with. |
| 476 | */ |
| 477 | $updated_instance = apply_filters( "tribe_widget_{$widget_slug}_updated_instance", $updated_instance, $new_instance, $this ); |
| 478 | |
| 479 | return $updated_instance; |
| 480 | } |
| 481 | |
| 482 | /** |
| 483 | * Sets up the widgets arguments, using saved values. |
| 484 | * |
| 485 | * @since 4.12.14 |
| 486 | * |
| 487 | * @param array<string,mixed> $instance Saved values for the widget instance. |
| 488 | * |
| 489 | * @return array<string,mixed> The widget arguments, as set by the user in the widget string. |
| 490 | */ |
| 491 | protected function setup_arguments( array $instance = [] ) { |
| 492 | // First Setup the Defaults to make sure dynamic values are present. |
| 493 | $this->setup_default_arguments(); |
| 494 | |
| 495 | // Now merge instance into the arguments then to the defaults. |
| 496 | $this->arguments = array_merge( |
| 497 | $this->get_default_arguments(), |
| 498 | $this->arguments, |
| 499 | $instance |
| 500 | ); |
| 501 | |
| 502 | // Parse these arguments to avoid problems. |
| 503 | $this->arguments = $this->parse_arguments( $this->arguments ); |
| 504 | |
| 505 | return $this->arguments; |
| 506 | } |
| 507 | |
| 508 | /** |
| 509 | * Handles gathering the data for admin fields. |
| 510 | * |
| 511 | * @since 5.3.0 |
| 512 | * @since 4.13.0 Move into common from Events Abstract |
| 513 | * |
| 514 | * @param array<string,mixed> $arguments Current set of arguments. |
| 515 | * @param int $field_name The ID of the field. |
| 516 | * @param array<string,mixed> $field The field info. |
| 517 | * |
| 518 | * @return array<string,mixed> $data The assembled field data. |
| 519 | */ |
| 520 | public function get_admin_data( $arguments, $field_name, $field ) { |
| 521 | $data = [ |
| 522 | 'classes' => Arr::get( $field, 'classes', '' ), |
| 523 | 'dependency' => $this->format_dependency( $field ), |
| 524 | 'id' => $this->get_field_id( $field_name ), |
| 525 | 'label' => Arr::get( $field, 'label', '' ), |
| 526 | 'name' => $this->get_field_name( $field_name ), |
| 527 | 'options' => Arr::get( $field, 'options', [] ), |
| 528 | 'placeholder' => Arr::get( $field, 'placeholder', '' ), |
| 529 | 'value' => Arr::get( $arguments, $field_name ), |
| 530 | ]; |
| 531 | |
| 532 | $children = Arr::get( $field, 'children', [] ); |
| 533 | |
| 534 | if ( ! empty( $children ) ) { |
| 535 | foreach ( $children as $child_name => $child ) { |
| 536 | $input_name = ( 'radio' === $child['type'] ) ? $field_name : $child_name; |
| 537 | |
| 538 | $child_data = $this->get_admin_data( |
| 539 | $arguments, |
| 540 | $input_name, |
| 541 | $child |
| 542 | ); |
| 543 | |
| 544 | $data['children'][ $child_name ] = $child_data; |
| 545 | } |
| 546 | } |
| 547 | |
| 548 | $data = array_merge( $field, $data ); |
| 549 | |
| 550 | // @todo properly filter this. |
| 551 | return apply_filters( 'tribe_widget_field_data', $data, $field_name, $this ); |
| 552 | } |
| 553 | |
| 554 | /** |
| 555 | * {@inheritDoc} |
| 556 | */ |
| 557 | public function get_arguments( array $_deprecated = [] ) { |
| 558 | return $this->filter_arguments( $this->arguments ); |
| 559 | } |
| 560 | |
| 561 | /** |
| 562 | * {@inheritDoc} |
| 563 | */ |
| 564 | public function filter_arguments( $arguments ) { |
| 565 | /** |
| 566 | * Applies a filter to instance arguments. |
| 567 | * |
| 568 | * @since 4.12.12 |
| 569 | * |
| 570 | * @param array<string,mixed> $arguments Current set of arguments. |
| 571 | * @param static $instance The widget instance we are dealing with. |
| 572 | */ |
| 573 | $arguments = apply_filters( 'tribe_widget_arguments', $arguments, $this ); |
| 574 | |
| 575 | $widget_slug = static::get_widget_slug(); |
| 576 | |
| 577 | /** |
| 578 | * Applies a filter to instance arguments based on the widget slug of the widget. |
| 579 | * |
| 580 | * @since 4.12.12 |
| 581 | * |
| 582 | * @param array<string,mixed> $arguments Current set of arguments. |
| 583 | * @param static $instance The widget instance we are dealing with. |
| 584 | */ |
| 585 | $arguments = apply_filters( "tribe_widget_{$widget_slug}_arguments", $arguments, $this ); |
| 586 | |
| 587 | return $arguments; |
| 588 | } |
| 589 | |
| 590 | /** |
| 591 | * {@inheritDoc} |
| 592 | */ |
| 593 | public function get_argument( $index, $default = null ) { |
| 594 | $argument = Arr::get( $this->get_arguments(), $index, $default ); |
| 595 | |
| 596 | return $this->filter_argument( $argument, $index, $default ); |
| 597 | } |
| 598 | |
| 599 | /** |
| 600 | * {@inheritDoc} |
| 601 | */ |
| 602 | public function filter_argument( $argument, $index, $default = null ) { |
| 603 | /** |
| 604 | * Applies a filter to a specific widget argument, catch all for all widgets. |
| 605 | * |
| 606 | * @since 4.12.12 |
| 607 | * |
| 608 | * @param mixed $argument The argument. |
| 609 | * @param string|int $index Which index we intend to fetch from the arguments. |
| 610 | * @param array<string,mixed> $default Default value if it doesn't exist. |
| 611 | * @param static $instance The widget instance we are dealing with. |
| 612 | */ |
| 613 | $argument = apply_filters( 'tribe_widget_argument', $argument, $index, $default, $this ); |
| 614 | |
| 615 | $widget_slug = static::get_widget_slug(); |
| 616 | |
| 617 | /** |
| 618 | * Applies a filter to a specific widget argument, to a particular widget slug. |
| 619 | * |
| 620 | * @since 4.12.12 |
| 621 | * |
| 622 | * @param mixed $argument The argument value. |
| 623 | * @param string|int $index Which index we intend to fetch from the arguments. |
| 624 | * @param mixed $default Default value if it doesn't exist. |
| 625 | * @param static $instance The widget instance we are dealing with. |
| 626 | */ |
| 627 | $argument = apply_filters( "tribe_widget_{$widget_slug}_argument", $argument, $index, $default, $this ); |
| 628 | |
| 629 | return $argument; |
| 630 | } |
| 631 | |
| 632 | /** |
| 633 | * {@inheritDoc} |
| 634 | */ |
| 635 | public function setup_sidebar_arguments( $arguments ) { |
| 636 | $this->sidebar_arguments = $arguments; |
| 637 | } |
| 638 | |
| 639 | /** |
| 640 | * {@inheritDoc} |
| 641 | */ |
| 642 | public function get_sidebar_arguments() { |
| 643 | return $this->filter_sidebar_arguments( $this->sidebar_arguments ); |
| 644 | } |
| 645 | |
| 646 | /** |
| 647 | * {@inheritDoc} |
| 648 | */ |
| 649 | public function filter_sidebar_arguments( $arguments ) { |
| 650 | /** |
| 651 | * Applies a filter to the widget sidebar arguments, catch all for all widgets. |
| 652 | * |
| 653 | * @since 4.13.0 |
| 654 | * |
| 655 | * @param mixed $arguments The argument. |
| 656 | * @param static $instance The widget instance we are dealing with. |
| 657 | */ |
| 658 | $arguments = apply_filters( 'tribe_widget_sidebar_arguments', $arguments, $this ); |
| 659 | |
| 660 | $widget_slug = static::get_widget_slug(); |
| 661 | |
| 662 | /** |
| 663 | * Applies a filter to the widget sidebar arguments, to a particular widget slug. |
| 664 | * |
| 665 | * @since 4.13.0 |
| 666 | * |
| 667 | * @param mixed $arguments The argument. |
| 668 | * @param static $instance The widget instance we are dealing with. |
| 669 | */ |
| 670 | $arguments = apply_filters( "tribe_widget_{$widget_slug}_sidebar_arguments", $arguments, $this ); |
| 671 | |
| 672 | return $arguments; |
| 673 | } |
| 674 | |
| 675 | /** |
| 676 | * Sets up the widgets default arguments. |
| 677 | * |
| 678 | * @since 4.12.14 |
| 679 | * |
| 680 | * @return array<string,mixed> The default widget arguments. |
| 681 | */ |
| 682 | protected function setup_default_arguments() { |
| 683 | // Setup admin fields. |
| 684 | $this->default_arguments['admin_fields'] = $this->get_admin_fields(); |
| 685 | |
| 686 | // Add the Widget to the arguments to pass to the admin template. |
| 687 | $this->default_arguments['widget_obj'] = $this; |
| 688 | |
| 689 | return $this->default_arguments; |
| 690 | } |
| 691 | |
| 692 | /** |
| 693 | * {@inheritDoc} |
| 694 | */ |
| 695 | public function get_default_arguments() { |
| 696 | return $this->filter_default_arguments( $this->default_arguments ); |
| 697 | } |
| 698 | |
| 699 | /** |
| 700 | * {@inheritDoc} |
| 701 | */ |
| 702 | public function filter_default_arguments( array $default_arguments = [] ) { |
| 703 | /** |
| 704 | * Applies a filter to default instance arguments. |
| 705 | * |
| 706 | * @since 4.12.12 |
| 707 | * |
| 708 | * @param array<string,mixed> $default_arguments Current set of default arguments. |
| 709 | * @param static $instance The widget instance we are dealing with. |
| 710 | */ |
| 711 | $default_arguments = apply_filters( 'tribe_widget_default_arguments', $default_arguments, $this ); |
| 712 | |
| 713 | $widget_slug = static::get_widget_slug(); |
| 714 | |
| 715 | /** |
| 716 | * Applies a filter to default instance arguments based on the widget slug of the widget. |
| 717 | * |
| 718 | * @since 4.12.12 |
| 719 | * |
| 720 | * @param array<string,mixed> $default_arguments Current set of default arguments. |
| 721 | * @param static $instance The widget instance we are dealing with. |
| 722 | */ |
| 723 | return apply_filters( "tribe_widget_{$widget_slug}_default_arguments", $default_arguments, $this ); |
| 724 | } |
| 725 | |
| 726 | /** |
| 727 | * {@inheritDoc} |
| 728 | */ |
| 729 | public function filter_args_to_context( array $alterations = [], array $arguments = [] ) { |
| 730 | /** |
| 731 | * Applies a filter to arguments before they get turned into context. |
| 732 | * |
| 733 | * @since 4.13.0 |
| 734 | * |
| 735 | * @param array<string,mixed> $alterations Current set of alterations for the context. |
| 736 | * @param array<string,mixed> $arguments Current set of arguments in the widget. |
| 737 | * @param static $instance The widget instance we are dealing with. |
| 738 | */ |
| 739 | $alterations = apply_filters( 'tribe_widget_args_to_context', $alterations, $arguments, $this ); |
| 740 | |
| 741 | $widget_slug = static::get_widget_slug(); |
| 742 | |
| 743 | /** |
| 744 | * Applies a filter to arguments before they get turned into context based on the widget slug of the widget. |
| 745 | * |
| 746 | * @since 4.13.0 |
| 747 | * |
| 748 | * @param array<string,mixed> $alterations Current set of alterations for the context. |
| 749 | * @param array<string,mixed> $arguments Current set of arguments in the widget. |
| 750 | * @param static $instance The widget instance we are dealing with. |
| 751 | */ |
| 752 | return apply_filters( "tribe_widget_{$widget_slug}_args_to_context", $alterations, $arguments, $this ); |
| 753 | } |
| 754 | |
| 755 | /** |
| 756 | * Sets the admin template. |
| 757 | * |
| 758 | * @since 4.12.14 |
| 759 | * |
| 760 | * @param \Tribe__Template $template The admin template to use. |
| 761 | */ |
| 762 | public function set_admin_template( \Tribe__Template $template ) { |
| 763 | $this->admin_template = $template; |
| 764 | } |
| 765 | |
| 766 | /** |
| 767 | * Returns the current admin template. |
| 768 | * |
| 769 | * @since 4.12.14 |
| 770 | * |
| 771 | * @return \Tribe__Template The current admin template. |
| 772 | */ |
| 773 | public function get_admin_template() { |
| 774 | return $this->admin_template; |
| 775 | } |
| 776 | |
| 777 | /** |
| 778 | * Get the admin html for the widget form. |
| 779 | * |
| 780 | * @since 4.12.14 |
| 781 | * |
| 782 | * @param array<string,mixed> $arguments Current set of arguments. |
| 783 | * |
| 784 | * @return string HTML for the admin fields. |
| 785 | */ |
| 786 | public function get_admin_html( $arguments ) { |
| 787 | return $this->get_admin_template()->template( [ 'widgets', static::get_widget_slug() ], $arguments ); |
| 788 | } |
| 789 | |
| 790 | /** |
| 791 | * Toggles hooks for the widget, will be deactivated after the rendering has happened. |
| 792 | * |
| 793 | * @since 4.13.0 |
| 794 | * |
| 795 | * @param bool $toggle Whether to turn the hooks on or off. |
| 796 | * |
| 797 | * @return void |
| 798 | */ |
| 799 | public function toggle_hooks( $toggle ) { |
| 800 | if ( $toggle ) { |
| 801 | $this->add_hooks(); |
| 802 | } else { |
| 803 | $this->remove_hooks(); |
| 804 | } |
| 805 | |
| 806 | /** |
| 807 | * Fires after widget was setup while rendering a widget. |
| 808 | * |
| 809 | * @since 4.13.0 |
| 810 | * |
| 811 | * @param bool $toggle Whether the hooks should be turned on or off. This value is `true` before a widget |
| 812 | * HTML is rendered and `false` after the widget HTML rendered. |
| 813 | * @param static $this The widget object that is toggling the hooks. |
| 814 | */ |
| 815 | do_action( 'tribe_shortcode_toggle_hooks', $toggle, $this ); |
| 816 | } |
| 817 | |
| 818 | /** |
| 819 | * Toggles off portions of the template based on widget params. |
| 820 | * This runs on the `tribe_shortcode_toggle_hooks` hook when the toggle is true. |
| 821 | * |
| 822 | * @since 4.13.0 |
| 823 | */ |
| 824 | protected function add_hooks() { |
| 825 | |
| 826 | } |
| 827 | |
| 828 | /** |
| 829 | * Toggles on portions of the template that were modified in `add_template_mods()` above. |
| 830 | * This runs on the `tribe_shortcode_toggle_hooks` hook when the toggle is false. |
| 831 | * Thus encapsulating our control of these shared pieces to only when the widget is rendering. |
| 832 | * |
| 833 | * @since 4.13.0 |
| 834 | */ |
| 835 | protected function remove_hooks() { |
| 836 | |
| 837 | } |
| 838 | |
| 839 | /********************** |
| 840 | * Deprecated Methods * |
| 841 | **********************/ |
| 842 | |
| 843 | /** |
| 844 | * Slug of the current widget. |
| 845 | * |
| 846 | * @since 4.12.12 |
| 847 | * |
| 848 | * @deprecated 4.13.0 Moved into using static::$widget_slug |
| 849 | * @todo remove after 2021-08-01 |
| 850 | * |
| 851 | * @var string |
| 852 | */ |
| 853 | protected $slug; |
| 854 | |
| 855 | /** |
| 856 | * The slug of the admin widget view. |
| 857 | * |
| 858 | * @since 4.12.14 |
| 859 | * |
| 860 | * @deprecated 4.13.0 Moved into using static::$widget_slug |
| 861 | * @todo remove after 2021-08-01 |
| 862 | * |
| 863 | * @var string |
| 864 | */ |
| 865 | protected $view_admin_slug; |
| 866 | |
| 867 | /** |
| 868 | * {@inheritDoc} |
| 869 | * @deprecated 4.13.0 Moved into using static::get_widget_slug |
| 870 | */ |
| 871 | public function get_registration_slug() { |
| 872 | return static::get_widget_slug(); |
| 873 | } |
| 874 | } |
| 875 |