mirror of
https://github.com/WordPress/WordPress.git
synced 2024-12-26 19:18:57 +01:00
31d4d81039
The last time a new widget was introduced, Vuvuzelas were a thing, Angry Birds started taking over phones, and WordPress stopped shipping with Kubrick. Seven years and 17 releases without new widgets have been enough, time to spice up your sidebar! Props westonruter, melchoyce, obenland, timmydcrawford, adamsilverstein, gonom9, wonderboymusic, Fab1en, DrewAPicture, sirbrillig, joen, matias, samikeijonen, afercia, celloexpressions, designsimply, michelleweber, ranh, kjellr, karmatosed. Fixes #32417, #39993, #39994, #39995. Built from https://develop.svn.wordpress.org/trunk@40640 git-svn-id: http://core.svn.wordpress.org/trunk@40501 1a063a9b-81f0-0310-95a4-ce76da25c4cd
423 lines
13 KiB
PHP
423 lines
13 KiB
PHP
<?php
|
|
/**
|
|
* Widget API: WP_Media_Widget class
|
|
*
|
|
* @package WordPress
|
|
* @subpackage Widgets
|
|
* @since 4.8.0
|
|
*/
|
|
|
|
/**
|
|
* Core class that implements a media widget.
|
|
*
|
|
* @since 4.8.0
|
|
*
|
|
* @see WP_Widget
|
|
*/
|
|
abstract class WP_Widget_Media extends WP_Widget {
|
|
|
|
/**
|
|
* Translation labels.
|
|
*
|
|
* @since 4.8.0
|
|
* @var array
|
|
*/
|
|
public $l10n = array(
|
|
'add_to_widget' => '',
|
|
'replace_media' => '',
|
|
'edit_media' => '',
|
|
'media_library_state_multi' => '',
|
|
'media_library_state_single' => '',
|
|
'missing_attachment' => '',
|
|
'no_media_selected' => '',
|
|
'add_media' => '',
|
|
);
|
|
|
|
/**
|
|
* Constructor.
|
|
*
|
|
* @since 4.8.0
|
|
* @access public
|
|
*
|
|
* @param string $id_base Base ID for the widget, lowercase and unique.
|
|
* @param string $name Name for the widget displayed on the configuration page.
|
|
* @param array $widget_options Optional. Widget options. See wp_register_sidebar_widget() for
|
|
* information on accepted arguments. Default empty array.
|
|
* @param array $control_options Optional. Widget control options. See wp_register_widget_control()
|
|
* for information on accepted arguments. Default empty array.
|
|
*/
|
|
public function __construct( $id_base, $name, $widget_options = array(), $control_options = array() ) {
|
|
$widget_opts = wp_parse_args( $widget_options, array(
|
|
'description' => __( 'A media item.' ),
|
|
'customize_selective_refresh' => true,
|
|
'mime_type' => '',
|
|
) );
|
|
|
|
$control_opts = wp_parse_args( $control_options, array() );
|
|
|
|
$l10n_defaults = array(
|
|
'no_media_selected' => __( 'No media selected' ),
|
|
'add_media' => _x( 'Add Media', 'label for button in the media widget; should not be longer than ~13 characters long' ),
|
|
'replace_media' => _x( 'Replace Media', 'label for button in the media widget; should not be longer than ~13 characters long' ),
|
|
'edit_media' => _x( 'Edit Media', 'label for button in the media widget; should not be longer than ~13 characters long' ),
|
|
'add_to_widget' => __( 'Add to Widget' ),
|
|
'missing_attachment' => sprintf(
|
|
/* translators: placeholder is URL to media library */
|
|
__( 'We can’t find that file. Check your <a href="%s">media library</a> and make sure it wasn’t deleted.' ),
|
|
esc_url( admin_url( 'upload.php' ) )
|
|
),
|
|
/* translators: %d is widget count */
|
|
'media_library_state_multi' => _n_noop( 'Media Widget (%d)', 'Media Widget (%d)' ),
|
|
'media_library_state_single' => __( 'Media Widget' ),
|
|
'unsupported_file_type' => __( 'Looks like this isn’t the correct kind of file. Please link to an appropriate file instead.' ),
|
|
);
|
|
$this->l10n = array_merge( $l10n_defaults, array_filter( $this->l10n ) );
|
|
|
|
parent::__construct(
|
|
$id_base,
|
|
$name,
|
|
$widget_opts,
|
|
$control_opts
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Add hooks while registering all widget instances of this widget class.
|
|
*
|
|
* @since 4.8.0
|
|
* @access public
|
|
*/
|
|
public function _register() {
|
|
|
|
// Note that the widgets component in the customizer will also do the 'admin_print_scripts-widgets.php' action in WP_Customize_Widgets::print_scripts().
|
|
add_action( 'admin_print_scripts-widgets.php', array( $this, 'enqueue_admin_scripts' ) );
|
|
|
|
if ( $this->is_preview() ) {
|
|
add_action( 'wp_enqueue_scripts', array( $this, 'enqueue_preview_scripts' ) );
|
|
}
|
|
|
|
// Note that the widgets component in the customizer will also do the 'admin_footer-widgets.php' action in WP_Customize_Widgets::print_footer_scripts().
|
|
add_action( 'admin_footer-widgets.php', array( $this, 'render_control_template_scripts' ) );
|
|
|
|
add_filter( 'display_media_states', array( $this, 'display_media_state' ), 10, 2 );
|
|
|
|
parent::_register();
|
|
}
|
|
|
|
/**
|
|
* Get schema for properties of a widget instance (item).
|
|
*
|
|
* @since 4.8.0
|
|
* @access public
|
|
*
|
|
* @see WP_REST_Controller::get_item_schema()
|
|
* @see WP_REST_Controller::get_additional_fields()
|
|
* @link https://core.trac.wordpress.org/ticket/35574
|
|
* @return array Schema for properties.
|
|
*/
|
|
public function get_instance_schema() {
|
|
return array(
|
|
'attachment_id' => array(
|
|
'type' => 'integer',
|
|
'default' => 0,
|
|
'minimum' => 0,
|
|
'description' => __( 'Attachment post ID' ),
|
|
'media_prop' => 'id',
|
|
),
|
|
'url' => array(
|
|
'type' => 'string',
|
|
'default' => '',
|
|
'format' => 'uri',
|
|
'description' => __( 'URL to the media file' ),
|
|
),
|
|
'title' => array(
|
|
'type' => 'string',
|
|
'default' => '',
|
|
'sanitize_callback' => 'sanitize_text_field',
|
|
'description' => __( 'Title for the widget' ),
|
|
'should_preview_update' => false,
|
|
),
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Determine if the supplied attachment is for a valid attachment post with the specified MIME type.
|
|
*
|
|
* @since 4.8.0
|
|
* @access public
|
|
*
|
|
* @param int|WP_Post $attachment Attachment post ID or object.
|
|
* @param string $mime_type MIME type.
|
|
* @return bool Is matching MIME type.
|
|
*/
|
|
public function is_attachment_with_mime_type( $attachment, $mime_type ) {
|
|
if ( empty( $attachment ) ) {
|
|
return false;
|
|
}
|
|
$attachment = get_post( $attachment );
|
|
if ( ! $attachment ) {
|
|
return false;
|
|
}
|
|
if ( 'attachment' !== $attachment->post_type ) {
|
|
return false;
|
|
}
|
|
return wp_attachment_is( $mime_type, $attachment );
|
|
}
|
|
|
|
/**
|
|
* Sanitize a token list string, such as used in HTML rel and class attributes.
|
|
*
|
|
* @since 4.8.0
|
|
* @access public
|
|
*
|
|
* @link http://w3c.github.io/html/infrastructure.html#space-separated-tokens
|
|
* @link https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList
|
|
* @param string|array $tokens List of tokens separated by spaces, or an array of tokens.
|
|
* @return string Sanitized token string list.
|
|
*/
|
|
public function sanitize_token_list( $tokens ) {
|
|
if ( is_string( $tokens ) ) {
|
|
$tokens = preg_split( '/\s+/', trim( $tokens ) );
|
|
}
|
|
$tokens = array_map( 'sanitize_html_class', $tokens );
|
|
$tokens = array_filter( $tokens );
|
|
return join( ' ', $tokens );
|
|
}
|
|
|
|
/**
|
|
* Displays the widget on the front-end.
|
|
*
|
|
* @since 4.8.0
|
|
* @access public
|
|
*
|
|
* @see WP_Widget::widget()
|
|
*
|
|
* @param array $args Display arguments including before_title, after_title, before_widget, and after_widget.
|
|
* @param array $instance Saved setting from the database.
|
|
*/
|
|
public function widget( $args, $instance ) {
|
|
$instance = wp_parse_args( $instance, wp_list_pluck( $this->get_instance_schema(), 'default' ) );
|
|
|
|
// Short-circuit if no media is selected.
|
|
if ( ! $this->has_content( $instance ) ) {
|
|
return;
|
|
}
|
|
|
|
echo $args['before_widget'];
|
|
|
|
if ( $instance['title'] ) {
|
|
|
|
/** This filter is documented in wp-includes/widgets/class-wp-widget-pages.php */
|
|
$title = apply_filters( 'widget_title', $instance['title'], $instance, $this->id_base );
|
|
echo $args['before_title'] . $title . $args['after_title'];
|
|
}
|
|
|
|
/**
|
|
* Filters the media widget instance prior to rendering the media.
|
|
*
|
|
* @since 4.8.0
|
|
*
|
|
* @param array $instance Instance data.
|
|
* @param array $args Widget args.
|
|
* @param WP_Widget_Media $this Widget object.
|
|
*/
|
|
$instance = apply_filters( "widget_{$this->id_base}_instance", $instance, $args, $this );
|
|
|
|
$this->render_media( $instance );
|
|
|
|
echo $args['after_widget'];
|
|
}
|
|
|
|
/**
|
|
* Sanitizes the widget form values as they are saved.
|
|
*
|
|
* @since 4.8.0
|
|
* @access public
|
|
*
|
|
* @see WP_Widget::update()
|
|
* @see WP_REST_Request::has_valid_params()
|
|
* @see WP_REST_Request::sanitize_params()
|
|
*
|
|
* @param array $new_instance Values just sent to be saved.
|
|
* @param array $instance Previously saved values from database.
|
|
* @return array Updated safe values to be saved.
|
|
*/
|
|
public function update( $new_instance, $instance ) {
|
|
|
|
$schema = $this->get_instance_schema();
|
|
foreach ( $schema as $field => $field_schema ) {
|
|
if ( ! array_key_exists( $field, $new_instance ) ) {
|
|
continue;
|
|
}
|
|
$value = $new_instance[ $field ];
|
|
if ( true !== rest_validate_value_from_schema( $value, $field_schema, $field ) ) {
|
|
continue;
|
|
}
|
|
|
|
$value = rest_sanitize_value_from_schema( $value, $field_schema );
|
|
|
|
// @codeCoverageIgnoreStart
|
|
if ( is_wp_error( $value ) ) {
|
|
continue; // Handle case when rest_sanitize_value_from_schema() ever returns WP_Error as its phpdoc @return tag indicates.
|
|
}
|
|
|
|
// @codeCoverageIgnoreEnd
|
|
if ( isset( $field_schema['sanitize_callback'] ) ) {
|
|
$value = call_user_func( $field_schema['sanitize_callback'], $value );
|
|
}
|
|
if ( is_wp_error( $value ) ) {
|
|
continue;
|
|
}
|
|
$instance[ $field ] = $value;
|
|
}
|
|
|
|
return $instance;
|
|
}
|
|
|
|
/**
|
|
* Render the media on the frontend.
|
|
*
|
|
* @since 4.8.0
|
|
* @access public
|
|
*
|
|
* @param array $instance Widget instance props.
|
|
* @return string
|
|
*/
|
|
abstract public function render_media( $instance );
|
|
|
|
/**
|
|
* Outputs the settings update form.
|
|
*
|
|
* Note that the widget UI itself is rendered with JavaScript via `MediaWidgetControl#render()`.
|
|
*
|
|
* @since 4.8.0
|
|
* @access public
|
|
*
|
|
* @see \WP_Widget_Media::render_control_template_scripts() Where the JS template is located.
|
|
* @param array $instance Current settings.
|
|
* @return void
|
|
*/
|
|
final public function form( $instance ) {
|
|
$instance_schema = $this->get_instance_schema();
|
|
$instance = wp_array_slice_assoc(
|
|
wp_parse_args( (array) $instance, wp_list_pluck( $instance_schema, 'default' ) ),
|
|
array_keys( $instance_schema )
|
|
);
|
|
|
|
foreach ( $instance as $name => $value ) : ?>
|
|
<input
|
|
type="hidden"
|
|
data-property="<?php echo esc_attr( $name ); ?>"
|
|
class="media-widget-instance-property"
|
|
name="<?php echo esc_attr( $this->get_field_name( $name ) ); ?>"
|
|
id="<?php echo esc_attr( $this->get_field_id( $name ) ); // Needed specifically by wpWidgets.appendTitle(). ?>"
|
|
value="<?php echo esc_attr( strval( $value ) ); ?>"
|
|
/>
|
|
<?php
|
|
endforeach;
|
|
}
|
|
|
|
/**
|
|
* Filters the default media display states for items in the Media list table.
|
|
*
|
|
* @since 4.8.0
|
|
* @access public
|
|
*
|
|
* @param array $states An array of media states.
|
|
* @param WP_Post $post The current attachment object.
|
|
* @return array
|
|
*/
|
|
public function display_media_state( $states, $post = null ) {
|
|
if ( ! $post ) {
|
|
$post = get_post();
|
|
}
|
|
|
|
// Count how many times this attachment is used in widgets.
|
|
$use_count = 0;
|
|
foreach ( $this->get_settings() as $instance ) {
|
|
if ( isset( $instance['attachment_id'] ) && $instance['attachment_id'] === $post->ID ) {
|
|
$use_count++;
|
|
}
|
|
}
|
|
|
|
if ( 1 === $use_count ) {
|
|
$states[] = $this->l10n['media_library_state_single'];
|
|
} elseif ( $use_count > 0 ) {
|
|
$states[] = sprintf( translate_nooped_plural( $this->l10n['media_library_state_multi'], $use_count ), number_format_i18n( $use_count ) );
|
|
}
|
|
|
|
return $states;
|
|
}
|
|
|
|
/**
|
|
* Enqueue preview scripts.
|
|
*
|
|
* These scripts normally are enqueued just-in-time when a widget is rendered.
|
|
* In the customizer, however, widgets can be dynamically added and rendered via
|
|
* selective refresh, and so it is important to unconditionally enqueue them in
|
|
* case a widget does get added.
|
|
*
|
|
* @since 4.8.0
|
|
* @access public
|
|
*/
|
|
public function enqueue_preview_scripts() {}
|
|
|
|
/**
|
|
* Loads the required scripts and styles for the widget control.
|
|
*
|
|
* @since 4.8.0
|
|
* @access public
|
|
*/
|
|
public function enqueue_admin_scripts() {
|
|
wp_enqueue_media();
|
|
wp_enqueue_script( 'media-widgets' );
|
|
}
|
|
|
|
/**
|
|
* Render form template scripts.
|
|
*
|
|
* @since 4.8.0
|
|
* @access public
|
|
*/
|
|
public function render_control_template_scripts() {
|
|
?>
|
|
<script type="text/html" id="tmpl-widget-media-<?php echo esc_attr( $this->id_base ); ?>-control">
|
|
<# var elementIdPrefix = 'el' + String( Math.random() ) + '_' #>
|
|
<p>
|
|
<label for="{{ elementIdPrefix }}title"><?php esc_html_e( 'Title:' ); ?></label>
|
|
<input id="{{ elementIdPrefix }}title" type="text" class="widefat title">
|
|
</p>
|
|
<div class="media-widget-preview">
|
|
<div class="attachment-media-view">
|
|
<div class="placeholder"><?php echo esc_html( $this->l10n['no_media_selected'] ); ?></div>
|
|
</div>
|
|
</div>
|
|
<p class="media-widget-buttons">
|
|
<button type="button" class="button edit-media selected">
|
|
<?php echo esc_html( $this->l10n['edit_media'] ); ?>
|
|
</button>
|
|
<button type="button" class="button change-media select-media selected">
|
|
<?php echo esc_html( $this->l10n['replace_media'] ); ?>
|
|
</button>
|
|
<button type="button" class="button select-media not-selected">
|
|
<?php echo esc_html( $this->l10n['add_media'] ); ?>
|
|
</button>
|
|
</p>
|
|
</script>
|
|
<?php
|
|
}
|
|
|
|
/**
|
|
* Whether the widget has content to show.
|
|
*
|
|
* @since 4.8.0
|
|
* @access protected
|
|
*
|
|
* @param array $instance Widget instance props.
|
|
* @return bool Whether widget has content.
|
|
*/
|
|
protected function has_content( $instance ) {
|
|
return ( $instance['attachment_id'] && 'attachment' === get_post_type( $instance['attachment_id'] ) ) || $instance['url'];
|
|
}
|
|
}
|