Themes and web templates
A theme controls how your whole site looks. It is a bundle of web templates (whole pages), widget templates (the blocks on site pages) and assets (logo, CSS, scripts, fonts). One theme is active at a time. This page explains the pieces and shows how to manage them without breaking the live site.
What you need
- The Manage Templates permission. Themes appears under Design in the sidebar.
- For editing templates, basic comfort with HTML. The Liquid parts are explained in How Liquid templates work in Raytha.
The parts of a theme
Open Themes, then click a theme. Its page has four tabs:
| Tab | What is on it |
|---|---|
| Settings | Title, description, the Publishing card (activate, allow export, duplicate) and the delete danger zone. |
| Web templates | Templates that draw a whole page: the shared layout, content item pages, list pages, site page layouts, login and error pages. |
| Widget templates | One template per widget type, with the settings editors fill in. |
| Assets | Files the templates use: images, stylesheets, scripts, fonts. |
The themes list shows each theme's Title, Developer name, Description and Status: an Active badge for the live theme, and Exportable or Hidden from export.
Web templates and widget templates
- A web template draws a full page, for example the page for one blog post. Web templates can inherit from a base layout, which supplies the header, footer and page frame and marks the spot for the page body with
{% renderbody %}. That is why one edit to the base layout changes every page. - A widget template draws one widget, such as a Hero. It has two halves: the Liquid markup and a list of fields (the settings form). Editors never see the markup, only the form.
Which template draws which page
| Visitor sees | Template that draws it | Where you choose it |
|---|---|---|
| A content item's page | The item's template, default Content item detail view | The Template field in the item editor |
| A public list (view) | The view's template, default Content item list view | Template on the view's Public tab |
| A site page | The page's template, such as Page - Full Width or Home | Template on the page's Settings tab |
| Each widget on a site page | The widget template of its type | The widget type picker |
| Sign-in, registration, forgot password, profile | The built-in login templates | Not selectable; Raytha uses the template by name |
| Error pages (403, 404, 500) | The built-in error templates | Not selectable |
| Every page's frame | The base layout and parent templates | Parent template in each template's settings |
Each built-in template is described in Overview of the built-in templates.
Activate a theme
- Open Themes and click the theme.
- On the Settings tab, in the Publishing card, click Set as active theme. If it is already active, the card says "This theme is the one visitors see."
- Open your public site and click through the main pages.
When you activate a theme, every content item and view that does not yet have a template in it gets one: the template with the same developer name as before if the new theme has it, otherwise the built-in Content item detail view or Content item list view. Email templates are not part of themes and do not change.
Important Site pages are not moved to the new theme. A site page keeps the template it already has, from the old theme, and shows the old theme's frame until you change it. After switching, open each site page, go to the Settings tab, pick a template from the new theme and click Save settings. Widgets always draw with the active theme's widget templates.
Create, duplicate, export and import themes
Create a theme
Click New theme on the themes list. Enter a Title, Developer name and Description. Tick Include default media to copy the built-in theme's images, Bootstrap files and icons into it. The new theme starts with all the built-in templates.
Duplicate a theme
Duplicate before making risky changes, so you can edit a copy while visitors keep seeing the original.
- On the theme's Settings tab, in Publishing, click Duplicate theme.
- Enter a Title, a new Developer name and a Description, then confirm.
- Wait for the background task to finish. It copies the templates, widget templates and assets. Follow it under Background tasks.
Edit the copy, check it carefully, then Set as active theme when it is ready.
Export a theme
- On the Settings tab, tick Allow this theme to be exported. The list then shows Exportable.
- Open
/raytha/themes/export/<developer name>on your site, for example/raytha/themes/export/my_theme. The browser shows the theme as JSON. Save it.
Warning That export address does not ask for a login. Anyone who knows the address can download the theme's templates while Allow this theme to be exported is ticked. Leave it off unless you want to share the theme, and do not put secrets in templates.
Import a theme
- On the themes list, click Import from URL.
- Enter a Title, Developer name and Description, and the Package URL: the web address of an exported theme file.
- Confirm and wait for the background task to finish.
The task downloads the package, creates the templates and downloads its media files. Addresses on internal networks are refused unless the server allows them.
Delete a theme
Use the Delete theme danger zone on the Settings tab. You cannot delete the active theme ("Set another theme active before deleting this one") or the built-in default theme.
Work with web templates
On the theme's Web templates tab you see a table with Label, Developer name and Type: Base layout, Built-in or Custom. Use the star on a row to favorite a template; favorites move to the top. Search templates filters the list.
Edit a web template
- Click the template.
- Edit the Liquid in the code editor. Type
{{for variables,{%for tags and|for filters to get suggestions. The side panel has a Variables tab (click a variable to insert it at the cursor) and an Assets tab (click a file to insert its public URL). Ctrl + Shift + F jumps to the panel's search box. - Click Save, or press Ctrl + S. You should see "Web template saved".
- Load the affected public pages and check them.
Template settings
| Setting | What it does |
|---|---|
| Label | The name shown in lists and pickers. |
| Parent template | The base layout this template sits inside. None means it draws a complete page by itself. |
| Base layout that other templates can inherit from | Makes the template available as a parent. The Liquid must contain {% renderbody %}. You cannot turn this off while other templates inherit from it, and it is locked on built-in templates. |
| Content types that can use this template | Which content types may choose this template for items and views. Content types created later includes future content types. |
To make a new template, click New template on the tab. A new template starts as {% renderbody %}, so it simply renders whatever its parent wraps. The developer name is chosen at creation and then fixed.
Delete a web template
Custom templates have a Delete template danger zone. Raytha refuses when content items, list views or site pages still use the template, when other templates inherit from it, and when it is the only non-layout template new content types can use. Built-in templates cannot be deleted.
Work with widget templates
The Widget templates tab lists each widget type with its Label, Developer name and number of Fields. Click one to edit it:
- The Liquid tab holds the markup. Settings are available as
widget.settings.<field developer name>. - The Fields tab defines the settings form, with a Form preview showing what editors will see.
- New widget template creates a custom widget type. Its developer name is the widget type that pages store, and it cannot change later.
Custom widget templates can be deleted unless pages still use them; Raytha lists the pages. Reset to defaults, at the bottom of the tab, replaces the markup and fields of every built-in widget template with the originals. Custom templates are untouched, and each built-in keeps a revision you can revert to.
Assets
The Assets tab lists the theme's files. Click Upload assets to add more. Each row has a Liquid snippet and copy buttons for the public URL and the redirect URL snippets. See The media library for which to use.
Edit templates safely
- Templates have no draft. Save changes the live site immediately.
- Every save keeps a revision. The Revisions panel lists them; click Revert to go back. See Revisions and publishing.
- Raytha checks Liquid syntax when you save and refuses a template with a syntax error. Mistakes that only show up at render time, such as printing a field that does not exist, are not caught. Always load the page after saving.
- For big changes, duplicate the theme first. Edit the copy and activate it when it works.
- Edit the base layout with care. It is part of every page.
Gotchas
- A new template has no Variables panel until you create it. Click Create once, and the editor then lists the variables available to that template.
- Built-in does not mean read-only. You can edit the Liquid of built-in templates, but you cannot delete them or change whether they are a base layout.
- Duplicating or importing can take a while for themes with many assets, because every file is copied or downloaded.