1<?php
2/**
3 * Widget API: WP_Media_Widget class
4 *
5 * @package WordPress
6 * @subpackage Widgets
7 * @since 4.8.0
8 */
9
10/**
11 * Core class that implements a media widget.
12 *
13 * @since 4.8.0
14 *
15 * @see WP_Widget
16 */
17abstract class WP_Widget_Media extends WP_Widget {
18
19 /**
20 * Translation labels.
21 *
22 * @since 4.8.0
23 * @var array
24 */
25 public $l10n = array(
26 'add_to_widget' => '',
27 'replace_media' => '',
28 'edit_media' => '',
29 'media_library_state_multi' => '',
30 'media_library_state_single' => '',
31 'missing_attachment' => '',
32 'no_media_selected' => '',
33 'add_media' => '',
34 );
35
36 /**
37 * Whether or not the widget has been registered yet.
38 *
39 * @since 4.8.1
40 * @var bool
41 */
42 protected $registered = false;
43
44 /**
45 * The default widget description.
46 *
47 * @since 6.0.0
48 * @var string
49 */
50 protected static $default_description = '';
51
52 /**
53 * The default localized strings used by the widget.
54 *
55 * @since 6.0.0
56 * @var string[]
57 */
58 protected static $l10n_defaults = array();
59
60 /**
61 * Constructor.
62 *
63 * @since 4.8.0
64 *
65 * @param string $id_base Base ID for the widget, lowercase and unique.
66 * @param string $name Name for the widget displayed on the configuration page.
67 * @param array $widget_options Optional. Widget options. See wp_register_sidebar_widget() for
68 * information on accepted arguments. Default empty array.
69 * @param array $control_options Optional. Widget control options. See wp_register_widget_control()
70 * for information on accepted arguments. Default empty array.
71 */
72 public function __construct( $id_base, $name, $widget_options = array(), $control_options = array() ) {
73 $widget_opts = wp_parse_args(
74 $widget_options,
75 array(
76 'description' => self::get_default_description(),
77 'customize_selective_refresh' => true,
78 'show_instance_in_rest' => true,
79 'mime_type' => '',
80 )
81 );
82
83 $control_opts = wp_parse_args( $control_options, array() );
84
85 $this->l10n = array_merge( self::get_l10n_defaults(), array_filter( $this->l10n ) );
86
87 parent::__construct(
88 $id_base,
89 $name,
90 $widget_opts,
91 $control_opts
92 );
93 }
94
95 /**
96 * Add hooks while registering all widget instances of this widget class.
97 *
98 * @since 4.8.0
99 *
100 * @param int $number Optional. The unique order number of this widget instance
101 * compared to other instances of the same class. Default -1.
102 */
103 public function _register_one( $number = -1 ) {
104 parent::_register_one( $number );
105 if ( $this->registered ) {
106 return;
107 }
108 $this->registered = true;
109
110 /*
111 * Note that the widgets component in the customizer will also do
112 * the 'admin_print_scripts-widgets.php' action in WP_Customize_Widgets::print_scripts().
113 */
114 add_action( 'admin_print_scripts-widgets.php', array( $this, 'enqueue_admin_scripts' ) );
115
116 if ( $this->is_preview() ) {
117 add_action( 'wp_enqueue_scripts', array( $this, 'enqueue_preview_scripts' ) );
118 }
119
120 /*
121 * Note that the widgets component in the customizer will also do
122 * the 'admin_footer-widgets.php' action in WP_Customize_Widgets::print_footer_scripts().
123 */
124 add_action( 'admin_footer-widgets.php', array( $this, 'render_control_template_scripts' ) );
125
126 add_filter( 'display_media_states', array( $this, 'display_media_state' ), 10, 2 );
127 }
128
129 /**
130 * Get schema for properties of a widget instance (item).
131 *
132 * @since 4.8.0
133 *
134 * @see WP_REST_Controller::get_item_schema()
135 * @see WP_REST_Controller::get_additional_fields()
136 * @link https://core.trac.wordpress.org/ticket/35574
137 *
138 * @return array Schema for properties.
139 */
140 public function get_instance_schema() {
141 $schema = array(
142 'attachment_id' => array(
143 'type' => 'integer',
144 'default' => 0,
145 'minimum' => 0,
146 'description' => __( 'Attachment post ID' ),
147 'media_prop' => 'id',
148 ),
149 'url' => array(
150 'type' => 'string',
151 'default' => '',
152 'format' => 'uri',
153 'description' => __( 'URL to the media file' ),
154 ),
155 'title' => array(
156 'type' => 'string',
157 'default' => '',
158 'sanitize_callback' => 'sanitize_text_field',
159 'description' => __( 'Title for the widget' ),
160 'should_preview_update' => false,
161 ),
162 );
163
164 /**
165 * Filters the media widget instance schema to add additional properties.
166 *
167 * @since 4.9.0
168 *
169 * @param array $schema Instance schema.
170 * @param WP_Widget_Media $widget Widget object.
171 */
172 $schema = apply_filters( "widget_{$this->id_base}_instance_schema", $schema, $this );
173
174 return $schema;
175 }
176
177 /**
178 * Determine if the supplied attachment is for a valid attachment post with the specified MIME type.
179 *
180 * @since 4.8.0
181 *
182 * @param int|WP_Post $attachment Attachment post ID or object.
183 * @param string $mime_type MIME type.
184 * @return bool Is matching MIME type.
185 */
186 public function is_attachment_with_mime_type( $attachment, $mime_type ) {
187 if ( empty( $attachment ) ) {
188 return false;
189 }
190 $attachment = get_post( $attachment );
191 if ( ! $attachment ) {
192 return false;
193 }
194 if ( 'attachment' !== $attachment->post_type ) {
195 return false;
196 }
197 return wp_attachment_is( $mime_type, $attachment );
198 }
199
200 /**
201 * Sanitize a token list string, such as used in HTML rel and class attributes.
202 *
203 * @since 4.8.0
204 *
205 * @link http://w3c.github.io/html/infrastructure.html#space-separated-tokens
206 * @link https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList
207 * @param string|array $tokens List of tokens separated by spaces, or an array of tokens.
208 * @return string Sanitized token string list.
209 */
210 public function sanitize_token_list( $tokens ) {
211 if ( is_string( $tokens ) ) {
212 $tokens = preg_split( '/\s+/', trim( $tokens ) );
213 }
214 $tokens = array_map( 'sanitize_html_class', $tokens );
215 $tokens = array_filter( $tokens );
216 return implode( ' ', $tokens );
217 }
218
219 /**
220 * Displays the widget on the front-end.
221 *
222 * @since 4.8.0
223 *
224 * @see WP_Widget::widget()
225 *
226 * @param array $args Display arguments including before_title, after_title, before_widget, and after_widget.
227 * @param array $instance Saved setting from the database.
228 */
229 public function widget( $args, $instance ) {
230 $instance = wp_parse_args( $instance, wp_list_pluck( $this->get_instance_schema(), 'default' ) );
231
232 // Short-circuit if no media is selected.
233 if ( ! $this->has_content( $instance ) ) {
234 return;
235 }
236
237 echo $args['before_widget'];
238
239 /** This filter is documented in wp-includes/widgets/class-wp-widget-pages.php */
240 $title = apply_filters( 'widget_title', $instance['title'], $instance, $this->id_base );
241
242 if ( $title ) {
243 echo $args['before_title'] . $title . $args['after_title'];
244 }
245
246 /**
247 * Filters the media widget instance prior to rendering the media.
248 *
249 * @since 4.8.0
250 *
251 * @param array $instance Instance data.
252 * @param array $args Widget args.
253 * @param WP_Widget_Media $widget Widget object.
254 */
255 $instance = apply_filters( "widget_{$this->id_base}_instance", $instance, $args, $this );
256
257 $this->render_media( $instance );
258
259 echo $args['after_widget'];
260 }
261
262 /**
263 * Sanitizes the widget form values as they are saved.
264 *
265 * @since 4.8.0
266 * @since 5.9.0 Renamed `$instance` to `$old_instance` to match parent class
267 * for PHP 8 named parameter support.
268 *
269 * @see WP_Widget::update()
270 * @see WP_REST_Request::has_valid_params()
271 * @see WP_REST_Request::sanitize_params()
272 *
273 * @param array $new_instance Values just sent to be saved.
274 * @param array $old_instance Previously saved values from database.
275 * @return array Updated safe values to be saved.
276 */
277 public function update( $new_instance, $old_instance ) {
278
279 $schema = $this->get_instance_schema();
280 foreach ( $schema as $field => $field_schema ) {
281 if ( ! array_key_exists( $field, $new_instance ) ) {
282 continue;
283 }
284 $value = $new_instance[ $field ];
285
286 /*
287 * Workaround for rest_validate_value_from_schema() due to the fact that
288 * rest_is_boolean( '' ) === false, while rest_is_boolean( '1' ) is true.
289 */
290 if ( 'boolean' === $field_schema['type'] && '' === $value ) {
291 $value = false;
292 }
293
294 if ( true !== rest_validate_value_from_schema( $value, $field_schema, $field ) ) {
295 continue;
296 }
297
298 $value = rest_sanitize_value_from_schema( $value, $field_schema );
299
300 // @codeCoverageIgnoreStart
301 if ( is_wp_error( $value ) ) {
302 continue; // Handle case when rest_sanitize_value_from_schema() ever returns WP_Error as its phpdoc @return tag indicates.
303 }
304
305 // @codeCoverageIgnoreEnd
306 if ( isset( $field_schema['sanitize_callback'] ) ) {
307 $value = call_user_func( $field_schema['sanitize_callback'], $value );
308 }
309 if ( is_wp_error( $value ) ) {
310 continue;
311 }
312 $old_instance[ $field ] = $value;
313 }
314
315 return $old_instance;
316 }
317
318 /**
319 * Render the media on the frontend.
320 *
321 * @since 4.8.0
322 *
323 * @param array $instance Widget instance props.
324 */
325 abstract public function render_media( $instance );
326
327 /**
328 * Outputs the settings update form.
329 *
330 * Note that the widget UI itself is rendered with JavaScript via `MediaWidgetControl#render()`.
331 *
332 * @since 4.8.0
333 *
334 * @see \WP_Widget_Media::render_control_template_scripts() Where the JS template is located.
335 *
336 * @param array $instance Current settings.
337 */
338 final public function form( $instance ) {
339 $instance_schema = $this->get_instance_schema();
340 $instance = wp_array_slice_assoc(
341 wp_parse_args( (array) $instance, wp_list_pluck( $instance_schema, 'default' ) ),
342 array_keys( $instance_schema )
343 );
344
345 foreach ( $instance as $name => $value ) : ?>
346 <input
347 type="hidden"
348 data-property="<?php echo esc_attr( $name ); ?>"
349 class="media-widget-instance-property"
350 name="<?php echo esc_attr( $this->get_field_name( $name ) ); ?>"
351 id="<?php echo esc_attr( $this->get_field_id( $name ) ); // Needed specifically by wpWidgets.appendTitle(). ?>"
352 value="<?php echo esc_attr( is_array( $value ) ? implode( ',', $value ) : (string) $value ); ?>"
353 />
354 <?php
355 endforeach;
356 }
357
358 /**
359 * Filters the default media display states for items in the Media list table.
360 *
361 * @since 4.8.0
362 *
363 * @param array $states An array of media states.
364 * @param WP_Post $post The current attachment object.
365 * @return array
366 */
367 public function display_media_state( $states, $post = null ) {
368 if ( ! $post ) {
369 $post = get_post();
370 }
371
372 // Count how many times this attachment is used in widgets.
373 $use_count = 0;
374 foreach ( $this->get_settings() as $instance ) {
375 if ( isset( $instance['attachment_id'] ) && $instance['attachment_id'] === $post->ID ) {
376 ++$use_count;
377 }
378 }
379
380 if ( 1 === $use_count ) {
381 $states[] = $this->l10n['media_library_state_single'];
382 } elseif ( $use_count > 0 ) {
383 $states[] = sprintf( translate_nooped_plural( $this->l10n['media_library_state_multi'], $use_count ), number_format_i18n( $use_count ) );
384 }
385
386 return $states;
387 }
388
389 /**
390 * Enqueue preview scripts.
391 *
392 * These scripts normally are enqueued just-in-time when a widget is rendered.
393 * In the customizer, however, widgets can be dynamically added and rendered via
394 * selective refresh, and so it is important to unconditionally enqueue them in
395 * case a widget does get added.
396 *
397 * @since 4.8.0
398 */
399 public function enqueue_preview_scripts() {}
400
401 /**
402 * Loads the required scripts and styles for the widget control.
403 *
404 * @since 4.8.0
405 */
406 public function enqueue_admin_scripts() {
407 wp_enqueue_media();
408 wp_enqueue_script( 'media-widgets' );
409 }
410
411 /**
412 * Render form template scripts.
413 *
414 * @since 4.8.0
415 */
416 public function render_control_template_scripts() {
417 ?>
418 <script type="text/html" id="tmpl-widget-media-<?php echo esc_attr( $this->id_base ); ?>-control">
419 <# var elementIdPrefix = 'el' + String( Math.random() ) + '_' #>
420 <p>
421 <label for="{{ elementIdPrefix }}title"><?php esc_html_e( 'Title:' ); ?></label>
422 <input id="{{ elementIdPrefix }}title" type="text" class="widefat title">
423 </p>
424 <div class="media-widget-preview <?php echo esc_attr( $this->id_base ); ?>">
425 <div class="attachment-media-view">
426 <button type="button" class="select-media button-add-media not-selected">
427 <?php echo esc_html( $this->l10n['add_media'] ); ?>
428 </button>
429 </div>
430 </div>
431 <p class="media-widget-buttons">
432 <button type="button" class="button edit-media selected">
433 <?php echo esc_html( $this->l10n['edit_media'] ); ?>
434 </button>
435 <?php if ( ! empty( $this->l10n['replace_media'] ) ) : ?>
436 <button type="button" class="button change-media select-media selected">
437 <?php echo esc_html( $this->l10n['replace_media'] ); ?>
438 </button>
439 <?php endif; ?>
440 </p>
441 <div class="media-widget-fields">
442 </div>
443 </script>
444 <?php
445 }
446
447 /**
448 * Resets the cache for the default labels.
449 *
450 * @since 6.0.0
451 */
452 public static function reset_default_labels() {
453 self::$default_description = '';
454 self::$l10n_defaults = array();
455 }
456
457 /**
458 * Whether the widget has content to show.
459 *
460 * @since 4.8.0
461 *
462 * @param array $instance Widget instance props.
463 * @return bool Whether widget has content.
464 */
465 protected function has_content( $instance ) {
466 return ( $instance['attachment_id'] && 'attachment' === get_post_type( $instance['attachment_id'] ) ) || $instance['url'];
467 }
468
469 /**
470 * Returns the default description of the widget.
471 *
472 * @since 6.0.0
473 *
474 * @return string
475 */
476 protected static function get_default_description() {
477 if ( self::$default_description ) {
478 return self::$default_description;
479 }
480
481 self::$default_description = __( 'A media item.' );
482 return self::$default_description;
483 }
484
485 /**
486 * Returns the default localized strings used by the widget.
487 *
488 * @since 6.0.0
489 *
490 * @return (string|array)[]
491 */
492 protected static function get_l10n_defaults() {
493 if ( ! empty( self::$l10n_defaults ) ) {
494 return self::$l10n_defaults;
495 }
496
497 self::$l10n_defaults = array(
498 'no_media_selected' => __( 'No media selected' ),
499 'add_media' => _x( 'Add Media', 'label for button in the media widget' ),
500 'replace_media' => _x( 'Replace Media', 'label for button in the media widget; should preferably not be longer than ~13 characters long' ),
501 'edit_media' => _x( 'Edit Media', 'label for button in the media widget; should preferably not be longer than ~13 characters long' ),
502 'add_to_widget' => __( 'Add to Widget' ),
503 'missing_attachment' => sprintf(
504 /* translators: %s: URL to media library. */
505 __( 'That file cannot be found. Check your <a href="%s">media library</a> and make sure it was not deleted.' ),
506 esc_url( admin_url( 'upload.php' ) )
507 ),
508 /* translators: %d: Widget count. */
509 'media_library_state_multi' => _n_noop( 'Media Widget (%d)', 'Media Widget (%d)' ),
510 'media_library_state_single' => __( 'Media Widget' ),
511 'unsupported_file_type' => __( 'Looks like this is not the correct kind of file. Please link to an appropriate file instead.' ),
512 );
513
514 return self::$l10n_defaults;
515 }
516}
517