Sections and blocks

In a Shopify theme a page is a list of sections, and each section has settings and blocks. Which settings a section has is declared in its {% schema %} (sections/<type>.liquid). Their values, and which sections a page has in which order, are kept in JSON: the page’s template (templates/index.json) or a section group (sections/header-group.json).

Shopify’s theme editor changes that JSON from its sidebar. midcode does the same from its right panel, as edits to the files in your folder: the smallest change that says it, undoable, and listed in Publish. To open a theme in midcode, see Shopify themes.

The Section panel

In a theme, the right panel has a group named “Section”.

• –

  With an element selected, it shows the section that element belongs to.

• –

  With nothing selected, it shows the page’s sections, starting on the first one of the template.

The “Section” list at the top has every section of the page in the order it’s drawn: the section groups above the page (the header), the template’s own sections, then the footer’s group. Each one says which file it’s in (index, header-group), and a hidden one is struck through. Pick one to see it without selecting anything on the canvas. “Shopify’s editor”, beside the title, opens the store’s themes in Shopify’s admin.

How the section is found

Shopify wraps each section of a page in an element whose id carries the section’s key in the JSON (shopify-section-template--…__image_banner). When the selected element sits inside one, that key is the section.

When it doesn’t, the file the element is written in names the type (sections/image-banner.liquid is image-banner), and the page’s first section of that type is taken. If the page has two, pick the other in the list.

The template comes from the page’s address: a product page reads templates/product.json, the home page templates/index.json. An element written in layout/theme.liquid belongs to no section, and the panel doesn’t show for it.

Settings

The panel shows each setting of the schema with the control for its type. Labels come from the schema, and a t: label is read from locales/en.default.schema.json. A setting with no value in the JSON shows the schema’s default.

A typed value is written when you leave the field (or press Return in a one-line field), a slider when you let go, a switch or a list at once. In the trial on a development store the preview showed a setting about a second and a half after it was written.

The last row is what midcode has no picker for yet. The panel shows what’s picked and says “Picked from the store: changed in Shopify’s editor for now.”

Things from the store

A setting that points at something of the store opens a picker: image_picker (an image of the store’s files), product, collection, page, blog and link_list (a menu). Click the field and type in “Search the store”. “None” clears the setting.

For an image, the list has the store’s images, newest first, and “Upload an image…”, which puts a file of your Mac into the store’s files (JPG, PNG, WebP, GIF, AVIF or HEIC, up to 20 MB) and picks it.

The picker reads the store through its Admin API, so the store has to be connected. When it isn’t, the picker says so and offers “Open the Store view to connect it”: see Connect the store.

What’s written is what a theme keeps, not the thing itself:

Add, remove, hide and move sections

The buttons under the “Section” list act on the section that’s shown.

• –

  “Move up” / “Move down” move it among the sections of its own file. A section of the template doesn’t move into the header group.

• –

  “Hide this section” keeps it in the theme and stops the page from drawing it. “Show this section” brings it back.

• –

  “Remove this section” takes it out of the file. Nothing asks first: ⌘Z brings it back.

• –

  “Add a section” lists the kinds the theme lets you add there. The new one goes right after the section that’s shown, with the blocks and settings of its first preset, and the panel moves to it.

A kind of section can be added when its file in sections/ has presets in its schema, and its enabled_on and disabled_on don’t close the template or the group you’re in. In older themes the schema’s own templates list is read the same way.

Blocks

Under the settings, “Blocks” lists the section’s blocks in order, each with its name and its first text. Click one to open its settings, which use the same controls. The buttons on its row are “Move up”, “Move down”, “Hide this block” (or “Show this block”) and “Remove this block”.

“Add a block” lists the block types of the section’s schema that still fit: a type under its own limit, while the section is under its max_blocks (50 when the schema doesn’t say). The new block goes last, with the settings its type has in the section’s first preset, if any.

What midcode writes

Every change is made to the JSON as text, on the lines it touches. The comment Shopify puts at the top of the file stays, and so does the rest of the file, byte for byte. The examples are from a home page, templates/index.json.

One value

       "settings": {-        "image_overlay_opacity": 40,+        "image_overlay_opacity": 60,         "image_height": "large"       }

A setting that had no value yet is one new line, last in settings, indented like its neighbours:

       "settings": {         "image_overlay_opacity": 60,-        "image_height": "large"+        "image_height": "large",+        "show_text_box": false       }

A new section

The section gets a key made the way Shopify’s editor makes them: its type and six letters and digits. Its entry goes into sections after the one it follows, and its key into order.

     "image_banner": {       "type": "image-banner",       "settings": {         "image_overlay_opacity": 60       }     },+    "rich_text_Xk3mPq": {+      "type": "rich-text",+      "blocks": {+        "heading_a8FjkL": {+          "type": "heading",+          "settings": {+            "heading": "Talk about your brand"+          }+        },+        "text_Tn4GhR": {+          "type": "text",+          "settings": {+            "text": "<p>Share information about your brand.</p>"+          }+        }+      },+      "block_order": [+        "heading_a8FjkL",+        "text_Tn4GhR"+      ],+      "settings": {}+    },     "featured_collection": {

   "order": [     "image_banner",+    "rich_text_Xk3mPq",     "featured_collection"   ]

A new block is written the same way: its entry last in the section’s blocks, its key last in block_order.

Hidden

     "featured_collection": {       "type": "featured-collection",+      "disabled": true,       "settings": {

Showing it again takes that line out. A block is hidden the same way, inside its own entry.

Moved

Only order changes (block_order for a block). The list is written again whole, one key per line, as Shopify writes it.

   "order": [     "image_banner",-    "rich_text_Xk3mPq",     "featured_collection",+    "rich_text_Xk3mPq",     "collage"   ]

Removed

The section’s entry leaves sections and its key leaves order. Adding a section and then removing it leaves the file exactly as it was.

Before saving, midcode reads the result back as Shopify would. If it couldn’t be read, nothing is written and midcode says it can’t read the file right now.

Undo and Publish

Each change is one edit: ⌘Z undoes it, and Publish lists it by what it was (“Add a section (index.json)”, “Hide a section (index.json)”). Like every edit in a theme, it reaches the development theme through the Shopify CLI. It reaches your other themes when you send the theme: see Send the theme to your store.

Limits

• –

  Tried with Dawn’s files, and live on a development store: the section is found from the page’s real ids, and a setting written, a section added, hidden or removed showed on the storefront in about a second and a half. The pickers were tried with that store’s real files and products.

• –

  Only JSON templates and section groups. A section a layout includes by name ({% section 'announcement' %}), whose values are in config/settings_data.json, isn’t in the panel. A template written in Liquid (templates/page.liquid) has no sections to list.

• –

  Theme settings, the ones Shopify’s editor has under “Theme settings” (colors, fonts), are not in the panel.

• –

  The default template of each kind of page is read. A product assigned to templates/product.featured.json still shows the sections of templates/product.json.

• –

  App blocks (@app) and theme blocks (@theme, the files in blocks/) can’t be added. A theme block that’s already in a section shows with “Nothing to set in this block.”, and blocks nested inside a block aren’t listed.

• –

  A color is typed, not picked.

• –

  Setting types in the last row of the table are changed in Shopify’s editor.