Banners & Content

The Banner & Inline Content Injection system allows non-engineering teams to inject promotional or informational banners into the PLP grid without code changes or theme redeploys.

Banners are managed through Shopify MetaObjects, providing merchant self-serve control with declarative configuration.

MetaObject Schema: `plp_banner`

Banners are defined using the plp_banner MetaObject type in Shopify.

Field	Type	Description
`name`	string	Internal identifier for the banner
`image_url`	string	Banner visual asset URL
`position`	integer	Grid or row index for placement
`collection_handle`	string / reference	Governing collection association
`whole_row`	boolean	Span behavior (full row vs single slot)

[!NOTE] MetaObjects are created and managed in Shopify. Users cannot edit MetaObjects directly in the Malachyte Portal. The Portal associates existing MetaObjects with collections.

When whole_row = false:

Occupies one product slot in the grid
Treated as a pseudo-product
Grid alignment remains unchanged
Useful for promotional cards that blend with products

When whole_row = true:

Spans entire grid width
Injected between product rows
Useful for campaign messaging, category headers, or promotional strips

Position Alignment

[!IMPORTANT] Positions reference the absolute dataset index of the collection, not the visible page index. This ensures consistent positioning regardless of pagination or infinite scroll state.

Position Examples

Position Value	Placement
`1`	Before the first product
`5`	After the fourth product
`13`	After the twelfth product

Creating Banners

Step 1: Create the MetaObject in Shopify

Navigate to Settings > Custom Data > MetaObjects in Shopify Admin
Create a new MetaObject using the plp_banner schema
Fill in the required fields:
- name — A recognizable internal identifier
- image_url — URL to your banner asset
- position — Where the banner should appear
- collection_handle — Which collection this banner belongs to
- whole_row — Whether to span the full grid width

Step 2: Associate in the Portal

Navigate to the PLP section in the Malachyte Portal
Select the target collection
View associated banners in the configuration page
Banners automatically appear based on their collection_handle value

Why MetaObjects?

Using Shopify MetaObjects for banner management provides several advantages:

Benefit	Description
Merchant self-serve	Marketing teams can create banners without developer involvement
No theme redeploys	Banner changes take effect without code deployments
Multiple formats	Support for various banner sizes and layouts
Scales across collections	One system works for all PLPs
Declarative configuration	Clear, structured data model

Frontend Integration

When returning a collection to the frontend, an API call joins MetaObjects and collections by ID so that banners can be rendered alongside products.

The rendering flow:

Fetch collection products with merchandising rules applied
Query associated plp_banner MetaObjects by collection_handle
Inject banners at their designated positions
Render the combined product + banner grid

Best Practices

Keep banners visually consistent with your product grid styling
Use high-quality images that scale well across devices
Consider mobile viewports — full-row banners should be responsive

Positioning Strategy

Early positions (1-5) for high-priority campaign content
Mid-grid positions for category storytelling
Strategic spacing — avoid clustering multiple banners together

Content Guidelines

Clear call-to-action if the banner is clickable
Seasonal relevance — update banners for campaigns and promotions
Performance tracking — use the Attribution module to measure banner effectiveness