Over the past several releases, the Customizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. API An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. has drastically improved its built-in media controls, empowering developers to leverage the power of the WordPress media management experience in themes and plugins with ease. WordPress 4.1 refactored the image and upload controls to leverage the media modal for the first time (see #21483). 4.2 abstracted this functionality to a new base media control class. And now in WordPress 4.3, we’ve added a control for cropped images. In this post, I’ll outline the recent changes in Customizer media controls and explain the differences between the available controls.
WP_Customize_Media_Control
Before WordPress 4.2, all Customizer media controls saved the file url to their corresponding settings. While this facilitates quick access when using the value of the setting in themes and plugins, it makes it more difficult to access other information about that attachment, such as its title/caption, mime type, or in the case of images, accessing specific image sizes.
WP_Customize_Media_Control was introduced to allow this paradigm to change while maintaining backwards compatibility for the existing WP_Customize_Upload_Control and WP_Customize_Image_Control, which now extend the media control class (see #29215). The media control will save the attachment id for the selected media file to the Customizer setting, rather than the file URL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org. However, note that the default value of the setting must still be a URL, since a default attachment id doesn’t really make sense.
The media control can be used for any type of media, be it an image, audio, video, PDF document, or any other file format that your server supports. To restrict a media control instance to a particular type of content, use the mime_type parameter when adding the control:
$wp_customize->add_control( new WP_Customize_Media_Control( $wp_customize, 'audio_control', array(
'label' => __( 'Media Control (audio)' ),
'section' => 'media',
'mime_type' => 'audio',
) ) );
When working with a setting corresponding with a media control, the sanitize_callback should generally be absint(), since a numerical id is expected. When using get_option() and get_theme_mod(), functions such as wp_get_attachment_url(), wp_get_attachment_image(), wp_get_attachment_image_src(), and even get_post() are useful depending on your needs, with each function taking the attachment id (value of the setting) as a parameter.
The full power of WP_Customize_Media_Control is realized when the control is extended to implement additional custom functionality in a custom child control. WP_Customize_Cropped_Image_Control is a great example of this in core Core is the set of software required to run WordPress. The Core Development Team builds WordPress.. The core Customizer control classes provide several working examples of this; see wp-includes/class-wp-customize-control.php and wp-admin/js/customize-controls.js.
WP_Customize_Cropped_Image_Control
New in WordPress 4.3, WP_Customize_Cropped_Image_Control extracts functionality from the header The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. image control to allow an image to be cropped to specific dimensions (see #29211). This offers a better user experience than automatic cropping in many cases when images of a certain size or aspect ratio are required in themes and plugins. In core, the new site icon feature relies heavily on the cropped-image control, implementing a child custom control to add additional site-icon-specific functionality.
The cropped image control comes with four custom parameters in addition to those available in the media control. These are used to specify the required (or recommended) image dimensions, as well as specifying whether alternative dimensions are allowed (the flex options). Here’s a typical usage when adding a cropped-image control:
$wp_customize->add_control( new WP_Customize_Cropped_Image_Control( $wp_customize, 'cropped_image', array(
'section' => 'background_image',
'label' => __( 'Croppable Image' ),
'flex_width' => true, // Allow any width, making the specified value recommended. False by default.
'flex_height' => false, // Require the resulting image to be exactly as tall as the height attribute (default).
'width' => 1920,
'height' => 1080,
) ) );
The cropped-image control creates a child attachment of the original image attachment object for the cropped image, preserving the original version. The cropped-image attachment is given a context based on the control id (with _ replaced by -). The core control doesn’t currently use this, but it could be leveraged to query for previously-cropped images for a specific control to add a library feature in the future or in child controls. Be mindful that a version of the control id is stored in the database for cropped image attachments.
As with the media control, the cropped-image control saves the attachment id instead of the image URL. This can be useful for querying specific sizes of the image, but you’ll typically want the full size image at the cropped dimension. wp_get_attachment_image_src( absint( get_option( 'cropped_image_setting' ) ) ) should do the trick if that’s the case, when outputting the value of the setting.
#4-2, #4-3, #customize, #dev-notes, #media, #media-modal
