Drafts
A draft is kept for one person and one theme, in the plugin's table design_studio_drafts. It holds the settings that person changed in the customizer, and the images they uploaded that are not published yet. In a preview, the draft's values replace the matching saved theme settings; the others are the published ones. Drafts are deleted when you publish or discard, when the user is deleted, and when the plugin is uninstalled.
Preview pages
A preview is an ordinary public page requested with ?design_preview=1 by someone allowed to configure themes, while the public theme is one the customizer supports. For anyone else, the parameter does nothing. Preview pages:
- use the editor's draft (an exhibit with a theme and settings of its own keeps them);
- hide Omeka's admin bar, so the page looks as it does to visitors;
- keep the parameter on links, forms and redirects within the public site;
- are sent with
Cache-Control: no-storeandX-Robots-Tag: noindex, so no cache or search engine keeps them.
Updates
While you work, the customizer sends the form to POST /admin/design-studio/index/update. The address is under /admin so that caches and rate limits treat it as admin traffic. The request needs Omeka's session token and the same permission as the customizer. Values are validated by the theme's settings form, the same form Configure Theme uses; HTML settings go through Omeka's HTML filter. Values that pass and differ from the published ones become the draft. The answer (JSON) carries the new token and custom CSS, the theme's body classes and attributes, a render key (which changes only when a reload setting changes), the effective value of each setting, the settings that differ from the published ones, and validation messages.
Images go to POST /admin/design-studio/index/upload, are checked as on Configure Theme (PNG, JPG or GIF, up to 1 MB unless file validation is turned off in Settings › Security) and stored in files/theme_uploads under a new name. The draft holds that name.
Publishing
Publishing validates the whole form with your draft's values and saves the theme's settings as Configure Theme does (Theme::setOptions(), the option theme_<theme>_options). Images are saved by file name; an image that is replaced is deleted unless another setting still shows it.
For theme developers
The preview relies on the Theme Engine's customizer API (Engine::CUSTOMIZER_API, version 1). A theme is supported when themes/<theme>/engine/src/Engine.php exists and offers that version; the plugin loads the theme's own copy of the engine in the admin.
| Hook | Purpose |
|---|---|
theme_engine_settings filter |
Filter of the saved settings (apply_filters('theme_engine_settings', $saved, ['theme' => <folder>])) before they are resolved; the plugin adds the draft here. |
resolve(array $saved) |
Effective settings: saved value, else the preset's, else the config.ini default, else the theme's fixed value. |
withSaved(array $settings) |
A copy of the engine that reads other settings. |
livePreview() |
Token and custom CSS, body classes, <html> attributes and header and footer data attributes for the current settings. |
renderKey() |
Fingerprint of the settings livePreview() cannot apply (all but liveSettings()). |
liveSettings() |
The engine's live settings, and the theme's own (live_settings in config/design.php). |
CUSTOMIZER_API |
The version of these hooks; the plugin checks it. |
Every theme built on the Theme Engine has these hooks.