plangkuDocs

Building themes

Theme settings

Add choices for the whole website, like a promo colour, with config/settings_schema.json.

What theme settings are

Section settings belong to one section. Theme settings belong to the whole website. Use them for things every section may need: an accent colour, a content width, a switch for rounded photos.

You define them in config/settings_schema.json. The owner sees them in the visual editor, in the Theme tab.

The file format

The file is a list of groups. Each group has a name and a list of settings.

json
[
	{
		"name": "Promo",
		"settings": [
			{ "type": "color", "id": "promo_color", "label": "Promo colour", "default": "#E11D48" },
			{ "type": "text", "id": "promo_text", "label": "Promo banner text", "default": "Gratis ongkir untuk pesanan di atas Rp 200.000" }
		]
	},
	{
		"name": "Layout",
		"settings": [
			{ "type": "range", "id": "content_width", "label": "Content width", "min": 960, "max": 1440, "step": 40, "unit": "px", "default": 1200 },
			{ "type": "checkbox", "id": "rounded_images", "label": "Rounded photos", "default": true }
		]
	}
]

To create the file, click the new file icon on the config folder in the Explorer. Plangku writes a small starter.

  • The file must be a JSON list. Anything else gives the error that it "is a list of groups".
  • A group's name is up to 60 characters. Without one, it is called "Theme settings".
  • You can have up to 20 groups. A group with no valid settings is left out.
  • Each setting uses the same options as in a section. See Setting types.

What is different from section settings

  • A collection setting is not allowed. It is an error.
  • Only handle, id and type are reserved as ids. The Section style ids (bg, pad and so on) are free to use.
  • An id must be unique across all groups. A repeat is an error.
  • All other types work, including list, image, link and icon.

Where the owner sees them

In the visual editor, open the Theme tab. Below the colour, font and style choices, each group appears with a code icon and the note "From your theme code (config/settings_schema.json)".

A website with no settings_schema.json, or with an empty one, shows no extra groups.

Where the values are stored

The owner's choices are saved with the website's theme design, in the draft. They go live when the website is published, and they are part of the website's version history. They are not stored in the theme files.

The file only describes the settings and their defaults. When a template or the CSS reads a value, Plangku uses the owner's choice, or the default from the schema if the owner has not chosen. Values for ids that are no longer in the schema are ignored.

Using them in templates

Read a value with settings.<id>. It works in sections and in snippets.

plang
{%- if settings.promo_text != blank -%}
<div class="promo-bar" style="background: {{ settings.promo_color }}">
	{{ settings.promo_text }}
</div>
{%- endif -%}

Values are checked by type, the same way as section settings. See Setting types for what each type gives you.

Using them in CSS

For some types, Plangku also writes a CSS custom property. You can use it in any CSS file and in any {% style %} block.

css
.promo-bar { background: var(--ts-promo-color); }
.site-wrap { max-width: var(--ts-content-width); }
.card img { border-radius: calc(var(--ts-rounded-images) * 1rem); }

The name is --ts- followed by the setting's id, with each _ changed to -. Other letters keep their case, so promo_color gives --ts-promo-color and contentWidth gives --ts-contentWidth.

Setting typeCSS variable value
colorThe hex colour. Only when it is a valid #RGB or #RRGGBB
rangeThe number, followed by the unit if it is 1 to 4 lowercase letters or % (so 1200px)
numberThe number, with no unit
select, radioThe chosen value, as long as it is a plain word or colour-like text (letters, numbers, spaces and . # % ( ) , -) and at most 80 characters
checkbox, toggle1 when on, 0 when off

text, textarea, image, link, icon and list give no variable. Use settings.<id> in the template for those, for example in a style attribute.

The variables are set on the website's root element, so they are available everywhere on the page, including inside every section.

Tip: A checkbox gives 1 or 0, so you can use it in calc(). For anything more, write {% if settings.rounded_images %} in the template and add a class.

Example: one setting, both ways

json
[
	{
		"name": "Colours",
		"settings": [
			{ "type": "color", "id": "promo_color", "label": "Promo colour", "default": "#E11D48" }
		]
	}
]

In CSS, assets/site.css:

css
.badge-promo { background: var(--ts-promo-color); color: white; }

In a section template:

plang
<span class="badge-promo">Diskon 20%</span>

When the owner changes the colour in the Theme tab, every badge changes with it.