Editing Theme Files

Opening the editor#

• Appearance > Theme Files, or /admin/theme-file-editor. The public theme is selected.
• On Appearance > Themes, Edit Theme Files under the current theme, or Edit theme files under any other theme.
• A direct link to a file: /admin/theme-file-editor?theme=my-theme&source=theme&path=items/show.php. Add &line=40 to show line 40, as search results do.

The toolbar#

• Theme lists every folder of the themes folder, by title and folder name, with a note for the public theme, your copies and the read-only themes. Choosing another theme reloads the editor.
• Show chooses what the tree shows: The theme's files, or a set of views the theme can override: Omeka views (application/views/scripts) and each plugin's public and shared views (plugins/<Plugin>/views/public and views/shared). See Overriding Plugin and Core Views.
• Copy Theme… copies the selected theme. See Copying a Theme.
• Delete This Copy appears on a theme you copied, when neither the site nor an exhibit uses it.

Below the toolbar, a notice says whether the theme's files can be changed:

• Your copy of…: a theme made with Copy Theme. Its files are the site's own; theme updates never change them.
• Read-only: an installed theme, with Copy This Theme…. Installing a new version of it would replace edits, so it is read-only unless you tick it under Settings > Editable themes. A theme whose folder is a link to a folder outside the themes folder, or that the web server cannot write to, is read-only too, and the notice says so.
• A warning on an installed theme you ticked as editable, as a reminder that an update replaces its files.

The file tree#

The tree shows the folder chosen in Show; folders open when you click them. Files you can open are links:

• Templates (.php), stylesheets (.css) and scripts (.js) open in the editor, editable when the theme is.
• Other text files (theme.ini, config.ini, .scss, .md, .json, .svg and the like) open read-only. A mistake in theme.ini or config.ini breaks the Themes page and the theme's configuration form, so they are never saved here.
• Backups the editor made (*.bak) open read-only, with Delete Backup.
• Images, fonts and other files are listed, dimmed.

Marks after a name:

• a blue dot: the theme file overrides a core or plugin view (hover for which);
• a green dot, when showing views to override: the theme has its own copy of the view;
• an arrow: the file is a link to a file outside the theme (Theme Engine themes link their templates to the engine's). It opens read-only, since other themes share it: copy the theme to get files of its own.

Hidden files (names starting with a dot) are not listed, nor links that point outside the theme, the Omeka installation and the folder holding the themes folder. The ↻ button reloads the tree.

The file#

Clicking a file opens it. The header shows its path, Editable or Read-only, its size, when it was modified, its latest revision and its SHA-256 checksum, and Revision History once it has revisions. When the file overrides a core or plugin view, a box names it, with Compare to see how the theme's version differs from it. When it is read-only, a notice says why.

The editor highlights PHP with HTML, CSS, JavaScript and the other file types, and shows line numbers.

Leaving a file with unsaved changes asks first.

Saving#

1. Make your changes.
2. Optionally say What changed, up to 255 characters; it is shown in the revision history.
3. Optionally tick Keep a backup file to keep a copy of the old file next to it.
4. Click Save, or press Ctrl+S / Cmd+S.

The status shows Saved: revision #N. A save:

1. checks that the theme is editable and that the path is an existing template, stylesheet or script inside the theme folder, not a link out of it;
2. refuses content larger than Largest file;
3. does nothing when the content has not changed (No changes to save.);
4. counts the save against Saves a minute;
5. checks the PHP of a .php file when Check PHP before saving is on;
6. stores the file's current content first when the history does not have it: the original before its first change, or a change made outside the editor;
7. writes the backup file when asked, then the file;
8. stores the new revision, deletes the file's oldest revisions beyond Revisions per file, and fires the plugin's hooks (see Hooks and Integration).

The editor cannot create or delete theme files, except backups and through Copy to Theme.

Syntax errors#

When the check finds an error in a template, nothing is saved and a notice above the editor shows PHP's message with the line number. Fix it and save again, or tick Save anyway, despite the error and save.

PHP's own parser checks the code first, in the PHP version that runs the site; then, where the server allows exec(), php -l runs too and catches the rarer compile errors (a break outside a loop, a parameter named twice). An error in a template breaks the pages that use it, and an error in custom.php or functions.php breaks every public page: if that happens, roll back from the revision history.

Backups#

A backup is a copy of the file as it was before the save, named <file>.<YYYYMMDDHHMMSS>.bak in the same folder. The revision history already keeps every version, so backups are only an extra copy on disk. They are ordinary files: a web server shows them to anyone who knows their name, so do not keep secrets in theme files, and delete backups you no longer need (open one and click Delete Backup).