Copying a Theme

Why copy a theme#

A theme you install, from the hosting dashboard, the Omeka add-ons directory or a zip of your own, is replaced when you install a new version of it: the new files are written over the old ones, and any edit made to them is lost. On RefBytes hosting, the dashboard unzips the new version over the theme's folder; a theme folder with another name is never touched.

So Theme File Editor edits the themes that are the site's own. Copy Theme makes a complete copy of an installed theme under a new folder name; the copy is yours, theme updates never change it, and the editor lets you change its files. Installed themes open read-only, with Copy This Theme….

A copy is also the way to experiment: make changes in a copy while the site keeps using the original, then switch.

Copying#

1. Open Appearance > Theme Files and choose the theme in Theme.
2. Click Copy Theme… in the toolbar (or Copy This Theme… in the read-only notice).
3. In the dialog:
   • Folder name: the new folder in themes/, up to 30 letters, numbers, hyphens and underscores (30 is the longest theme name an exhibit can use). It must not be the name of an existing theme, in any case.
   • Title: the name shown under Appearance > Themes.
   • Copy the theme's configuration too: copies its Configure Theme settings (logo, colors and the rest) to the copy. Leave it ticked to get the same look.
4. Click Copy.

The editor then:

• copies every file of the theme to themes/<folder name>/, as files of its own: a link in the theme (Theme Engine themes link their templates and their engine folder to the shared Theme Engine) is replaced by a copy of what it points to, so the copy's templates and engine are all editable and nothing is written to files other themes share. Links pointing elsewhere, broken links and links to a folder holding the theme are left out and listed in a message. Version control folders (.git) and .DS_Store files are not copied;
• writes the new title in the copy's theme.ini;
• copies the configuration when asked;
• records the copy as yours, and reloads the editor on it.

The copy is written to a hidden temporary folder and renamed when complete, so a failure (a full disk, a file that cannot be read) leaves nothing behind. The whole theme is measured first: a copy larger than 256 MB or 20,000 files is refused.

To use the copy on the site, choose it under Appearance > Themes. Exhibits with a theme of their own can use it too.

Theme Engine copies#

A copy of Vitrine, Plinth, Confetti or Overprint holds its own copy of the Theme Engine, at the version the original had. Updating the original theme, or the engine, does not change the copy: that is the point of a copy. To take a later version, copy the updated theme again and redo your changes; the revision history and Compare help you find them.

Deleting a copy#

On a theme you copied, Delete This Copy deletes its folder, its revision history and its configuration, after you confirm. It is shown only when neither the site (the public theme) nor an exhibit uses the copy; choose another theme first. Installed themes are never deleted by the editor.

Requirements and limits#

• The web server must be able to write to the themes folder, or the copy fails with The web server cannot write to the themes folder.
• After uninstalling and installing the plugin again, the list of your copies is gone: tick them under Settings > Editable themes to edit them again. They can then be edited but not deleted from the editor.