@imgix/contentful

A Contentful app that integrates with imgix's Image Manager. Browse for, select and insert image assets into your content quickly and easily. Simplify your content editing workflow within Contentful and empower your developers with imgix’s powerful image rendering and optimization service.

---

• Installation
• Configuration
  • Assign to Fields (Optional)
• Add to Content Model
• Browse and Select Images
• Query an Image
  • Transforming Images
• License

Installation

The app can be installed to your Contentful workspace via the marketplace.

If running locally, the app can be installed via npm:

npm install @imgix/contentful
npm run start

Configuration

Upon installation, configure the app using an API key generated via the imgix Dashboard. Ensure that the generated key has the following permissions: Sources and Image Manager Browse.

Following the instructions on the screen, enter in the API key and press Verify. If the key is valid, you will receive a notification that the key has been successfully verified. If verification fails, you will need to ensure that the key was entered correctly.

https://user-images.githubusercontent.com/15919091/136624478-84830210-585d-40a3-9aa0-8540b4e67d7f.mov

Assign to Fields (Optional)

The configuration page surfaces the option for users to select pre-existing content fields that are compatible with the imgix app. Note that the app is configured to integrate with JSON object fields only, therefore only fields of this type will be displayed. Users may prefer this method over selecting individual fields manually for each applicable content model.

https://user-images.githubusercontent.com/15919091/136625503-aa4dabd4-5a7b-4886-912e-f536f7e67ab3.mov

Add to Content Model

Of the many content types that users can choose from, imgix specifically integrates with the JSON object. Please note that if you are currently using a Media content type for images, you will need to create a new field of type JSON object to integrate the app with. Designate a field to use imgix on by navigating to that field’s Appearance tab and selecting the app. This step can be skipped if you already assigned the app directly to the desired field(s).

https://user-images.githubusercontent.com/15919091/136624966-717df2ec-f3fd-4e3c-aa0b-4ed1e7252e73.mov

Browse and Select Images

From any instance of a field using the imgix app, a modal can be opened to browse images by imgix source. First, select a desired source to browse images from. Using any of the pagination buttons, navigate each page of assets to choose from. After selecting an image, it can be inserted to the field via the Add image button. Additionally, there are options to replace an image, or clear a selection from the field altogether.

https://user-images.githubusercontent.com/15919091/136625073-6c109568-7b8b-490f-aa2f-4be12bbc2cb0.mov

Query an Image

Once the content is published, developers can query the src of the selected image, returned as a string, via the Contentful API. The example below demonstrates this using GraphQL, but this can be done independent of any specific tool.

query MyQuery {
  allContentfulArticle {
    nodes {
      avatar {
        src
      }
      bannerImage {
        src
      }
    }
  }
}

returns something similar to:

{
  "data": {
    "allContentfulArticle": {
      "nodes": [
        {
          "avatar": {
            "src": "https://fourbottle.imgix.net/heroes/pourover.jpg"
          },
          "bannerImage": {
            "src": "https://fourbottle.imgix.net/heroes/light-scatter.jpg"
          }
        }
      ]
    }
  },
  "extensions": {}
}

Transforming Images

Developers can leverage the power of imgix's rendering API downstream from where the image was selected in Contentful. We recommend piping the value of the src field of the image through to one of imgix's SDKs. The example below builds on the previous one by passing the image src through to @imgix/gatsby component:

import React from "react";
import { graphql } from "gatsby";
import { ImgixGatsbyImage } from "@imgix/gatsby";

export default function Page({ data }) {
  return (
    data.allContentfulArticle.nodes.map(({ node }) => (
        <ImgixGatsbyImage
          src={node.avatar.src}
          imgixParams={{
            auto: "format,compress",
            crop: "faces,edges",
          }}
          layout="constrained"
          width={350}
          aspectRatio={16 / 9}
          sizes="(min-width: 1024px) calc(30vw - 128px), (min-width: 768px) calc(50vw - 100px), calc(100vw - 70px)"
          alt="An imgix-served image from Contentful"
        />
    ))
  );
}

export const query = graphql`
query MyQuery {
  allContentfulArticle {
    nodes {
      avatar {
        src
      }
    }
  }
}
`;

License

Changelog

1.0.0 (2021-10-08)

Features

• Allow users to configure their app with an imgix API key
  • Add button to Verify user's key
  • Users can assign the imgix app to pre-existing JSON object fields at installation
• Modal from which users can select an imgix source to browse images from
• Pagination buttons for browsing multiple pages of assets
• Add image button saves the image src to the field value
• Replace button to replace an image
• Remove button to clear a selection