Upgrading module layouts to dynamic Studio sections

Dynamic sections are essentially module layouts, given a little bit of extra metadata so that Studio can read them and use them in the page. This article explains how to add that metadata to an existing module layout.

Written By Matt Jones

Last updated About 14 hours ago

Pre-requisites

To upgrade a module layout to a Studio dynamic section, you will need to be familiar with the Quickstart: CLI and have a connection to the site you’re building your library on CLI Site Setup . Siteglide Admin doesn’t yet support adding metadata in code-editor.
This article assumes you already have a module layout you’d like to upgrade, see Modules Reference

Do I lose anything when I upgrade a module layout to a dynamic section?

No, this is an upgrade, not a replacement. Dynamic sections will still work as ordinary module layouts, when you use the {% include 'module' %} or similar tags. Existing pages which already include the section will keep working.

This means it’s still absolutely fine to use an {% include %} tag within a static section to pull in a nested module layout.

Using as a dynamic section simply gives a different user-experience to the client. You can fine-tune which settings the client is given.

If you’re creating a library to share with others, upgrading allows the module layouts which reference that section to be installed along with the static sections when others download your library.

Metadata Reference

For each module layout, there will normally be more than one file which is needed to make that layout work. Normally these will at least all be inside the same folder, but not always.

For each layout, choose one file which will be the “top file” and will be used by Studio to read its metadata and find other dependencies. This should be the file that is first loaded when your module layout is used. Normally, the file will be named wrapper.liquid.

The top file must be given the following metadata in YML format in the frontmatter:

e.g.

---
metadata:
  studio_library: my-library
---

Key	Req / Type	Usage (scroll sideways to read more)
`studio_library` (`studio_theme` is deprecated)	Yes / String	The folder name of the library this belongs to
`studio_dynamic/library`	No / String	Same, but not currently required
`studio_dynamic/layout`	Yes / String	The folder the module layout sits inside. E.g. if I had a Blog module layout at layouts/modules/module_3/<layout-name>/list/wrapper.liquid Set studio_dynamic/layout to <layout-name>
`layout_name`	Yes / String	A human-readable version of the above
`studio_dynamic/module_id`	Yes / String	A numerical ID representing which module this is a layout for. While being loosely based on Siteglide module IDs, a few more are added for system module features which don’t officially have module IDs. The available IDs are documented here. e.g. ‘module_3’
`studio_dynamic/sub_module_id`	Yes / String	Even within modules, some features use different Siteglide tags. We’ve documented sub-module IDs which help Studio identify the code and options it needs to use this type of layout. e.g. ‘1’ If a module has no sub-modules defined, use ‘0’ for default.
`studio_dynamic/type`	Yes / String	‘default’/’list’/’detail’ If applicable, always set either `list` or `detail`. If not applicable to this module e.g. Secure Zones, set ‘default’.
`studio_dynamic/files`	Yes / Array	This lists all dependency Liquid files which should be installed at the same time as the “top file”. It allows you to specify files within completely different directories, which is useful for creating complex layouts which nest other module layouts and install them all together. E.g. an add-to-cart button inside an eCommerce product layout. Use full file paths relative to the marketplace_builder folder in CLI: `views/partials/layouts/modules/module_3/blog-live-updating-table/list/wrapper.liquid` It’s normal for the first item in the array to reference the current file, for the sake of showing all files in one list. It will not be installed twice. It is good practice for two top-files in the same library not to install files with identical names and filepaths, to prevent duplicates; Studio should gracefully skip this if it occurs - just be aware if the files have different content, the destination site might not get exactly what you expected.
`studio_dynamic/live_updates`	No / String	‘true’/’false’ Live default layouts tend to shift the choices away from the client towards the end user, e.g. instead of letting the client choose to output 3 items, a dropdown is shown where the end-user can choose how many items to display. Setting this to ‘true’ reduces the options given to the Studio user in order to avoid confusion when those choices are irrelevant and the choice sits with the end-user. To gain deeper control over what choices are passed to the end user, the layout code needs modification and settings need adding for the client.
`settings`	No / Array	This is exactly the same as using settings in a static section. Use it to give the client choices about how you want the functionality of the layout to behave. These will appear as settings in the Studio UI. They use the same field-types as settings in Studio. See the full example below.
`studio_dynamic/make_global_form`	No / Boolean	Use when your layout is a form layout, but sits in a folder like forms/form_2. Form 2 might not exist on a destination site when your library is being installed there, so this setting being set to true copies your layout into a forms/global folder and creates shortcuts to it in any form folders they do have.
`studio_dynamic/already_global_form`	No / Boolean	Similar to above, but where you’ve already got your form layout in a global folder. This skips the move to global folder, but keeps the process where shortcuts are created on the destination site.
`studio_dynamic/global_form_layout_shortcut`	No / Boolean	You’re unlikely to need to add this. It’s added automatically by Studio when shortcuts are created from specific form folders on a site to a global folder holding a dynamic form section

Full metadata example

In this example, the file views/partials/layouts/modules/module_14/product/live-updating-product-list/list/wrapper.liquid is the “top file” which will be given the metadata.

---
metadata:
  settings:
  - id: price_options_floor
    type: number
    label: Price Options Floor (Cents)
    default: 500
  - id: price_options_increment
    type: number
    label: Price Options Increment (Cents)
    default: 500
  - id: price_options_number
    type: number
    label: Price Options Number
    default: 5
  - id: show_display_price_crossed_out
    type: boolean
    label: Show Display Price Crossed Out
    default: true
  - id: product_category_parent
    type: text
    label: Product Category Parent
    default:
  - id: filters_values_from_URL
    type: boolean
    label: Set Filter Defaults From URL
    default: false
  - id: cart_url
    type: text
    label: Cart URL
    default: "/cart"
  studio_theme: studiokit
  studio_library: studiokit
  studio_dynamic/type: list
  studio_dynamic/files:
  - views/partials/layouts/modules/module_14/product/live-updating-product-list/list/wrapper.liquid
  - views/partials/layouts/modules/module_14/product/live-updating-product-list/list/item.liquid
  - views/partials/layouts/modules/module_14/components/add_to_cart_button/live-updating-product-list.liquid
  studio_dynamic/theme: studiokit
  studio_dynamic/layout: live-updating-product-list
  studio_dynamic/theme_id: theme_01
  studio_dynamic/module_id: module_14
  studio_dynamic/layout_name: Live-updating product list
  studio_dynamic/live_updates: 'true'
  studio_dynamic/ui_framework: tailwind
  studio_dynamic/original_name: Live Updating Product List
  studio_dynamic/sub_module_id: '1'
  studio_dynamic/make_global_form: false
---

Module and submodule reference

Use this to determine which studio_dynamic/module_id and studio_dynamic/sub_module_id to give your layout in the metadata.

Module	ID	Submodules	Submodule IDs
Menu	module_2	Headers, Footers, Sidebars	1, 2, 3
Blog	module_3	Default	0
Slider	module_4	Default	0
Secure Zones	module_5	Login Forms, Logout Buttons, User Form Submissions	1, 2, 3
Authors / Team	module_6	Standard	1
Testimonials	module_8	Default	0
FAQ	module_10	Default	0
Events	module_12	Default	0
eCommerce	module_14	Product List, Product Detail, Cart, Order Detail, Currency Changer, Tax Code Changer	1, 2, 3, 4, 5, 6
Forms	module_s1	Default	0
Pagination	module_s2	Default	0
Form Confirmation	module_s3	Default	0
Cookie Preferences	module_s4	Cookie Popup, Cookie Settings Page Section	1, 2
Categories	module_s5	Full Categories List, Category Detail Layouts	1, 2
WebApp	webapp	Standard, Swiper, Tables, WebApp with Update and Delete	1, 2, 4, 5