Sections

#Anatomy of a section file

A section is one file in sections/, for example sections/promo.plang. It has up to three parts.

{%- assign s = section.settings -%}
<div class="site-wrap">
	<h2 class="site-heading">{{ s.heading }}</h2>
	<p>{{ s.text }}</p>
	{% render 'button', label: s.button_label, link: s.button_link %}
</div>

{% style %}
.box { padding: 1rem; }
{% endstyle %}

{% schema %}
{
	"name": "Promo hari ini",
	"settings": [
		{ "type": "text", "id": "heading", "label": "Heading", "default": "Promo hari ini" },
		{ "type": "textarea", "id": "text", "label": "Text", "default": "Diskon 20% untuk pesanan hari ini." },
		{ "type": "text", "id": "button_label", "label": "Button label", "default": "Pesan lewat WhatsApp" },
		{ "type": "link", "id": "button_link", "label": "Button link", "default": "wa:Halo, saya mau pesan" }
	]
}
{% endschema %}

• The template is everything outside the two blocks. It is the HTML inside the section. Read the owner's values from section.settings.
• {% schema %} holds one JSON object. A section file needs exactly one. Without it, saving fails. With two, saving fails too.
• {% style %} is optional CSS. Plangku scopes it to this section, so .box only matches inside it. Plangku only loads it on pages that use the section. See Styling.

The template language is covered in The Plang language.

#The schema

{
	"name": "Promo hari ini",
	"description": "A banner with a short text and a WhatsApp button",
	"icon": "Sparkles",
	"category": "custom",
	"padding": true,
	"settings": [],
	"presets": [{ "name": "Promo hari ini", "settings": { "heading": "Promo Ramadan" } }]
}

Mistakes in a schema show up in the Problems panel with a line number. The most common ones: invalid JSON, an unknown setting type, two settings with the same id, or an id that Plangku already uses (see below).

#Presets

A preset is a row in the section library. It has a name, an optional description (up to 160 characters) and settings: the values that override the defaults for that row.

"presets": [
	{ "name": "Promo Ramadan", "description": "Diskon khusus bulan puasa", "settings": { "heading": "Promo Ramadan" } },
	{ "name": "Promo gajian", "settings": { "heading": "Promo gajian" } }
]

If you give no presets, Plangku makes one with the section's name, so the section can always be added. A setting value that starts with assets/ (an image from a package) becomes the uploaded image's address.

#Reserved ids

A setting id starts with a letter and uses only letters, numbers and _. It can be up to 40 characters. These ids belong to the platform and cannot be used in a section:

handle, id, type, index, bg, bgImage, overlay, pattern, edge, headingAlign, pad, anchor.

#How Plangku wraps a section

You write the inside of a section. Plangku writes the outside. Every section that is not a header or footer is wrapped in a <section> element that:

• sets the colour variables of the section's background (--s-bg, --s-fg, --s-muted and more), so your text and cards work on any background,
• adds the vertical spacing, unless padding is false or {% shell padded: false %} is used,
• draws the pattern, the top edge and a photo background when the owner chose them,
• sets id to the owner's anchor id,
• adds data-code="<handle>", the name of your section file,
• adds data-section="<type>". For your own sections the type is code. For a built-in replacement it is the built-in type, like hero.

#Section style settings

Plangku adds a Section style group to every section it wraps. You do not write these settings.

You can read these values in your template (section.settings.bg) if you need them.

#The site-wrap class

Wrap your content in <div class="site-wrap"> to get the standard width. It is centred, up to 72rem wide, with side padding that grows on wider screens. Sections that want a full-bleed look can skip it.

#The shell tag

{% shell %} changes the wrapper for this render only. Put it anywhere in the template.

{% shell padded: false, class: 'text-center' %}

• padded: false turns the wrapper's vertical spacing off. padded: true turns it on.
• class: '...' adds classes to the <section> element, up to 300 characters.

Without a {% shell %}, the schema's padding decides.

#Replacing built-in sections

A section file named like a built-in section replaces it. The file sections/hero.plang replaces the Hero everywhere. The easiest way to start is Explorer → Built-in sections → Customize, which writes the built-in template and its full schema for you.

Things to know:

• Existing sections keep their stored values. Keep the same setting ids as the built-in schema, or the owner's text and photos will not reach your template. A setting your schema does not list is not shown in the settings panel, although its stored value can still be read in the template.
• The name, description, icon and category come from the built-in section when your schema leaves them out.
• A replacement does not appear in the library, and has no presets, because it is not a new section.
• Delete the file to go back to the built-in look.

#Which handles can be replaced

These can be replaced. The handle is the built-in's type name.

These cannot be replaced, and a file with one of these names fails to save:

To show products or articles from a collection in your own markup, make a new section with a collection setting. See Collections and data.

#Header and footer

header and footer are global sections. There is one of each for the whole website, not one per page.

• Plangku does not wrap them in a <section>. You write the whole element, such as <header> or <footer>.
• They have no Section style settings and no presets, and they are not in the library.
• Only handle, id and type are reserved for their settings.
• Everything in the header and footer, including the language switcher (site.languages), is yours to draw.

#When a section file is deleted or renamed

Pages keep a reference to the section's handle. If the file goes away, the reference breaks.

• A theme section on a page whose file is gone shows nothing on the live site. In the editor it shows "Missing: <handle>" and an error naming sections/<handle>.plang.
• Renaming a file is the same as deleting the old one and adding a new one. Add the section again from the library.
• A deleted built-in replacement goes back to the built-in look straight away.

You can restore a deleted file from History.