Dynamic sources
Dynamic sources allow merchants to connect input settings to data coming from resources such as products, collections, blogs, and pages as well as metafields and metaobjects.
Dynamic sources available to theme blocks
Anchor link to section titled "Dynamic sources available to theme blocks"Theme blocks are reusable blocks which are defined at the theme level and can be nested. The settings of theme blocks can be connected to data that come from the following:
Source | Description |
---|---|
Template | The resource that's associated to the template or page being rendered. |
Section | A resource input setting defined as part of the section schema, such as product setting and collection setting. |
Block | A resource input setting defined as part of any of the ancestor blocks, such as product setting and collection setting. |
Liquid | A resource drop passed to blocks explicitly in Liquid to the content_for tag. |
Accessing the closest resource
Anchor link to section titled "Accessing the closest resource"Theme blocks can access dynamic sources using access paths such as:
Theme blocks are reusable and can be nested across various sections and blocks. As a result, it isn't always possible to determine ahead of time where the data will come from. To address this issue, you can use the closest
access path to reference the nearest resource of a specified type.
The closest
access path provides a way to access the closest resource of a given type, regardless of whether it is coming from the template, parent section or any ancestor block.
In this example, the Image banner
section has a Product card
block with nested Media
, Title
and Price
blocks. They are connected to the closest product which currently resolves to the product setting of the Product card
which is set to Sunglasses
.
If the Sunglasses
product is removed from the Product card
, the nested blocks connected to the closest product are still pointing to the Product card
product setting, even when the setting is empty. Because no closest product is currently set, the nested blocks will display placeholders.
If the T-shirt
product is later selected in the Product card
block, its nested blocks will then display the new closest product: T-shirt
.
In other words, a setting connected to the closest product will automatically go up the chain of its ancestors to grab the attributes from the closest product found, in the following order:
- A product setting within the same block;
- A parent block product setting;
- The current section product setting;
- The current template’s product
Usage in theme block presets
Anchor link to section titled "Usage in theme block presets"You can connect settings to the closest resource of a specific type within their presets, which allows you to access the most relevant resource of any type (such as a product, collection or page).
You can configure theme block preset settings to reference the closest resource of a compatible resource type by using the following Liquid syntax: {{closest.<type>}}
.
When a nested theme block is connected the closest resource of a specified type, the order of resolution for the closest resource is based on the following rules:
- The closest Liquid context setter of the specified type
- The closest ancestor block setting of the specified type
- The section resource settings of the specified type
- The template resource if it's of the specified type
The following table shows all possible configuration values for each resource type:
Resource type | Configuration value |
---|---|
Product | {{ closest.product }} |
Collection | {{ closest.collection }} |
Article | {{ closest.article }} |
Blog | {{ closest.blog }} |
Page | {{ closest.page }} |
Metaobject | {{ closest.metaobject[<definition_type>] }} |
The following examples shows a price block with a product setting. The price block’s product setting is set to closest.product
. The closest key means it will be able to access the closest product resource from the closest ancestor possible.
You can configure theme block settings in presets to point to the closest ancestor of a specific resource type, without needing to specify where. After a resource is connected at an ancestor level, children blocks can access the available resource properties using dynamic sources from their settings.
In the following example, the text, price and product media blocks access the closest product resource using {{ closest.product }}:
After the preset has been inserted into a section or block, then the data is stored in JSON as follows:
Passing resources down in Liquid using closest
Anchor link to section titled "Passing resources down in Liquid using closest"Theme block settings can access the closest resources set in Liquid using the content_for
Liquid tag directly. A resource can be passed directly to the content_for
tag using a parameter that specifies the type of the resource.
The table below shows which resource types can be passed to the content_for
tag in Liquid:
Resource type | Syntax |
---|---|
Product | {% content_for "blocks", closest.product: <Product Drop> %} |
Collection | {% content_for "blocks", closest.collection: <Collection Drop> %} |
Article | {% content_for "blocks", closest.article: <ArticleDrop> %} |
Blog | {% content_for "blocks", closest.blog: <BlogDrop> %} |
Page | {% content_for "blocks", closest.page: <PageDrop> %} |
Metaobject | {% content_for "blocks", closest.metaobject.<definition_type>: <MetaobjectDrop> %} |
The {% content_for "block" %}
tag, which is used to render static blocks, also supports passing context using the same syntax for all of the resource types above.
A common use-case for passing resources down to nested blocks in Liquid is when looping over the products in a collection. We need to pass down the current product that is being iterated over in the collection to the content_for
tag so that nested blocks can access the product resource using {{ closest.product }}
.
In this example, we are rendering a static block named product-card
while looping over the products in the collection setting of the Product grid
block. This will allow the Product card
block, and all of its nested blocks to access the current product for that card via {{ closest.product }}
.
Using dynamic sources in the theme editor
Anchor link to section titled "Using dynamic sources in the theme editor"Merchants can connect theme block settings to the closest resource of a particular type using the dynamic sources picker in the theme editor. A merchant might have access to more than one type of closest resource.
In this example, the merchant is editing a text block on a product template. The merchant is connecting a text setting for the text block to a dynamic source. The merchant can pick from different resource contexts: the closest product, the product set at the section or the product set at the template.
Once a closest resource context is selected, the merchant may select a data field. All the listed data fields are compatible with a text setting.