feat: Add img_class argument for get_timber_picture_responsive() (#84)

* preserve the class attribute when generating the JPG fallback img when rendering a picture * feat: Add img_class argument to set CSS class for fallback image * docs: Add documentation for get_picture_image_responsive() * tests: Add a test --------- Co-authored-by: Robin Schülein <robins@animalequality.de>
mindkomm · Aug 27, 2024 · efcf332 · efcf332
1 parent f45456e
commit efcf332
Show file tree

Hide file tree

Showing 4 changed files with 86 additions and 0 deletions.
diff --git a/docs/functions.md b/docs/functions.md
@@ -12,6 +12,7 @@ You can use the following functions to get your images into your template:
 
 ## Responsive images
 
+* [get_timber_picture_responsive()](#get_timber_picture_responsive) – Returns the picture markup used for modern image formats using a fallback source.
 * [get_timber_image_responsive()](#get_timber_image_responsive) – Returns the srcset, size and alt attributes for an image.
 * [get_timber_image_responsive_src()](#get_timber_image_responsive_src) – Returns the srcset and sizes for an image. This is practically the same as *get_timber_image_responsive*, just without the alt tag.
 * [get_timber_image_responsive_acf()](#get_timber_image_responsive_acf) – Takes the field name of an ACF image as the input and returns the same output as *get_timber_image_responsive()*.
@@ -129,6 +130,55 @@ Returns the image height for an image size. If you use the [lazy loading functio
 
 ---
 
+## get_timber_picture_responsive
+
+`get_timber_picture_responsive( int|Timber\Image $timber_image, string $size, array $args = [] )`
+
+Gets the picture markup used for modern image formats using a fallback source.
+
+### Usage in WordPress templates
+
+```php
+<picture>
+    <?php echo get_timber_picture_responsive( get_post_thumbnail_id(), 'custom-6' ); ?>
+</picture>
+```
+
+### Usage in Twig
+
+```twig
+<picture>
+    {{ post.thumbnail|get_timber_picture_responsive('custom-6') }}
+</picture>
+```
+
+### img_class
+
+If you want to define the CSS class for the fallback `<img>`, you can use the `img_class` parameter.
+
+**PHP**
+
+```php
+
+<picture>
+    <?php echo get_timber_picture_responsive( get_post_thumbnail_id(), 'custom-6', [
+        'img_class' => 'the-class',
+    ] ); ?>
+</picture>
+```
+
+**Twig**
+
+```twig
+<picture>
+    {{ post.thumbnail|get_timber_picture_responsive('custom-6', {
+        img_class: 'the-class',
+    }) }}
+</picture>
+```
+
+---
+
 ## get_timber_image_responsive
 
 `get_timber_image_responsive( int $post_id|\Timber\Image $timber_image, string|array $size )`

diff --git a/docs/picture.md b/docs/picture.md
@@ -26,6 +26,16 @@ You will use a `<picture>` element instead of an `<img>`
 </picture>
 ```
 
+If you want to add a CSS class to the fallback `<img>`, then you can use the `img_class` parameter:
+
+```twig
+<picture>
+    {{ post.thumbnail|get_timber_picture_responsive('webp-picture', {
+        img_class: 'the-class'
+    }) }}
+</picture>
+```
+
 ### Art directed picture with fallbacks
 
 To be implemented …
diff --git a/lib/Image.php b/lib/Image.php
@@ -336,6 +336,7 @@ public function picture_fallback_image( $args = [] ) {
 		 */
 		$default_args = [
 			'loading' => 'lazy',
+			'img_class' => '',
 		];
 
 		$args = wp_parse_args( $args, $default_args );
@@ -348,6 +349,10 @@ public function picture_fallback_image( $args = [] ) {
 			'loading' => $this->loading( $args['loading'] ),
 		];
 
+		if (!empty($args['img_class'])) {
+			$fallback_attributes['class'] = $args['img_class'];
+		}
+
 		$fallback_attributes = $this->add_data_attributes( $fallback_attributes, $args );
 
 		return '<img' . Helper::get_attribute_html( $fallback_attributes ) . '>';

diff --git a/tests/test-picture.php b/tests/test-picture.php
@@ -85,4 +85,25 @@ public function test_picture_with_lazy_attributes() {
 
 		$this->assertEquals( $expected, $result );
 	}
+
+	/**
+	 * @since 2.1.0
+	 * @return void
+	 */
+	public function test_picture_img_class() {
+		$alt_text   = 'Burrito Wrap';
+		$attachment = $this->create_image( [
+			'alt'         => $alt_text,
+			'description' => 'Burritolino',
+		] );
+		$result = get_timber_picture_responsive( $attachment, 'picture', ['img_class' => 'the-class'] );
+
+		$expected = sprintf(
+			'<source srcset="%1$s/test-560x0-c-default.jpg 560w, %1$s/test-1400x0-c-default.jpg 1400w" sizes="100vw">%2$s<img src="%1$s/test-1400x0-c-default.jpg" width="1400" height="933" alt="Burrito Wrap" loading="lazy" class="the-class">',
+			$this->get_upload_url(),
+			PHP_EOL
+		);
+
+		$this->assertEquals( $expected, $result );
+	}
 }