Skip to content

Latest commit

 

History

History
150 lines (110 loc) · 7.46 KB

faq.md

File metadata and controls

150 lines (110 loc) · 7.46 KB
Raw

FAQ

Why is my image not displaying?

Timmy silently fails (it returns false) when an image can’t be found. You might want to check with {{ dump(yourimage) }} if you really try to use one of Timmy’s functions on your image.

How does Timmy handle SVG images?

Timmy will always try to return the image src for an SVG image, without any responsive markup (even if you call it with a function that normally returns responsive markup, like get_timber_image_responsive()).

How does Timmy handle GIF images?

Timber can resize GIF images when you have Imagick installed. So GIF images behave the same way than normal images. However, resizing GIF images takes quite some time. That’s why Timmy tries to reduce the amount of sizes that have to be generated.

When a GIF is uploaded to the backend, it will only be resized to the thumbnail size defined in your image configuration. GIF images in the Media Library will be loaded in a smaller size, because this makes the Media Grid load faster. All other image size are ignored when uploading an image. GIF images are still resized on the fly.

How can I better control the markup for SVG and GIF images?

If you want more control over the markup for SVG or GIF images, you can catch them through the mime type:

{# Assuming that image is an instance of Timber\Image #}
{% if image.post_mime_type == 'image/svg+xml' %}
    <img class="img-svg" src="{{ image.src }}" alt="">
{% elseif image.post_mime_type == 'image/gif'}
    <img class="img-gif" src="{{ image.src }}" alt="">
{% else %}
    {# Default for images #}
    <img{{ image|get_timber_image_responsive('your-size') }}>
{% endif %}

How can I make the full size unavailable when I insert an image into the WordPress Editor?

Timmy uses the filter image_size_names_choose with a standard priority of 10 to return the image sizes configured with Timmy and additionally adds the full size of an image. Add the following filter to your theme functions to remove the full size again.

add_filter( 'image_size_names_choose', function( $sizes ) {
    unset( $sizes['full'] );
    return $sizes;
}, 11 );

How does it work with the srcset and sizes parameters?

The sizes and srcset attribute tells the browser which images sizes are available and let’s the browser choose which image size to display based on the current viewport size, caching settings etc.

This image by Harry Roberts might help to explain/remember what it means:

Why is my backend unresponsive?

With Timmy’s logic, when an image size is changed in the configuration, it can trigger an on-the-fly regeneration of an image. This can lead to performance problems, because resizing an image takes quite some time. Timmy is optimized to be performant in the backend and tries to keep resizes to the minimum.

Changing the image size of the thumbnail size will always trigger a resize. When you do this, or if you see your Media takes a very long time loading images, or doesn’t load them at all, it might be a good idea to run Regenerate Thumbnails.

Why doesn’t Yoast generate OG image markup?

Yoast SEO tries to load the following image sizes for the OG image markup: full, large, medium_large. Yoast might not generate an image if the image size is not defined in the attachment metadata in the database. Since version 0.14.0, this should not be a problem with Timmy.

How can I control the image size generated by Yoast?

To better support Yoast, you can define your own image size that should be used for OG images. Here’s an example that adds an og-image size.

/**
 * Optimize default Yoast SEO image selection.
 *
 * Yoast SEO uses the `wpseo_image_sizes` filter to loop through an array of potential image
 * sizes it can use to generate an OG image. We remove the 'full' image size and add an
 * 'og-image' size at the beginning.
 *
 * The 'og-image' size is defined with a width of 1200 and height of 630, which is quite a good
 * size for social media sharing.
 *
 * @param array $sizes Image size names.
 *
 * @return array
 */
add_filter( 'wpseo_image_sizes', function filter_image_sizes( $sizes ) {
    // Remove 'full' image size.
    $sizes = array_filter( $sizes, function( $size ) {
        return 'full' !== $size;
    } );

    // Prepend 'og-image'.
    array_unshift( $sizes, 'og-image' );

    return $sizes;
} );

/**
 * Add an image size that can be used for OG images.
 *
 * 1200 × 630 is an image format that is used by ~50% of all websites as the OG image format.
 *
 * @link https://iamturns.com/open-graph-image-size/
 *
 * @param array $sizes
 *
 * @return array
 */
add_filter( 'timmy/sizes', function add_og_image_size( $sizes ) {
    return array_merge( $sizes, [
        'og-image'          => [
            'resize'     => [ 1200, 630 ],
            'post_types' => [ 'all' ],
        ],
    ] );
} );

Can I convert an existing project with WordPress images to Timmy?

Yes, you can. You can follow the installation guide and replace all of your existing image output functions with Timmy’s functions.

The final step would be to regenerate images so that you end up with only the images files you need. But you need to use Force Regenerate Thumbnails to delete all images that were generated by WordPress.

How does Timmy handle scaled images?

Scaled images were introduced in WordPress 5.3. Images above 2560px will be scaled down to a smaller version for the full size of an image. This version will include -scaled in its filename.

Timmy will return the scaled version of an image when the full image size is requested. You can always get the original size of an image when using original instead of full as the size.

<img src="{{ image|get_timber_image_src('original') }}">

If you want to disable scaled images, you’ll have to use the big_image_size_threshold filter:

add_filter( 'big_image_size_threshold', '__return_false' );