Plugin SDK > Customize record presentation

Customize record presentation

When viewing a collection of items, the records will normally show their title and possibly an image preview (as defined in the model's presentation settings). In this example, the record previews come from the record's Name field:

A product listing in Compact view, using the Name field as the title

But sometimes you may want more advanced control over the presentation of your collections. For example, you might want to make the title dynamically change based on another field in the record or an external API query.

Basic Example: Data from another field

Maybe you want to show an emoji next to the product name based on its product type:

The same product listing, now with an emoji next to each title

This change is purely cosmetic & superficial, affecting only what your editors see in the collection. It does NOT change the actual data in the record, only its presentation inside the DatoCMS UI.

How does it work? We used the buildItemPresentationInfo hook:

1
import {type BuildItemPresentationInfoCtx, connect, Item} from "datocms-plugin-sdk";
2

3
// A schema for our basic example
4
type ProductRecord = Item & {
5
  attributes: {
6
    name: 'string'
7
    product_type?: 'apple' | 'orange'
8
  }
9
}
10

11
// This checks to make sure an item is a product based on its API key, and if it is, assert that it is a ProductRecord
12
function isProductRecord(item: Item, ctx: BuildItemPresentationInfoCtx): item is ProductRecord {
13
  return ctx.itemTypes[item.relationships.item_type.data.id]?.attributes.api_key === 'product';
14
}
15

16
connect({
17
  async buildItemPresentationInfo(item: Item, ctx: BuildItemPresentationInfoCtx) {
18

19
    // We only want to override records in the `product` model
20
    if (!isProductRecord(item, ctx)) {
21
      return undefined; // Return undefined to let the record use its default values
22
    }
23

24
    // Get the record fields
25
    const {attributes: {product_type, name}} = item
26

27
    const fruitEmoji = {
28
      'apple': '🍎',
29
      'orange': '🍊',
30
      'unknown': '❓'
31
    }
32

33
    return {
34
      title: `${product_type ? fruitEmoji[product_type] : fruitEmoji['unknown']} ${name}`,
35
    }
36
  },
37
});

This level of flexibility empowers you to create a unique and tailored user experience that aligns with your goals.

The buildItemPresentationInfo hook can be used in numerous ways. For example, you can:

Combine multiple fields to present a record
Generate a preview image on the fly
Perform asynchronous API requests to third parties to compose the presentation

These are just a few examples of what you can do with the buildItemPresentationInfo hook. The possibilities are limitless, and you can use this hook to create the exact presentation you need.

The buildItemPresentationInfo hook is called every time a record needs to be presented, and it can return an object with title and/or imageUrl attributes, or undefined, if the plugin does not want to interfere with the default presentation at all.

imageUrl can also be a Data URL

While the imageUrl attribute normally is a normal URL starting with https://, you can also pass a Data URL. Data URLs can be useful to generate an image on-the-fly in JavaScript (for example, using canvases).

Advanced Example: Data from an async fetch

Suppose that one of the models in a DatoCMS project is used to represent products in a ecommerce frontend, and that each product record in DatoCMS is linked to a particular Shopify product via its handle.

Shopify holds information like inventory availability, prices and variant images. We don't want to replicate the same information in DatoCMS, but it would be nice to show them inside the DatoCMS interface.

Since the buildItemPresentationInfo hook can be an async function, we can make a fetch call to the Shopify Storefront API (or any other API) and use its response in our collection display.

We'll modify our previous example to show use the result of this fetch instead, based on a new field shopify_product_handle (which holds an external ID) and a fake function fetchShopifyProduct() (simulating an external fetch):

1
// Updated schema
2
type ProductRecord = Item & {
3
  attributes: {
4
    name: 'string'
5
    shopify_product_handle: string // A new required field
6
    // product_type?: 'apple' | 'orange' // No longer needed in the modified example
7
  }
8
}
9

10
// Updated hook
11
connect({
12
  async buildItemPresentationInfo(item: Item, ctx: BuildItemPresentationInfoCtx) {
13

14
    // Same function as before
15
    if (!isProductRecord(item, ctx)) {
16
      return undefined;
17
    }
18

19
    // Get the new field
20
    const {attributes: {name, shopify_product_handle}} = item
21

22
    // Just an example. In a real use case this would be an awaited fetch.
23
    const shopifyData = await fetchShopifyProduct(shopify_product_handle);
24

25
    const { imageUrl, availableForSale } = shopifyData;
26

27
    return {
28
      title: `${name} (${availableForSale ? '🛍️' : '🚫'})`,
29
      imageUrl,
30
    }
31
  },
32
})

The above is a simplified example using a fake fetch function. In a real project, to perform the actual API call to Shopify, we would need to implement a real fetch function using a real API token and the Shopify store domain. Both can be specified by the final user by adding some settings to the plugin.

A more realistic fetchShopifyProduct function might be something like this:

1
import { Plugin } from "datocms-plugin-sdk";
2

3
type PluginParameters = {
4
  shopifyDomain: string;
5
  shopifyAccessToken: string;
6
}
7

8
async function fetchShopifyProduct(handle: string, plugin: Plugin) {
9
  const parameters = plugin.attributes.parameters as PluginParameters;
10

11
  const res = await fetch(
12
    `https://${parameters.shopifyDomain}.myshopify.com/api/graphql`,
13
    {
14
      method: 'POST',
15
      headers: {
16
        'Content-Type': 'application/json',
17
        'X-Shopify-Storefront-Access-Token': `${parameters.shopifyAccessToken}`,
18
      },
19
      body: JSON.stringify({
20
        query: `query getProduct($handle: String!) {
21
          product: productByHandle(handle: $handle) {
22
            title
23
            availableForSale
24
            images(first: 1) {
25
              edges {
26
                node {
27
                  src: transformedSrc(crop: CENTER, maxWidth: 200, maxHeight: 200)
28
                }
29
              }
30
            }
31
          }
32
        }`,
33
        variables: { handle },
34
      }),
35
    },
36
  );
37

38
  const body = await res.json();
39

40
  return {
41
    title: body.data.product.title,
42
    availableForSale: body.data.product.availableForSale,
43
    imageUrl: body.data.product.images.edges[0].node.src,
44
  };
45
}

`buildItemPresentationInfo(item: Item, ctx)`

Use this function to customize the presentation of a record in records collections and "Single link" or "Multiple links" field.

Return value

The function must return: MaybePromise<ItemPresentationInfo | undefined>.

Context object

The following properties and methods are available in the ctx argument:

Properties and methods available in every hook

Every hook available in the Plugin SDK shares the same minumum set of properties and methods.

Authentication properties

Information about the current user using the CMS.

ctx.currentUser: User | SsoUser | Account | Organization The current DatoCMS user. It can either be the owner or one of the collaborators (regular or SSO).

The current DatoCMS user. It can either be the owner or one of the collaborators (regular or SSO).