Topic Explorer — Metaobjects setup

This theme section uses two Shopify Metaobject definitions:

• topic — an editorial grouping.
• topic_item — an individual entry inside a topic.

These are read server-side in Liquid (via shop.metaobjects.topic.values and the topic.items reference list) and progressively enhanced in the browser.

1) Shopify Admin setup (high level)

1. Go to Settings → Custom data → Metaobjects.
2. Create the two definitions below.
3. In each definition, enable Storefront access (so Liquid can read entries on the storefront).
4. Create entries for your topics and items.
5. In the theme editor, add the Topic explorer section and choose whether topics are sourced from:
   • All topics (reads all topic entries), or
   • Manual selection (add topic blocks and pick topics explicitly).

2) Definition: topic_item

Use this metaobject for an individual item that lives inside a topic.

Field key	Label (suggested)	Type	Required	Notes
title	Title	Single line text	Yes	Display name.
handle	Handle	(Entry handle)	Yes	Used for deep linking via ?item=….
card_image	Card image	File (image)	No	Used in the item list.
card_excerpt	Card excerpt	Single line text	No	Optional short summary.
detail_image	Detail image	File (image)	No	Preferred image for the drawer; falls back to card_image.
quick_facts	Quick facts	List of values (single line text)	No	Rendered as bullets.
detail_body	Detail body	Rich text	No	Main drawer body.
sources	Sources	Rich text	No	Optional sources block.

3) Definition: topic

Use this metaobject for a topic / grouping of items.

Field key	Label (suggested)	Type	Required	Notes
title	Title	Single line text	Yes	Topic heading.
handle	Handle	(Entry handle)	Yes	Used for deep linking via ?topic=….
hero_image	Hero image	File (image)	No	Optional topic hero.
intro	Intro	Rich text	No	Optional topic intro.
support_points	Support points	List of values (single line text)	No	Optional bullet list under the intro.
items	Items	List of metaobject references (topic_item)	Yes	The item ordering follows this list order.
sort_order	Sort order	Number (integer)	No	Not required by the section; can help editorial workflows.

4) Handles, ordering, and deep linking

• Topic handle appears in URLs as ?topic=<topic_handle>.
• Item handle appears in URLs as ?item=<item_handle>.
• Ordering for Prev/Next in the drawer is the DOM order of items in the active topic panel, which is the same as the items list order in the topic entry.

5) Troubleshooting

• Section shows "No topics found."

  • Confirm there are topic entries.
  • Confirm the definition has Storefront access enabled.
  • If using Manual selection, confirm you added topic blocks and picked topics.

• Drawer opens but content is blank

  • Check that the topic_item entry has a title and (optionally) detail_body.
  • Check that the topic's items list actually references topic_item entries.

• Deep links don't open the right item / topic

  • Verify the entry handle matches the topic / item query param.
  • Handles are case-sensitive in the browser URL state.

6) Example entry data

Example topic_item handle: citric-acid

Example topic handle: acids

Example deep link:

• https://yourstore.com/pages/topics?topic=acids&item=citric-acid