' . t('The Responsive Image module provides an image formatter and breakpoint mappings to output responsive images using the HTML5 picture tag. For more information, see the online documentation for the Responsive Image module.', array( '!responsive_image' => 'https://www.drupal.org/documentation/modules/responsive_image')) . '

' . t('Uses') . '

'; $output .= '

' . t('Defining responsive image styles') . '

'; $output .= '

' . t('By creating responsive image styles you define the image styles that are being used to output images at certain breakpoints. On the Responsive image styles page, click Add responsive image style to create a new style. First chose a label and a breakpoint group and click Save. After that you can choose the image styles that will be used for each breakpoint. Image styles can be defined on the Image styles page that is provided by the Image module. Breakpoints are defined in the configuration files of the theme. See the help page of the Breakpoint module for more information.', array('!responsive_image_style' => \Drupal::url('entity.responsive_image_style.collection'), '!image_styles' => \Drupal::url('entity.image_style.collection'),'!image_help' => \Drupal::url('help.page', array('name' => 'image')), '!breakpoint_help' => \Drupal::url('help.page', array('name' => 'breakpoint')))) . '

'; $output .= '

' . t('Using responsive image styles in Image fields') . '

'; $output .= '

' . t('After defining responsive image styles, you can use them in the display settings for your Image fields, so that the site displays responsive images using the HTML5 picture tag. Open the Manage display page for the entity type (content type, taxonomy vocabulary, etc.) that the Image field is attached to. Choose the format Responsive image, click the Edit icon, and select one of the responsive image styles that you have created. For general information on how to manage fields and their display see the Field UI module help page. For background information about entities and fields see the Field module help page.', array('!field_ui' => (\Drupal::moduleHandler()->moduleExists('field_ui')) ? \Drupal::url('help.page', array('name' => 'field_ui')) : '#','!field_help' => \Drupal::url('help.page', array('name' => 'field')))) . '

'; $output .= '

' . t('A responsive image style associates an image style with each breakpoint defined by your theme.') . '

* tag. In other words, this function provides the attributes for each * tag in a tag. * * In a responsive image style, each breakpoint has an image style mapping for * each of its multipliers. An image style mapping can be either of two types: * 'sizes' (meaning it will output a tag with the 'sizes' attribute) or * 'image_style' (meaning it will output a tag based on the selected * image style for this breakpoint and multiplier). A responsive image style * can contain image style mappings of mixed types (both 'image_style' and * 'sizes'). For example: * @code * $responsive_img_style = ResponsiveImageStyle::create(array( * 'id' => 'style_one', * 'label' => 'Style One', * 'breakpoint_group' => 'responsive_image_test_module', * )); * $responsive_img_style->addImageStyleMapping('responsive_image_test_module.mobile', '1x', array( * 'image_mapping_type' => 'image_style', * 'image_mapping' => 'thumbnail', * )) * ->addImageStyleMapping('responsive_image_test_module.narrow', '1x', array( * 'image_mapping_type' => 'sizes', * 'image_mapping' => array( * 'sizes' => '(min-width: 700px) 700px, 100vw', * 'sizes_image_styles' => array( * 'large' => 'large', * 'medium' => 'medium', * ), * ), * )) * ->save(); * @endcode * The above responsive image style will result in a tag like this: * @code * * * * * * @endcode * * When all the images in the 'srcset' attribute of a tag have the same * MIME type, the source tag will get a 'mime-type' attribute as well. This way * we can gain some front-end performance because browsers can select which * image ( tag) to load based on the MIME types they support (which, for * instance, can be beneficial for browsers supporting WebP). * For example: * A tag can contain multiple images: * @code * * @endcode * In the above example we can add the 'mime-type' attribute ('image/jpeg') * since all images in the 'srcset' attribute of the tag have the same * MIME type. * If a tag were to look like this: * @code * * @endcode * We can't add the 'mime-type' attribute ('image/jpeg' vs 'image/webp'). So in * order to add the 'mime-type' attribute to the tag all images in the * 'srcset' attribute of the tag need to be of the same MIME type. This * way, a tag could look like this: * @code * * * * * * @endcode * This way a browser can decide which tag is preferred based on the * MIME type. In other words, the MIME types of all images in one tag * need to be the same in order to set the 'mime-type' attribute but not all * MIME types within the tag need to be the same. * * For image style mappings of the type 'sizes', a width descriptor is added to * each source. For example: * @code * * @endcode * The width descriptor here is "100w". This way the browser knows this image is * 100px wide without having to load it. According to the spec, a multiplier can * not be present if a width descriptor is. * For example: * Valid: * @code * * @endcode * Invalid: * @code * * @endcode * * Note: Since the specs do not allow width descriptors and multipliers combined * inside one 'srcset' attribute, we either have to use something like * @code * * @endcode * to support multipliers or * @code * * @endcode * to support the 'sizes' attribute. * * In theory people could add an image style mapping for the same breakpoint * (but different multiplier) so the array contains an entry for breakpointA.1x * and breakpointA.2x. If we would output those we will end up with something * like * @code * * @endcode * which is illegal. So the solution is to merge both arrays into one and * disregard the multiplier. Which, in this case, would output * @code * * @endcode * See http://www.w3.org/html/wg/drafts/html/master/embedded-content.html#image-candidate-string * for further information. * * @param \Drupal\Core\Image\ImageInterface $image * The image to build the tags for. * @param array $variables * An array with the following keys: * - responsive_image_style_id: The \Drupal\responsive_image\Entity\ResponsiveImageStyle * ID. * - width: The width of the image (if known). * - height: The height of the image (if known). * @param \Drupal\breakpoint\BreakpointInterface $breakpoint * The breakpoint for this source tag. * @param array $multipliers * An array with multipliers as keys and image style mappings as values. * * @return \Drupal\Core\Template\Attribute[] * An array of attributes for the source tag. */ function responsive_image_build_source_attributes(ImageInterface $image, array $variables, BreakpointInterface $breakpoint, array $multipliers) { $width = isset($variables['width']) && !empty($variables['width']) ? $variables['width'] : $image->getWidth(); $height = isset($variables['height']) && !empty($variables['height']) ? $variables['height'] : $image->getHeight(); $extension = pathinfo($image->getSource(), PATHINFO_EXTENSION); $sizes = array(); $srcset = array(); $derivative_mime_types = array(); foreach ($multipliers as $multiplier => $image_style_mapping) { switch ($image_style_mapping['image_mapping_type']) { // Create a tag with the 'sizes' attribute. case 'sizes': // Loop through the image styles for this breakpoint and multiplier. foreach ($image_style_mapping['image_mapping']['sizes_image_styles'] as $image_style_name) { // Get the dimensions. $dimensions = responsive_image_get_image_dimensions($image_style_name, array('width' => $width, 'height' => $height)); // Get MIME type. $derivative_mime_type = responsive_image_get_mime_type($image_style_name, $extension); $derivative_mime_types[] = $derivative_mime_type; // Add the image source with its width descriptor. When a width // descriptor is used in a srcset, we can't add a multiplier to // it. Because of this, the image styles for all multipliers of // this breakpoint should be merged into one srcset and the sizes // attribute should be merged as well. if (is_null($dimensions['width'])) { throw new \LogicException(SafeMarkup::format('Could not determine image width for @file using image style with ID: @image_style_name. This image style can not be used for a responsive image style mapping using the \'sizes\' attribute.', array('@file' => $image->getSource(), '@image_style_name' => $image_style_name))); } // Use the image width as key so we can sort the array later on. // Images within a srcset should be sorted from small to large, since // the first matching source will be used. $srcset[intval($dimensions['width'])] = file_create_url(_responsive_image_image_style_url($image_style_name, $image->getSource())) . ' ' . $dimensions['width'] . 'w'; $sizes = array_merge(explode(',', $image_style_mapping['image_mapping']['sizes']), $sizes); } break; case 'image_style': // Get MIME type. $derivative_mime_type = responsive_image_get_mime_type($image_style_mapping['image_mapping'], $extension); $derivative_mime_types[] = $derivative_mime_type; // Add the image source with its multiplier. Use the multiplier as key // so we can sort the array later on. Multipliers within a srcset should // be sorted from small to large, since the first matching source will // be used. We multiply it by 100 so multipliers with up to two decimals // can be used. $srcset[intval(Unicode::substr($multiplier, 0, -1) * 100)] = file_create_url(_responsive_image_image_style_url($image_style_mapping['image_mapping'], $image->getSource())) . ' ' . $multiplier; break; } } // Sort the srcset from small to large image width or multiplier. ksort($srcset); $source_attributes = new \Drupal\Core\Template\Attribute(array( 'srcset' => implode(', ', array_unique($srcset)), )); $media_query = trim($breakpoint->getMediaQuery()); if (!empty($media_query)) { $source_attributes->setAttribute('media', $media_query); } if (count(array_unique($derivative_mime_types)) == 1) { $source_attributes->setAttribute('type', $derivative_mime_types[0]); } if (!empty($sizes)) { $source_attributes->setAttribute('sizes', implode(',', array_unique($sizes))); } return $source_attributes; } /** * Determines the dimensions of an image. * * @param string $image_style_name * The name of the style to be used to alter the original image. * @param array $dimensions * An associative array containing: * - width: The width of the source image (if known). * - height: The height of the source image (if known). * * @return array * Dimensions to be modified - an array with components width and height, in * pixels. */ function responsive_image_get_image_dimensions($image_style_name, array $dimensions) { // Determine the dimensions of the styled image. if ($image_style_name == RESPONSIVE_IMAGE_EMPTY_IMAGE) { $dimensions = array( 'width' => 1, 'height' => 1, ); } else { $entity = ImageStyle::load($image_style_name); if ($entity instanceof Drupal\image\Entity\ImageStyle) { $entity->transformDimensions($dimensions); } } return $dimensions; } /** * Determines the MIME type of an image. * * @param string $image_style_name * The image style that will be applied to the image. * @param string $extension * The original extension of the image (without the leading dot). * * @return string * The MIME type of the image after the image style is applied. */ function responsive_image_get_mime_type($image_style_name, $extension) { if ($image_style_name == RESPONSIVE_IMAGE_EMPTY_IMAGE) { return 'image/gif'; } // The MIME type guesser needs a full path, not just an extension, but the // file doesn't have to exist. $fake_path = 'responsive_image.' . ImageStyle::load($image_style_name)->getDerivativeExtension($extension); return Drupal::service('file.mime_type.guesser.extension')->guess($fake_path); } /** * Wrapper around image_style_url() so we can return an empty image. */ function _responsive_image_image_style_url($style_name, $path) { if ($style_name == RESPONSIVE_IMAGE_EMPTY_IMAGE) { // The smallest data URI for a 1px square transparent GIF image. // http://probablyprogramming.com/2009/03/15/the-tiniest-gif-ever return 'data:image/gif;base64,R0lGODlhAQABAIABAP///wAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=='; } $entity = ImageStyle::load($style_name); if ($entity instanceof Drupal\image\Entity\ImageStyle) { return $entity->buildUrl($path); } return file_create_url($path); }