Clusters

A cluster is a parent metaobject that holds a list of child metaobjects. Sections connect to clusters through dynamic source in the theme customizer — wire a section’s metaobject picker to a product or collection metafield, and the right content shows up automatically per resource.

This is the core content pattern in the Nama theme. Instead of manually configuring every section on every product page, you create one cluster entry and connect it. The section renders from the cluster when data exists, falls back to manual theme blocks when it doesn’t, and auto-hides on PDP/collection pages when no metaobject is connected.

---

How clusters work

1. Define the data

A parent metaobject (e.g. faq_group) holds a list.metaobject_reference field pointing to child entries (e.g. faq_item). You create and populate these in Content > Metaobjects in the Shopify admin.

2. Connect via metafield

A product or collection metafield (e.g. nama.product_faqs) references the parent metaobject. You set this on individual products in the admin.

3. Wire dynamic source

In the theme customizer, the section has a metaobject or metaobject_list setting. Use the “Connect dynamic source” button to wire it to the metafield. The section automatically loads the correct cluster for each product/collection.

4. Section renders or hides

The section checks if the cluster has data:

{% if cluster != blank and cluster.child_field.value.size > 0 %}
  {%- assign has_metaobject_items = true -%}
{% endif %}

• Has data: renders from the metaobject entries
• No data, has manual blocks: falls back to theme blocks ({% content_for 'blocks' %})
• No data, no blocks, on PDP/collection: auto-hides (no empty whitespace)

---

Auto-hide pattern

Sections on PDP and collection templates auto-hide when no cluster data is connected. The pattern:

{% liquid
  assign hide_section = false
  if template contains 'product'
    if has_metaobject_items == false
      assign hide_section = true
    endif
  endif
%}

{% unless hide_section %}
  {%- comment -%} Section markup here {%- endcomment -%}
{% endunless %}

Caution

section.blocks.size does NOT work reliably with theme blocks from the /blocks/ directory. For auto-hide checks, always test the metafield directly — never rely on section.blocks.size.

---

Cluster types

True clusters (parent → child list)

These have a dedicated parent metaobject that wraps a list of children.

Parent type	Child type	Metafield	Section	Fallback blocks?
faq_group	faq_item	nama.product_faqs, nama.collection_faqs	FAQs	Yes — faq-item blocks
slides	social_slide_item	nama.product_social_slides	Social Slider	Yes — social-slide blocks
product_accordion_cluster	product_accordion_item	nama.product_accordion_cluster	Accordion	Yes — accordion-item blocks
product_feature_section	product_feature_step	nama.product_feature_section	Feature Steps	Yes — step blocks
collection_editorial_set	collection_editorial_card	nama.collection_editorials	Collection Grid	No
collection_filter_set	collection_filter_group	nama.collection_filter_set	Collection Filters	Falls back to all collection.filters
system_block	system_block_accessory	nama.system_block	Total Kitchen	kitchen-tab blocks

Flat metaobject lists (no parent wrapper)

These use metaobject_list settings to reference children directly — no parent cluster wrapper.

Metaobject type	Metafield	Section	Fallback?
educator	nama.product_educators	Educators	Yes — educator-card blocks
text_image_split	nama.product_text_image_split	Text Image Split	Yes — static blocks

Config metaobjects (single, not a list)

These store configuration rather than a list of items.

Metaobject type	Metafield	Section	Purpose
featured_articles	nama.product_featured_recipes, nama.collection_featured_articles	Featured Recipes	Holds a blog tag + up to 4 article picks
photo_medley	custom.photo_medley	Photo Medley	Holds 3 images + title/description
product_featured_editorial	nama.product_featured_editorial	Featured Editorial	Holds media + copy for an editorial card

---

Setting type reference

Shopify setting type	When to use
"type": "metaobject"	Single metaobject reference — for cluster parents or flat config objects
"type": "metaobject_list"	Direct list of child metaobjects without a parent wrapper (e.g. educators)

Note

Use metaobject_list (not metaobject) for list.metaobject_reference metafields. The metaobject type only works with single metaobject_reference metafields.

---

Adding a new cluster

1. Define the child metaobject in Shopify admin (Content > Metaobjects) and in metaobject-definitions.yaml
2. Define the parent metaobject with a list.metaobject_reference field pointing to the child type
3. Add a product/collection metafield (e.g. nama.my_cluster) of type metaobject_reference pointing to the parent type — add to metaobject-definitions.yaml
4. Add a metaobject setting to your section schema with the parent type
5. Implement the Liquid pattern: read the setting, check for data, set has_metaobject_items, render from metaobject or fall back to blocks, auto-hide when empty on PDP
6. Document the cluster in this file and the metafield in Metafields