Update documentation and changelog

CHANGELOG.md

@@ -10,7 +10,6 @@
 - Added `get_timber_image_alt()` function.
 - Added `get_timber_image_caption()` function.
 - Added `get_timber_image_description()` function.
-- Added `get_timber_image_loading()` function.
 - Added `get_timber_picture_responsive()` function.
 - Added `get_timber_picture_fallback_image()` function.
 - Added better support for SVG images.
@@ -21,6 +20,11 @@
 - Improved hints about [controlling image sizes for Yoast](https://github.com/mindkomm/timmy/blob/master/docs/faq.md#how-can-i-control-the-image-size-generated-by-yoast).
 - Removed deprecated `get_image_attr_html()`, `get_timber_image_attr()` and `get_acf_image_attr()` functions.
 
+### New API behind the scenes
+
+- Added a new `Timmy\Image` class that is used to generate the markup for an image. Most of the functionality that was in the `get_timber_*()` functions before now lives in that class.
+- Added a `Timmy\Timmy::get_image()` function to get a `Timmy\Image` in a way that allows developers to extend the `Timmy\Image` class.
+
 ### Breaking changes
 
 #### Changed how Timmy should be initialized.

README.md

@@ -29,6 +29,9 @@ alt="Your alt text"
 - [Responsive Content Images](./docs/responsive-content-images.md)
 - [Hooks (Filters)](./docs/hooks.md)
 - [Lazy Loading](./docs/lazy-loading.md)
+- [WebP images and Picture](./docs/picture.md)
+- [API](./docs/api.md)
+- [Extending Timmy](./docs/extending-timmy.md)
 - [Performance and Best Practices](./docs/best-practices.md)
 - [FAQ](./docs/faq.md)
 

docs/api.md

@@ -0,0 +1,39 @@
+# API
+
+Timmy started out with functions that returned markup. But this made it harder to access data that you might need before accessing an image. All [functions](https://github.com/mindkomm/timmy/blob/master/docs/functions.md) still work fine, but with version 1.0.0, there’s a new API.
+
+The new API works mostly with the `Timmy\Image` class. You can use it to get data about an image with a certain size and also generate the markup you need.
+
+First, to get a Timmy image, you can use `Timmy\Timmy::get_image()`.
+
+**PHP**
+
+```php
+<?php
+
+use Timmy\Timmy;
+
+$image = Timmy::get_image( $attachment_id, 'large' );
+```
+
+**Twig**
+
+```twig
+{% set image = get_timmy_image( attachment_id, 'large' ) %}
+```
+
+This function returns a `Timmy\Image` object if you pass an ID for an existing attachment and `null` if it’s not a valid attachment.
+
+As soon as you have that image, you can start interacting with it.
+
+```twig
+{% if image %}
+    {% if image.is_webp %}
+        <picture>
+            {{ image.picture_responsive }}
+        <picture>
+    {% else %}
+        <img {{ image.image_responsive }}>
+    {% endif %}
+{% endif %
+```

docs/extending-timmy.md

@@ -0,0 +1,49 @@
+# Extending Timmy
+
+When you work with the image class, you may find that you need functionality that doesn’t exist in the Image class. In that case, you can extend Timmy to use your own class that extends `Timmy\Image`.
+
+Here’s an example where we tell Timmy to use a custom TimmyImage class that we extend with an `aspect_class()` method that returns a CSS class we can use based on the aspect ratio of an image.
+
+**functions.php**
+
+```php
+add_filter( 'timmy/image/class', function( $class ) {
+    return TimmyImage::class;
+} );
+```
+
+**TimmyImage.php**
+
+```php
+<?php
+
+use Timmy\Image;
+
+/**
+ * Class TimmyImage
+ */
+class TimmyImage extends Image {
+	/**
+	 * Gets a CSS class based on the aspect ratio.
+	 *
+	 * This also works for SVG images.
+	 *
+	 * @return string|null
+	 */
+	public function aspect_class() {
+		if ( $this->is_squarish() ) {
+			return 'isSquare';
+		} elseif ( $this->is_landscape() ) {
+			return 'isLandscape';
+		}
+
+		return 'isPortrait';
+	}
+}
+```
+
+In Twig, you can then access the method through `image.aspect_class`:
+
+```twig
+<img class="{{ image.aspect_class }}" {# … #}>
+```

docs/installation.md

@@ -17,7 +17,7 @@ You can either install both Timmy and Timber as plugins or use Composer.
 
 ### Install as Plugin
 
-1. Install [Timber Library Plugin](https://wordpress.org/plugins/timber-library/). You don’t have to necessarily go full Timber with your theme. You can use Timber and Timmy to only handle your images in your theme.
+1. Install the [Timber Library plugin](https://wordpress.org/plugins/timber-library/). You don’t have to necessarily go full Timber with your theme. You can use Timber and Timmy to only handle your images in your theme.
 
 2. Then [download and install the latest version of Timmy](<https://github.com/MINDKomm/Timmy/releases/latest>). (Timmy currently can’t be found in the official WordPress plugin directory. Maybe it will be soon.)
 

docs/picture.md

@@ -0,0 +1,99 @@
+# Picture
+
+You will use a `<picture>` element instead of an `<img>`
+
+- If you want to use **modern image formats like WebP** and provide fallbacks for browsers that don’t support it yet.
+- If you want to use **art direction** and provide different images for differents screens. (Using `<img>` is for serving differently-sized version of the *same image*.)
+
+## WebP
+
+### Simple responsive picture
+
+```html
+<picture>
+    <source srcset="burrito-720x0-default.webp 720w, burrito-1200x0-default.webp 1200w" sizes="(min-width: 1200px) 1200px, 100vw" type="image/webp">
+    <source srcset="burrito-720x0-default.jpg 720w, burrito-1200x0-default.jpg 1200w" sizes="(min-width: 1200px) 1200px, 100vw">
+
+    <img src="burrito-1200x0-default.jpg" width="1200" height="600" alt="Your alt text">
+</picture>
+```
+
+**Twig**
+
+```twig
+<picture>
+    {{ post.thumbnail|get_timber_picture_responsive('webp-picture') }}
+</picture>
+```
+
+If you want to enable WebP conversion for all image sizes, you can add it to your image sizes with the `timmy/sizes` filter.
+
+```php
+add_filter( 'timmy/sizes', function( $sizes ) {
+	$sizes = array_map( function( $size ) {
+		if ( ! isset( $size['to_webp'] ) ) {
+			$size['to_webp'] = true;
+		}
+
+		return $size;
+	}, $sizes );
+
+	return $sizes;
+}, 50 );
+```
+
+### Art directed picture with fallbacks
+
+To be implemented …
+
+```html
+<picture>
+  <source media="(min-width: 56.25em)" srcset="large.webp" type="image/webp">
+  <source media="(min-width: 56.25em)" srcset="large.jpg">
+
+  <source media="(min-width: 37.5em)" srcset="medium.webp" type="image/webp">
+  <source media="(min-width: 37.5em)" srcset="medium.jpg">
+
+  <source srcset="small.webp" type="image/webp">
+  <source srcset="small.jpg">
+  <img src="fallback.jpg" alt="">
+</picture>
+```
+
+**Twig**
+
+```twig
+<picture>
+    {{ get_timber_picture_sources('webp-picture', [
+        {
+            media: '(min-width: 62em)'
+            srcset
+        }
+    ]) }}
+</picture>
+```
+
+**Timmy config**
+
+```php
+[
+    'webp-picture' => [
+        'type' => 'picture',
+        'towebp' => true,
+        // This will be used
+        'resize' => '',
+        'sources' => [
+            'desktop' => [
+
+            ],
+            'default' => [
+
+            ],
+            'fallback' => [
+
+            ],
+        ],
+    ],
+],
+```
+

lib/Timmy.php

@@ -757,14 +757,14 @@ public static function resize( $img_size, $file_src, $width, $height, $crop, $fo
 	}
 
 	public static function to_webp( $file_src, $size ) {
-			$args = [
-				'quality' => 100,
-				'force'   => false,
-			];
+		$args = [
+			'quality' => 100,
+			'force'   => false,
+		];
 
 		if ( isset( $size['webp'] ) && is_array( $size['webp'] ) ) {
 			$args = wp_parse_args( $size['webp'], $args );
-			}
+		}
 
 		return Timber\ImageHelper::img_to_webp( $file_src, $args['quality'], $args['force'] );
 	}
@@ -828,6 +828,7 @@ public static function should_convert_to_webp( $file_src, $img_size ) {
 	 * srcset, there can’t be a value like "image.jpg 0w". So we have to calculate the width based
 	 * on the values we have.
 	 *
+	 * @todo Deprecate this.
 	 * @since 0.9.3
 	 *
 	 * @param  int          $width        The value of the resize parameter for width.