Relationships

Typically, most banners and structures can be created in a single request, where all necessary data for the parent and its children are provided. However, if this isn't the case, children must be created separately and then referenced during the parent's creation.

When children are nested within the parent, updating them and the parent must be done separately.

Upon creation, children are automatically linked to their parent. Notably, directly linked children have a 1:1 connection with their parents, while parents have a 1:n connection with their children. Consequently, deleting a parent will cascade down to its children. However, banners that only reference their children are exempt from this behavior as they are only loosely connected.

{
   "banners":[
      {
         "__typename":"Textblock",
         "id":"319b9671-fbb8-4e6f-93db-ecb20779cebd",
         "published": true
      }
   ],
    "basis":"350px"
}

This example shows a grid wrapper that uses a loose connection to its children. Therefor the children have to be created forehand and then are just referenced in the parents creation.

But loosely connections can't only occur in banners, referencing other banners. Sometimes also products are in loosely connected in a similiar fashion to a banner, as the banner only utilizes the id of a product, which is then fetched on-demand for the banner.

{
    "sliderItems":[
          {
             "__typename":"Product",
             "gid":"gid://shopify/Product/1234567890"
          }
    ]
}

{
   "textItems":[
      {
         "requiredDisplayTitle": { ... },
         "displayDescription": { ... },
         "icon": { ... }
      }
   ]
}

This shows a statement row banner, which is strongly connected to it's children statement row items. The items are created upon creation of the parent and will deleted when the parent gets deleted.

Referenced banner DTOs

Parent banners that have children banners that are only loosely connected, will always utilize one of these two reference DTOs:

1. The variant BannerReferenceDto allows all banners to be referenced. This includes a _typename to identify the correct type of the banner, the id of the desired banner and its published state, since only banners that have been published by an admin will be sent out to the frontend on request.

class BannerReferenceDto {
  @IsEnum(BannerTypename)
  __typename: BannerTypename;
 
  @IsString()
  id: string;
 
  /** Controls the published property and whether referenced banners are live. */
  @IsBoolean()
  @IsOptional()
  published?: boolean | null;
}

2. The second variant is a bit more restrictive, as it only allows one specific banner type to be referenced.

class SpecificBannerReferenceDto<T extends keyof typeof BannerTypename> {
  @IsEnum(BannerTypename)
  __typename: T;
 
  @IsString()
  id: string;
 
  /** Controls the published property and whether referenced banners are live. */
  @IsBoolean()
  @IsOptional()
  published?: boolean | null;
}

BannerTypename enum

The enum for all currently supported banners to be referenced, is the following:

enum BannerTypename {
  AnnouncementBanner = 'AnnouncementBanner',
  FunnelBlockBanner = 'FunnelBlockBanner',
  ProductPreviewBlockBanner = 'ProductPreviewBlockBanner',
  SmallFunnelWrapperBanner = 'SmallFunnelWrapperBanner',
  StatementRowBanner = 'StatementRowBanner',
  UpsellBlockBanner = 'UpsellBlockBanner',
  TextBlock = 'TextBlock',
  ImageBlock = 'ImageBlock',
  ButtonBlock = 'ButtonBlock',
  GridWrapper = 'GridWrapper',
  CustomBlock = 'CustomBlock',
}

Note that only Banners are allowed as reference objects. Structures like a Header or Footer are not allowed as reference objects.