From 2b9e0847dbe8a6e73a524af332c8f19c289b9eaf Mon Sep 17 00:00:00 2001 From: Lukas Gaechter Date: Mon, 21 Feb 2022 17:24:12 +0100 Subject: [PATCH] Update documentation and changelog --- CHANGELOG.md | 6 ++- README.md | 3 ++ docs/api.md | 39 ++++++++++++++++ docs/extending-timmy.md | 49 ++++++++++++++++++++ docs/installation.md | 2 +- docs/picture.md | 99 +++++++++++++++++++++++++++++++++++++++++ lib/Timmy.php | 11 ++--- 7 files changed, 202 insertions(+), 7 deletions(-) create mode 100644 docs/api.md create mode 100644 docs/extending-timmy.md create mode 100644 docs/picture.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 97eb5eb..a1d405e 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/README.md b/README.md index 13e44ed..fc05ec9 100644 --- a/README.md +++ b/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) diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..43dd949 --- /dev/null +++ b/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 + + {{ image.picture_responsive }} + + {% else %} + + {% endif %} +{% endif % +``` \ No newline at end of file diff --git a/docs/extending-timmy.md b/docs/extending-timmy.md new file mode 100644 index 0000000..ec0e8c7 --- /dev/null +++ b/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 +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 + +``` diff --git a/docs/installation.md b/docs/installation.md index ca14337..205fe3b 100644 --- a/docs/installation.md +++ b/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](). (Timmy currently can’t be found in the official WordPress plugin directory. Maybe it will be soon.) diff --git a/docs/picture.md b/docs/picture.md new file mode 100644 index 0000000..826569f --- /dev/null +++ b/docs/picture.md @@ -0,0 +1,99 @@ +# Picture + +You will use a `` element instead of an `` + +- 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 `` is for serving differently-sized version of the *same image*.) + +## WebP + +### Simple responsive picture + +```html + + + + + Your alt text + +``` + +**Twig** + +```twig + + {{ post.thumbnail|get_timber_picture_responsive('webp-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 + + + + + + + + + + + +``` + +**Twig** + +```twig + + {{ get_timber_picture_sources('webp-picture', [ + { + media: '(min-width: 62em)' + srcset + } + ]) }} + +``` + +**Timmy config** + +```php +[ + 'webp-picture' => [ + 'type' => 'picture', + 'towebp' => true, + // This will be used + 'resize' => '', + 'sources' => [ + 'desktop' => [ + + ], + 'default' => [ + + ], + 'fallback' => [ + + ], + ], + ], +], +``` + diff --git a/lib/Timmy.php b/lib/Timmy.php index bac3637..efb4633 100644 --- a/lib/Timmy.php +++ b/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.