legrisch/statamic-graphql-thumbnails

A Statamic CMS GraphQL Addon that provides a convenient thumbnail field on all asset fields.

v0.5.0 2021-11-15 10:14 UTC

Requires

• php: ^7.3 || ^8.0
• statamic/cms: ^3.1

MIT

• Grischa Erbe

README

This Statamic GraphQL addon provides a thumbnail field on all AssetInterface fields. Either provide the argument name to query by predefined formats or use Just-In-Time thumbnail generation and provide width, height or fit.

Features

• Predefined thumbnail Formats: Query by name
• Just-In-Time thumbnail: Query by width, height or fit
• Control Panel UI to define formats and enable/disable JIT thumbnail generation
• Permissions for managing GraphQL thumbnail Settings

Installation

Run composer require legrisch/statamic-graphql-thumbnails

Setup

After installation, you must visit the control panel to define formats to query for or enable the JIT thumbnail generation.

Usage

Formats Usage

The thumbnail field requires an argument name which resolves to the name of one of your formats.

If formats are defined, you can also directly access a property srcset on the Asset.

asset {
  thumbnail(name: "small")
  srcset
}

yields

"asset": {
  "thumbnail": "http://absolute.url/to/thumbnail-small.jpg",
  "srcset": "http://absolute.url/to/thumbnail-small.jpg 500w, http://absolute.url/to/thumbnail-medium.jpg 1000w",
}

JIT Usage

The thumbnail field requires an argument width or height with an integer. Additionally you may specify the parameter fit. The possible values are: contain, max, fill, stretch, crop, crop_focal with the default being crop_focal.

asset {
  thumbnail(width: 100)
}

yields

"asset": {
  "thumbnail": "http://absolute.url/to/thumbnail-with-100px-width.jpg"
}

Full Examples

Query single thumbnail

query MyQuery {
  entries(collection: "pages") {
    data {
      ... on Entry_Pages_Pages {
        image {
          id
          thumbnail(width: 200)
        }
      }
    }
  }
}

yields

{
  "data": {
    "entries": {
      "data": [
        {
          "image": {
            "id": "assets::20210409232458.jpg",
            "thumbnail": "http://absolute.url/to/thumbnail.jpg"
          }
        }
      ]
    }
  }
}

Query multiple thumbnails

Use GraphQL aliases to query multiple thumbnails:

query MyQuery {
  entries(collection: "pages") {
    data {
      ... on Entry_Pages_Pages {
        image {
          id
          thumbnailSmall: thumbnail(width: 100)
          thumbnailMedium: thumbnail(width: 250)
          thumbnailLarge: thumbnail(width: 500)
          thumbnailSquare: thumbnail(width: 500, height: 200, fit: "crop")
        }
      }
    }
  }
}

yields

{
  "data": {
    "entries": {
      "data": [
        {
          "image": {
            "id": "assets::20210409232458.jpg",
            "thumbnailSmall": "http://absolute.url/to/small/thumbnail.jpg",
            "thumbnailMedium": "http://absolute.url/to/medium/thumbnail.jpg",
            "thumbnailLarge": "http://absolute.url/to/large/thumbnail.jpg",
            "thumbnailSquare": "http://absolute.url/to/square/thumbnail.jpg"
          }
        }
      ]
    }
  }
}

License

This project is licensed under the MIT License.