Theme editor: change the look of your site right in the panel

The theme editor is for when a ready-made theme is not enough: you want a different header, your own search page, another button colour, a separate look for one category. You cannot edit the files of ready-made themes — an engine update will replace them. So the changes go into your own theme: a ready-made theme plus only the files you changed. Everything else is taken from the ready-made theme, and its updates still reach you.

Who can edit, and when

• The site owner only. The “Appearance → Theme editor” section is visible to the owner alone; an administrator with any rights will not see it and cannot open it. Such a right cannot be granted: it is not in the rights table.
• The editor is off by default. The owner turns it on from the section page by entering a password. While it is off, theme files cannot be changed from the panel at all.
• Password. Saving a file asks for the password if you have not confirmed it in the last 5 minutes. Deleting a file, rolling back to a version, renaming, deleting a theme and turning the editor on ask for the password every time, even if you have just entered it.
• Guessing. After five wrong passwords within 15 minutes the editor stops checking the password altogether — even the right one — until the end of the window.
• The action log records who changed which file and when (path, size, a short fingerprint), but not the text of the file.

What you can edit

Only what is not executed:

Never allowed: PHP, scripts (.js), theme.json, .htaccess and anything else that is executable or unknown. Scripts are added to the site through settings and modules, not through a theme. A file name may contain lowercase Latin letters, digits, a dot, a hyphen and an underscore; folders may be at most six levels deep.

In styles, @import, addresses of other servers and expressions (expression, behavior) are forbidden; in templates, program code is. Pictures from other sites are allowed in templates, but the editor warns you: the visitor’s address will go to a third-party server.

How to start

1. Appearance → Theme editor. If the editor is off, turn it on (you will need your password).
2. Create your own theme. Pick a short name (it always starts with my-), a title, and a ready-made base theme. The new theme is at first no different from its base and does not turn on by itself.
3. Open the theme and choose a file on the left. Files of the base theme open read-only; the “Change this file” button copies the file into your theme, and the copy can be edited. “Your files” in the list on the left shows everything you have changed.
4. Make your change and click “Save”. Before saving, the template is checked (see below).
5. When the theme is ready, turn it on in Appearance → Themes just like any other. Only a theme that is not currently in use can be deleted; a deleted theme goes to the history folder and can be restored by hand if needed.

Template check

Before saving a tag file, the editor finds errors and names the line:

• an [if], [ifnot] or [each] that is not closed or is closed an extra time, blocks that are mixed up;
• [else] outside a condition or inside a list;
• a tag with a name from the forbidden list (protection keys, passwords, mail, codes, devices) — such data is never given to templates;
• a template that is too long, too many tags, nesting that is too deep;
• program code.

An error prevents saving the file. Warnings (an unknown tag — it will output nothing; what cleaning will remove at display time: scripts, on…=, javascript:; a picture from another server) do not prevent saving.

Tags: what to insert and how

To the right of the field is the tag catalogue with search: click a tag and it is placed at the cursor. Each one says what it outputs. The catalogue holds the core tags (site name, user, page, visitor, forms, menu, breadcrumbs…) and the insertable elements of modules — record lists, comments, banners and so on. The full list for each kind of page is in the “Views on tags” reference.

A few tricks:

• Conditions and lists: [if:user.logged]…[else]…[/if], [each:menu]…{item.title}…[/each].
• A date in your own format: {date=d.m.Y H:i}; the edit date: {edit-date=d.m.Y}.
• Trimming any text: {title limit=60 wordsafe=1} (by characters, without breaking a word) or {title words=10} (by words); trimmed text ends with “…”.
• Visitor: [if:visitor.mobile], [if:visitor.ios], [if:visitor.tv], {visitor.os}, [if:visitor.lang=ru], [if:visitor.country=UA].
• Role of the signed-in user: [if:user.role=editor] — by the machine name of the role, which does not depend on the site language; several can be given, separated by commas.

A template for a category

Want one category to look different? Create a second file next to the regular one, inserting the category key between the view name and .tpl.html:

• views/news/show.tpl.html — a news record for all categories;
• views/news/show.tehnika.tpl.html — a news record in the category with the key tehnika.

The same goes for the main layout: views/layouts/main.tehnika.tpl.html will replace the header and footer on the pages of this category. Other categories and pages without a category keep the regular file. The category key is its short name in the address; it works in modules that name the category of a page (news, forum, shop, downloads).

Preview, versions, comparison

• Preview. The button next to “Save” shows the draft in a closed window under the code field. Nothing is saved, scripts do not run in the window, other servers’ addresses are not loaded, and the link to the window works for 10 minutes and is tied to you and your session. The window shows a sample page with your tags and the site’s styles.
• Versions. Every save, rename and delete puts the previous text into history: up to 30 versions per file. A rollback is also a new version, so nothing is lost. A rollback asks for the password.
• Comparison. “Compare” on a version shows what changed line by line (red was, green is now). “Compare with the base theme file” shows how your file differs from the original.
• “Base changed”. If a file of the base theme changed after an engine update, your copy gets a badge. Compare and carry over what you need: nothing is replaced automatically.

If something goes wrong

• The site looks odd after an edit. Open the file → “Versions of this file” → return the previous one. Or delete your file: the site will take the base file again.
• A template is not applied. Tag files of your own theme do not replace every view: sign-in, registration and other login pages, emails, payment and orders stay as in the base, because they may contain forms with a protection key. The other views and the main layout are replaced.
• The whole theme broke. The engine returns a fallback theme by itself if your file causes an error, and tells the owner.
• Site backup. Your own themes live in storage/themes and are not included in the database backup. File versions live in storage/theme-history. Copy these folders together with the site files.
• What security says. The folders with your own themes are closed to direct access over the network; styles, pictures and icons are served by the engine through /assets with a type check, and SVG icons with scripts forbidden. If on your server the direct address /storage/themes/… suddenly serves a file, tell the server owner: it should not.