Drafts
A draft is the customizer form's values for one site, stored as the user setting design_studio_draft_<site id> of the person editing. In a preview, the draft's values replace the matching saved theme settings; settings the form does not include (such as resource page blocks) are kept. Drafts are deleted when you publish or discard, when the site is deleted, when the user is deleted, and when the module is uninstalled.
Preview pages
A preview is an ordinary page of the site requested with ?design_preview=1 by someone allowed to change the site's theme settings, on a site whose theme the customizer supports. For anyone else, the parameter does nothing. Preview pages:
- use the editor's draft;
- hide Omeka's user bar, so the page looks as it does to visitors;
- keep the parameter on links, forms and redirects within the 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/preview/<site-slug>. The address is under /admin so that caches and rate limits (such as TrafficGuard's) treat it as admin traffic; the theme is still set up as on the site's pages. The request needs the form's CSRF token and the same permission as the customizer. Values are validated by the theme's settings form; those that pass 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.
For theme developers
The preview relies on hooks in the Theme Engine's helper ($this->ThemeEngine(), declared as helpers[] = "ThemeEngine" in the theme's theme.ini):
| Hook | Purpose |
|---|---|
theme_engine.settings view event |
Filter of the saved settings (settings param) before they are resolved; the module adds the draft here. |
withSaved(array $settings) |
A copy of the helper 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()). |
CUSTOMIZER_API |
The version of these hooks; the module checks it. |
Every theme built on the Theme Engine has these hooks. Vitrine 0.4 and 0.5 have them under the helper name Vitrine, with the vitrine.settings event.