mirror of
https://github.com/WordPress/WordPress.git
synced 2024-09-30 16:17:56 +02:00
0860bb2771
Prior to about 2013, many class methods lacked even access modifiers which made the `@access` notations that much more useful. Now that we've gotten to a point where the codebase is more mature from a maintenance perspective and we can finally remove these notations. Notable exceptions to this change include standalone functions notated as private as well as some classes still considered to represent "private" APIs. See #41452. Built from https://develop.svn.wordpress.org/trunk@41162 git-svn-id: http://core.svn.wordpress.org/trunk@41002 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' => '',
|
|
);
|
|
|
|
/**
|
|
* Whether or not the widget has been registered yet.
|
|
*
|
|
* @since 4.8.1
|
|
* @var bool
|
|
*/
|
|
protected $registered = false;
|
|
|
|
/**
|
|
* Constructor.
|
|
*
|
|
* @since 4.8.0
|
|
*
|
|
* @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' ),
|
|
'replace_media' => _x( 'Replace Media', 'label for button in the media widget; should preferably not be longer than ~13 characters long' ),
|
|
'edit_media' => _x( 'Edit Media', 'label for button in the media widget; should preferably 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
|
|
*
|
|
* @param integer $number Optional. The unique order number of this widget instance
|
|
* compared to other instances of the same class. Default -1.
|
|
*/
|
|
public function _register_one( $number = -1 ) {
|
|
parent::_register_one( $number );
|
|
if ( $this->registered ) {
|
|
return;
|
|
}
|
|
$this->registered = true;
|
|
|
|
// 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 );
|
|
}
|
|
|
|
/**
|
|
* Get schema for properties of a widget instance (item).
|
|
*
|
|
* @since 4.8.0
|
|
*
|
|
* @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
|
|
*
|
|
* @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
|
|
*
|
|
* @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
|
|
*
|
|
* @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
|
|
*
|
|
* @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
|
|
*
|
|
* @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
|
|
*
|
|
* @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
|
|
*
|
|
* @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
|
|
*/
|
|
public function enqueue_preview_scripts() {}
|
|
|
|
/**
|
|
* Loads the required scripts and styles for the widget control.
|
|
*
|
|
* @since 4.8.0
|
|
*/
|
|
public function enqueue_admin_scripts() {
|
|
wp_enqueue_media();
|
|
wp_enqueue_script( 'media-widgets' );
|
|
}
|
|
|
|
/**
|
|
* Render form template scripts.
|
|
*
|
|
* @since 4.8.0
|
|
*/
|
|
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
|
|
*
|
|
* @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'];
|
|
}
|
|
}
|