Plugin SDK > Customize record presentation

Customize record presentation

While the DatoCMS interface does offer basic controls for specifying which fields of a model should be used as the record title and "image preview" within the interface, you may encounter scenarios where you need more advanced control over the presentation of your content.

To address this, you can use the buildItemPresentationInfo hook, which enables you to customize the presentation of your records according to your specific needs. 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 imageUrl attributes, or undefined, if the plugin does not want to interfere with the default presentation:

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

connect({
  async buildItemPresentationInfo(item: Item, ctx: BuildItemPresentationInfoCtx) {
    return {
      title: '',
      imageUrl: '',
    }
  },
});

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).

A basic example

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 easily make a fetch call to the Shopify Storefront API and use this information:

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

3
type ProductRecord = Item & {
4
  attributes: {
5
    shopify_product_handle: string;
6
  }
7
}
8

9
function isProductRecord(item: Item, ctx: OnBootCtx): item is ProductRecord {
10
  return ctx.itemTypes[item.relationships.item_type.data.id]?.attributes.api_key === 'product';
11
}
12

13
connect({
14
  async buildItemPresentationInfo(item: Item, ctx: OnBootCtx) {
15
    // we only want to tweak the presentation on product records
16
    if (!isProductRecord(item, ctx)) {
17
      return undefined;
18
    }
19

20
    const { title, imageUrl, availableForSale } = await fetchShopifyProduct(
21
      item.attributes.shopify_product_handle,
22
      ctx.plugin,
23
    );
24

25
    return {
26
      title: `${title} (${availableForSale ? '🛍️' : '🚫'})`,
27
      imageUrl,
28
    }
29
  },
30
});

To perform the actual API call to Shopify, we need an API token and the Shopify store domain. Both can be specified by the final user by adding some settings to the plugin.

The final fetchShopifyProduct function:

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:

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

Information about the current user using the CMS.

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