img_caption_shortcode

Advertisement

Summery Summery

Builds the Caption shortcode output.

Syntax Syntax

img_caption_shortcode( array $attr, string $content = null )

Description Description

Allows a plugin to replace the content that would otherwise be returned. The filter is ‘img_caption_shortcode’ and passes an empty string, the attr parameter and the content parameter values.

The supported attributes for the shortcode are ‘id’, ‘caption_id’, ‘align’, ‘width’, ‘caption’, and ‘class’.

Parameters Parameters

$attr

(Required) Attributes of the caption shortcode.

  • 'id'
    (string) ID of the image and caption container element, i.e. <figure> or <div>.
  • 'caption_id'
    (string) ID of the caption element, i.e. <figcaption> or <p>.
  • 'align'
    (string) Class name that aligns the caption. Default 'alignnone'. Accepts 'alignleft', 'aligncenter', alignright', 'alignnone'.
  • 'width'
    (int) The width of the caption, in pixels.
  • 'caption'
    (string) The caption text.
  • 'class'
    (string) Additional class name(s) added to the caption container.

$content

(Optional) Shortcode content.

Default value: null

Return Return

(string) HTML content to display the caption.

Source Source

File: wp-includes/media.php

 * @return bool Whether to add the attribute.
 */
function wp_lazy_loading_enabled( $tag_name, $context ) {
	// By default add to all 'img' tags.
	// See https://html.spec.whatwg.org/multipage/embedded-content.html#attr-img-loading
	$default = ( 'img' === $tag_name );

	/**
	 * Filters whether to add the `loading` attribute to the specified tag in the specified context.
	 *
	 * @since 5.5.0
	 *
	 * @param bool   $default  Default value.
	 * @param string $tag_name The tag name.
	 * @param string $context  Additional context, like the current filter name or the function name from where this was called.
	 */
	return (bool) apply_filters( 'wp_lazy_loading_enabled', $default, $tag_name, $context );
}

/**
 * Filters specific tags in post content and modifies their markup.
 *
 * Modifies HTML tags in post content to include new browser and HTML technologies
 * that may not have existed at the time of post creation. These modifications currently
 * include adding `srcset`, `sizes`, and `loading` attributes to `img` HTML tags.
 * Future similar optimizations should be added/expected here.
 *
 * @since 5.5.0
 *
 * @see wp_img_tag_add_width_and_height_attr()
 * @see wp_img_tag_add_srcset_and_sizes_attr()
 * @see wp_img_tag_add_loading_attr()
 *
 * @param string $content The HTML content to be filtered.
 * @param string $context Optional. Additional context to pass to the filters.
 *                        Defaults to `current_filter()` when not set.
 * @return string Converted content with images modified.
 */
function wp_filter_content_tags( $content, $context = null ) {
	if ( null === $context ) {
		$context = current_filter();
	}

	$add_loading_attr = wp_lazy_loading_enabled( 'img', $context );

	if ( false === strpos( $content, '<img' ) ) {
		return $content;
	}

	if ( ! preg_match_all( '/<img\s[^>]+>/', $content, $matches ) ) {
		return $content;
	}

	// List of the unique `img` tags found in $content.
	$images = array();

	foreach ( $matches[0] as $image ) {
		if ( preg_match( '/wp-image-([0-9]+)/i', $image, $class_id ) ) {
			$attachment_id = absint( $class_id[1] );

			if ( $attachment_id ) {
				// If exactly the same image tag is used more than once, overwrite it.
				// All identical tags will be replaced later with 'str_replace()'.
				$images[ $image ] = $attachment_id;
				continue;
			}
		}

		$images[ $image ] = 0;
	}

	// Reduce the array to unique attachment IDs.
	$attachment_ids = array_unique( array_filter( array_values( $images ) ) );

	if ( count( $attachment_ids ) > 1 ) {
		/*
		 * Warm the object cache with post and meta information for all found
		 * images to avoid making individual database calls.
		 */
		_prime_post_caches( $attachment_ids, false, true );
	}

	foreach ( $images as $image => $attachment_id ) {
		$filtered_image = $image;

		// Add 'width' and 'height' attributes if applicable.
		if ( $attachment_id > 0 && false === strpos( $filtered_image, ' width=' ) && false === strpos( $filtered_image, ' height=' ) ) {
			$filtered_image = wp_img_tag_add_width_and_height_attr( $filtered_image, $context, $attachment_id );
		}

		// Add 'srcset' and 'sizes' attributes if applicable.
		if ( $attachment_id > 0 && false === strpos( $filtered_image, ' srcset=' ) ) {
			$filtered_image = wp_img_tag_add_srcset_and_sizes_attr( $filtered_image, $context, $attachment_id );
		}

		// Add 'loading' attribute if applicable.
		if ( $add_loading_attr && false === strpos( $filtered_image, ' loading=' ) ) {
			$filtered_image = wp_img_tag_add_loading_attr( $filtered_image, $context );
		}

		if ( $filtered_image !== $image ) {
			$content = str_replace( $image, $filtered_image, $content );
		}
	}

	return $content;
}

/**
 * Adds `loading` attribute to an `img` HTML tag.
 *
 * @since 5.5.0
 *
 * @param string $image   The HTML `img` tag where the attribute should be added.
 * @param string $context Additional context to pass to the filters.
 * @return string Converted `img` tag with `loading` attribute added.
 */
function wp_img_tag_add_loading_attr( $image, $context ) {
	/**
	 * Filters the `loading` attribute value. Default `lazy`.
	 *
	 * Returning `false` or an empty string will not add the attribute.
	 * Returning `true` will add the default value.
	 *
	 * @since 5.5.0
	 *
	 * @param string|bool $value   The `loading` attribute value. Returning a falsey value will result in
	 *                             the attribute being omitted for the image. Default is `lazy`.
	 * @param string      $image   The HTML `img` tag to be filtered.
	 * @param string      $context Additional context about how the function was called or where the img tag is.

Advertisement

Changelog Changelog

Changelog
Version Description
5.1.0 The caption_id attribute was added.
3.9.0 The class attribute was added.
2.6.0 Introduced.

Advertisement

Leave a Reply