# Getting started from the default theme A theme is a zip with a manifest, one layout, one template per page, snippets, a stylesheet, images, fonts and Danish and English strings. The layout follows Shopify's: if you have built a Shopify theme, most of this will feel familiar. There is no JavaScript: Truly's components draw everything interactive (the pickers, the calendar, the forms, the consents and the order button), and your templates place them as slots. A `
` menu needs none either: when a link in it leads to another page, Truly closes it. ## 1. Download the default theme In the back office, a tenant owner, admin or theme developer opens **Settings > Brand & Apps > Theme** and clicks **Download the default theme**. The zip is today's booking pages in the theme format, and it uploads unchanged. Its `coverage.json` lists the pages the default theme draws; Truly ignores the file in your upload, and every page it does not list keeps today's design whatever the theme says. ## 2. Look around ``` manifest.json { "name": "…", "version": "1.0.0", "format_version": 1 } layout/theme.liquid wraps every page templates/.liquid one per page, e.g. templates/booking.services.liquid snippets/.liquid pieces you {% render 'name' %} assets/theme.css your stylesheet assets/.webp images (PNG, JPEG or WebP) and .woff2 fonts locales/da.json your strings, Danish locales/en.json and English ``` The default layout is one line: ```liquid {% slot 'cookie_banner' %}{% slot 'header' %}{{ content_for_layout }}{% slot 'footer' %} ``` and most templates are a single slot, for example `templates/booking.services.liquid`: ```liquid {% slot 'service_picker' %} ``` ## 3. Make a change Give the services page a heading and the location's address around the picker: ```liquid

{{ 'services.title' | t }}

{{ location.address_line }}, {{ location.postal_code }} {{ location.city }}
{% slot 'service_picker' %} ``` Add `"services": { "title": "Vælg behandling" }` to `locales/da.json` and `"services": { "title": "Choose a treatment" }` to `locales/en.json`, and style `.intro` in `assets/theme.css`. Change `name` and `version` in `manifest.json` so you can tell your versions apart. ## 4. Upload and check Zip the folder's contents (the manifest at the top of the zip, not inside a folder) and upload it on the same back-office page. The check report lists every problem with a reason, file and line; see [The check report](/guides/check-report). A package that passes becomes a draft version. ## 5. Publish A draft changes nothing for customers. Publishing it, in the theme library, shows it on the tenant's verified custom domain. Themes never show on Truly's own booking host. ## Next - [The edit, push and preview loop](/guides/edit-push-preview) - [Slots and styling](/guides/slots-and-styling) - [Locales](/guides/locales) - The reference: [routes and states](/reference/v1/routes), [drops](/reference/v1/drops), [slots](/reference/v1/slots), [markup](/reference/v1/tree), [CSS](/reference/v1/css), [package format](/reference/v1/package). # The edit, push and preview loop Every upload creates a new draft version; nothing you upload changes what customers see until someone publishes it. So the loop is safe to run as often as you like. ## Edit Work in a folder laid out as the [package format](/reference/v1/package) says. Keep it in version control: the theme's own `version` in `manifest.json` is yours to set, and Truly shows it next to each version in the library. ## Pack Zip the folder's contents, with `manifest.json` at the top of the archive. Leave out anything that is not part of the format (`.git`, `.DS_Store`, `README.md`): an unknown file fails the check. For example: ```sh cd my-theme && zip -r -X ../my-theme.zip manifest.json layout templates snippets assets locales ``` ## Push Upload the zip in **Settings > Brand & Apps > Theme**, or push it from a script with a personal push token. Either way, the same file again while it is being checked, or after it passed, returns the same upload instead of a new version, so a retried push is safe. Each push makes a new draft version; it never overwrites one. ### A push token A theme developer, or anyone with the push token permission, creates a token under **Push tokens** on the same page. Creating one asks for a code from your authenticator app or your passkey; a password is not enough, so add one of them under **Profile** first. The token is shown once: copy it into your password manager or your CI's secrets. It expires after 90 days, the page shows when it was last used, and you can revoke it there at any time. It also stops working when your user is deactivated, loses the upload permission or the theme module is turned off. A token can do two things: push a zip and make a preview link. It cannot publish, roll back, delete or turn the theme off; those stay in the library, behind your sign-in. ### Push Send the zip as the `archive` field of a form upload to `https://app.truly.dk//api/themes/pushes`, with the token in the `Authorization` header (never in the address or a cookie): ```sh curl -sS -H "Authorization: Bearer $TRULY_THEME_TOKEN" -F archive=@my-theme.zip https://app.truly.dk//api/themes/pushes ``` The answer is the upload, a job you poll for the check report: ```json { "id": 42, "status": "pending", "filename": "my-theme.zip", "report": [], "counts": { "error": 0, "warning": 0, "info": 0 }, "versionId": null, "version": null, "createdAt": "…", "url": "//api/themes/pushes/42" } ``` `202` means a new upload; `200` means this archive was already pushed, and you get that upload back. Poll `GET https://app.truly.dk` followed by `url`, with the same header, every few seconds until `status` is `succeeded` (with the new version's id in `versionId`, and its warnings in `report`) or `failed` (with the errors in `report`). ### Read the result `succeeded` only means a version was made: a CSS rule left out, a missing English string or a state slot placed nowhere is a warning, and the version is made anyway. Check `counts.error` and `counts.warning`, not only `status`, and read every entry whose `level` is `error` or `warning`. The `info` entries (`fixture_states`, one per template) list the states each template was rendered in; they need nothing from you. Each entry has its `reason` code and `message`, the same sentence the Settings page shows, in English. A CSS entry also quotes what was left out (`selector`, `declaration` or `rule`, at most 200 characters): ```json { "id": 42, "status": "succeeded", "counts": { "error": 0, "warning": 1, "info": 1 }, "report": [ { "level": "warning", "reason": "css_selector", "message": "The selector is not allowed (no ids, no :has() and only [data-part=…] as an attribute); the rule is left out.", "file": "assets/theme.css", "line": 12, "key": null, "selector": ".card:has(input:checked)" }, { "level": "info", "reason": "fixture_states", "message": "The template was shown with sample data for these states.", "file": "templates/booking.services.liquid", "line": null, "key": "default, empty" } ], "versionId": "…", "version": { "name": "My theme", "version": "1.4.0" }, "createdAt": "…", "url": "//api/themes/pushes/42" } ``` [The check report](/guides/check-report) explains each field and the order of the checks. Errors come back as `{ "error": { "code": "…" } }`: `unauthenticated` (401: no token, or an unknown, expired or revoked one), `forbidden` (403: your user lacks the permission), `missing` (422: no `archive` field), `too_large` (413), `too_many_requests` (429: 20 pushes per token and 40 per tenant an hour). A tenant without the theme module answers 404. ## Check The page shows the check report when the check is done. Errors block the version; warnings (an English string missing, a CSS rule left out) are kept on it. See [The check report](/guides/check-report). ## Preview Preview a version on the tenant's custom domain before publishing it: choose **Preview on your domain** in the version's menu in the library, or ask for a link with your push token: ```sh curl -sS -X POST -H "Authorization: Bearer $TRULY_THEME_TOKEN" https://app.truly.dk//api/themes/versions//preview ``` which answers `201` with `{ "url": "…" }` (or `422` `no_domain` while the tenant has no connected domain). You need the preview permission, and the domain must be verified and connected. The link opens ```text https:///_preview//?preview_token= ``` with the version drawn against sample data for that route and state (the same data the check renders with), and Truly's own parts (the pickers, forms and footer) as labelled placeholders. Change `` and `` in the address to see any other page and state of the [routes](/reference/v1/routes); a route or state that does not exist answers 404. Links between preview pages keep the link; any other link leaves the preview. A page without a template of yours shows the default theme, as it would live. The link works for 4 hours, for the version, domain and user it was made for. It stops working sooner if the version is deleted, the theme module or the theme switch is turned off, the domain stops being live, or the user loses the preview permission. Treat it as a password for the draft: anyone holding it sees the draft until it expires. While a link is live the version cannot be deleted by hand, but the library's automatic clean-up may still delete it to make room for a new upload, which ends the link. Previews set no cookies, load no tracking, and are never cached. ## Publish and roll back Publishing, rolling back, duplicating, downloading and deleting versions, and the switch that turns the theme off, are in the theme library. The library keeps a limited number of versions: when it is full, a new upload deletes the oldest draft, never the published version. ## When a page fails A page that fails to render (a Liquid error, a missing required slot, a time limit, a filter result over 64 KB) does not break the booking: that page falls back to the default theme, and the failure is counted per version and day with its reason, template and line, without any customer data. Fix it, upload a new version and publish it. # Slots and styling ## Slots A slot is one of Truly's components. You place it with a tag; it draws itself: ```liquid {% slot 'service_picker' %} {% slot 'consent', role: 'terms' %} {% slot 'order', label_da: 'Bestil og betal', label_en: 'Order and pay' %} ``` The order label names a payment, so it applies only when something is paid online. Where nothing is paid (a booking with no amount due), the button books the time and reads "Book tiden" / "Book the time" whatever the label says. Each page has slots it must place, per state: the [routes and states](/reference/v1/routes) reference lists them. The check refuses a package where a template, together with the layout and the snippets they render, never places a slot every state of its page requires, and warns about a slot only some states require. At render, Truly checks the page against the state it is in, so put a state-dependent slot behind the matching drop: ```liquid {% slot 'booking_status' %} {% if state.withdrawal %}{% slot 'withdrawal_notice' %}{% endif %} {% endslot %} ``` A field's value is a quoted literal; `true` may also be written bare. The account forms (`signup_form`, `sign_in_form`, `sign_in_code_form`, `profile_logins`) take `bare: true`: the form without Truly's heading and without the card around it, so your own heading does not stack with ours. On Min side and the sign-in pages a bare form also has no `main` of its own, so place it inside yours. The profile page places either `profile_logins` or all three of its parts, each once, so you can lay them out yourself; each part also takes `bare: true`, which leaves out its card and its subheading so you head your columns: ```liquid

{{ 'profile.title' | t }}

{{ 'profile.contact' | t }}

{% slot 'profile_contact', bare: true %}

{{ 'profile.sign_in' | t }}

{% slot 'profile_sign_in', bare: true %}{% slot 'profile_locale', bare: true %}
``` ### Container slots A container slot is a block: Truly draws its container (the step's section, the consents' region, a membership's card) at its place, and your markup and the slots between `{% slot %}` and `{% endslot %}` inside it, in your order. The legal parts sit inside their container, so you decide where in the step the consents, the withdrawal notice and the order go: ```liquid {% slot 'payment_step' %} {% if state.open %} {% slot 'order', label_da: 'Betal nu', label_en: 'Pay now' %} {% slot 'payment_consents' %} {% slot 'consent', role: 'perform_now' %} {% slot 'consent', role: 'terms' %} {% endslot %} {% slot 'payment_withdrawal' %}{% if state.withdrawal %}{% slot 'model_withdrawal_form' %}{% endif %}{% endslot %} {% endif %} {% endslot %} ``` Each route's containers, and the slots each holds, are in the [routes and states](/reference/v1/routes) reference. A listed slot outside its container, a container inside one that is not its own, and a container without `{% endslot %}` fail the check; a slot your snippet places is checked when the page renders. On Min side's membership page the actions sit inside `membership_status`, which draws them in each membership's card; `membership_termination` must come before `membership_pause`. To draw the membership cards yourself from `memberships`, place `{% slot 'membership_status', membership: 'next' %}` once inside `{% for m in memberships %}`, each holding that membership's `membership_termination`: the Nth one holds the Nth membership's actions, so loop over `memberships` in its own order (not `reversed` or sorted). A page that places a different number than there are memberships falls back to Truly's default theme. If you print the pause rules yourself from `memberships[].pause`, write `{% slot 'membership_pause', bare: true %}`: the pause form without its heading and its own list of the rules. To draw the details step your own way, write `{% slot 'details_form', bare: true %}`: the slot then draws only the form (the fields, the parts you place inside it, the submit), without Truly's heading, the accepted payment methods or the recap of the done steps. Draw those yourself from `summary` and `payment_methods`, inside your own `main`; the customer must see the payment methods before ordering. The payment step takes `{% slot 'payment_step', bare: true %}` the same way: no step heading and no recap, so draw them from `summary` (the held booking, without change links: its `price`, what is charged now in `due_today` and, for a deposit, the rest for the salon in `in_salon`); the messages, the code field, the cancellation fee, the hold's countdown and the parts you place inside stay. The booking's own page takes `{% slot 'booking_status', bare: true %}` too: no heading, order card or "Book en ny tid", so draw them from `summary`, `order` (a booking paid online), `receipt_email` and `new_time_url`, and word the heading by `state.status` and `state.payment`; the hold's countdown, the status messages, the withdrawal notice you place inside, the account code field and the referral welcome stay. When the chosen time is gone (someone else booked it, or it is no longer offered), the details step renders in its `stale` state: place `{% slot 'stale_slot' %}` there instead of `details_form`. It draws Truly's step around the notice and the day's other free times; with `bare: true` only the notice and the times, so you head the page yourself (`stale.date` and `stale.time` name the lost time, `summary` the rest of the choice): ```liquid {% if state.stale %}

{{ 'details.taken' | t }}

{% slot 'stale_slot', bare: true %}
{% else %} {% slot 'details_form', bare: true %}…{% endslot %} {% endif %} ``` While the seller has closed its public sales, every booking and purchase page answers with the `errors.sales_closed` page instead: place `{% slot 'sales_closed' %}` in it, inside your shell. With `bare: true` it draws only the text and the call link, so head it yourself: `

{{ sales_closed.title }}

{% slot 'sales_closed', bare: true %}
`. Every other page's own slot takes `bare: true` too, so no customer page has to keep Truly's look: the booking steps' pickers, the payment's return page (`order_status`), the payment link, the waitlist and offer pages, the withdrawals, the price list, the punch card, gift card and membership pages, the card link pages, the rebooking and unsubscribe pages, the legal texts, the error pages (`not_found`, `too_many_requests`, `form_expired`) and every Min side page. Bare leaves out Truly's heading, its own `main`, the recap or summary card and any button to a public page; the messages, forms, legal parts and links that carry a secret (a retry payment, a withdrawal link) stay. Draw what was left out from the route's drops (`state`, `summary`, `me`) and link on with `route_url`. Each slot's reference entry says what its bare form keeps. A form sent after it was open too long now answers with the `errors.form_expired` page (place `{% slot 'form_expired' %}`), not a plain error page. To list the payment methods the tenant accepts, place `{% slot 'payment_marks' %}` where you want them, on any page, inside a container or not, and as often as you like, after your own label: `

Vi tager imod

{% slot 'payment_marks' %}`. Truly draws the brands' own marks (their rules forbid recolouring or resizing one against the others), from the tenant's online payment setting, on every page (unlike `payment_methods`, which a booking page lists only where payment is taken). Rules that hold everywhere: - The layout places `{% slot 'footer' %}` and prints `{{ content_for_layout }}` once, both at its top level, outside any `if`, `for` or other block and not in a snippet. - Pages where tracking tags may load require `{% slot 'cookie_banner' %}`; it is simplest to place it in the layout, where it is allowed on every page. - A slot that is not a container has no content of its own, and no slot can sit inside a link. - The legal slots (the consents, the withdrawal notice and form, and the order) cannot be replaced or split: the order slot always draws the order summary directly followed by the order button. The [slots](/reference/v1/slots) reference says what each slot draws. ## Styling Write normal CSS in `assets/theme.css`, with classes on your elements. Truly rebuilds the stylesheet from what it accepts (see the [CSS](/reference/v1/css) reference) and serves it from its asset host. - Your rules apply to your own markup and stop at slots: `button { … }` styles your buttons, never Truly's. Your markup inside a container slot is yours again, so your rules reach it and stop at the slots inside it. - Inherited properties do flow into slots: `color`, `font-family`, `font-size` and `line-height` on a wrapper style the component inside. - To recolour Truly's components, set the `--truly-…` custom properties on your own element around the slots, as in `.page { --truly-color-primary: #1a1a1a; --truly-radius: 0; }`. The [slots](/reference/v1/slots) reference lists them. - To make the order summary a dark bar, set `--truly-order-background`, `--truly-order-foreground` and `--truly-order-muted-foreground` on `[data-part="order"]` (or a wrapper): they recolour the summary's background, its text and its labels, and the muted colour also the notes and seller line under the button (outside the summary box), so paint the whole part's background too when the muted colour is light. - To style inside a component, select its hooks: a rule whose last part is a `[data-part="…"]` reaches into the slot, as in `.checkout [data-part="order"] { gap: 2rem; }`. A part further left (`[data-part="order"] button`) stays outside. The [slots](/reference/v1/slots) reference lists each slot's hooks; they keep working for themes of the same `format_version`. - Truly's headings inside a slot keep Truly's weight and size until you style them: `[data-part="subheading"]` is a card's title, a section's heading, a form group's or a consent's title, a booking step's section heading or a time-of-day group, and the footer's and cookie banner's headings ("Fortrydelsesret", "Dine kort", "Afbestilling og udeblivelse", "Modtager", "Medlemsvilkår", "Nye ledige tider"), `[data-part="alert-title"]` an alert's title, as in `.page [data-part="subheading"] { font-family: var(--serif); font-weight: 400; font-size: 1.25rem; }`. Legal headings stay on the page; you change how they look, not what they say. - The code boxes (the sign-in code, and a code asked when adding a login) are a row at most 20rem wide of six squares. `[data-part="code"]` is the row and `[data-part="code-slot"]` each box: `.login [data-part="code"] { max-width: none; width: 100%; } .login [data-part="code-slot"] { aspect-ratio: auto; height: 64px; }` stretches them across the form. - To size the payment marks, set `--truly-payment-mark-height` on `[data-part="marks"]` or a wrapper, as in `.site-footer { --truly-payment-mark-height: 20px; }`; every mark keeps the same height and its own width. - No ids, no `:has()`, no other attribute selectors and no `style` attributes. ## Images and fonts Put images in `assets/` as PNG, JPEG or WebP (no SVG) and show them with `…`; `alt` is required (empty for a decorative image). Truly re-encodes them as WebP. The tenant's logos come as drops: `{{ tenant.logo.alt }}` inside `{% if tenant.logo %}`. Fonts are WOFF2 files in `assets/`, loaded with `@font-face { font-family: Brand; src: url(brand.woff2) format("woff2"); }`. Make sure your licence allows web use. ## Icons Use `{% icon 'arrow-right' %}` for Truly's icon set; inline SVG is not allowed. The [markup](/reference/v1/tree) reference lists the icons. ## Links Link to the tenant's website with an absolute `https:` URL, and between Truly's pages with `route_url`: the route id, then its params written literally in the template. Truly builds the URL (the tenant's domain, the language and campaign parameters). When the page is drawn, Truly adds the visitor's attribution (the referrer and the Reserve with Google token) to every link on the booking page's own host, so a booking made through your links is credited as one made through Truly's pickers; links to other hosts get nothing. ```liquid All locations Book a haircut ``` Each route on the [routes](/reference/v1/routes) page says whether it has a link and which params it takes. A param must match its pattern, or the page fails and falls back: | Param | Value | | --- | --- | | `location` | the location's slug in its URL (`a-z`, `0-9`, `-`) | | `service`, `product`, `plan` | the service's, punch card's or gift card's, or membership plan's number in its URL | | `kind` | the legal text: `terms`, `privacy`, … as in its URL | A missing or extra param, or a route without a link (pages reached only from a link Truly sends, such as a booking's own page, and the error pages), fails the page. In a preview every link opens that route's preview. `tel:` and `mailto:` links are not allowed: print phone numbers and email addresses as text. # Locales Booking pages show in Danish or English, as the customer chooses. Your theme's own strings live in `locales/da.json` and `locales/en.json`; Truly's components and the drops come in the page's language already. ## Files Both files are required. Each is a JSON object of plain strings, flat or nested; keys are lowercase letters, digits, `-` and `_`, at most 64 characters: ```json { "services": { "title": "Vælg behandling" }, "footer_note": "Vi glæder os til at se dig" } ``` No HTML in strings: they are printed as text. ## Using strings ```liquid

{{ 'services.title' | t }}

``` `t` takes the dotted path of a key. A key missing from the page's language falls back to Danish. A key missing from both fails the page. ## Step names in your wording `summary.steps[].label` is Truly's name for each booking step. To use your own, write one key per step in your locales and look it up by the step's `id` (`location`, `service`, `staff`, `time`, `details`, and `pay` while the location takes payment online): ```liquid {% for step in summary.steps %} {% assign key = 'steps.' | append: step.id %}
  • {{ key | t }}
  • {% endfor %} ``` with `"steps": { "location": "Salon", "service": "Behandling", "staff": "Barber", "time": "Tid", "details": "Bekræft", "pay": "Betal" }` in `da.json` and the English words in `en.json`. Every `id` needs its key: a missing one fails the page. ## Danish first A key in `da.json` that `en.json` lacks is a warning in the check report (`missing_english_key`), not an error: the version still uploads, and English pages show the Danish string. Add the English strings before you publish if English customers matter to the tenant. ## Drops in the page's language Drop values that are words (a day's name, a menu link's label, a plan's credits) are already in the page's language, so print them as they are. The [drops](/reference/v1/drops) reference says which are. # The check report Every upload is checked before it becomes a version. The report lists each problem with: - its **level**: an error blocks the version; a warning is kept on it and the version is still made; a `Tested` line lists the states each template was rendered in; - its **reason**, a fixed code (the [package format](/reference/v1/package#check-report-reasons) reference lists them all); - the **file** in the package, the Liquid **line** where known, and for locale strings the **key**; - for a CSS rule left out, what was left out as written, at most 200 characters: the `selector`, the `declaration` or the at-`rule`. The report never quotes your template's text or a Liquid error message, apart from the name of an element or attribute themes cannot use (`