bagisto-theme-sections

Theme Sections

packages/Webkul/Theme owns the Appearance area: the theme gallery, and the sections a theme's storefront is built from. Sections replaced the old settings/themes CRUD — the routes are gone, and a section is now edited beside a live preview rather than on a form of its own.

Reference files

File	Load when
drafts.md	The staging model — what is held, what publishing does, the preview
sections.md	Section types, the field schema, media, and the rules per type

Where things live

Path	What
admin/appearance/themes	The gallery — installed themes and ones on offer
admin/appearance/themes/{code}/sections	The editor for one theme, on one channel
appearance-preview (shop)	The storefront rendered from drafts, framed in the editor

ThemeCatalog supplies the gallery and answers isInstalled() / isActive(); SectionSchema resolves the section types a theme offers and their field schema; SectionRepository owns every read and write.

Nothing goes live until it is published

This is the rule the whole area is built on. Every change is staged — editing content, toggling a section on or off, and dragging it to a new position. Each is held on the row and applied only when the operator publishes:

Change	Held in
Content, per locale	theme_section_translations.draft_options
On/off	theme_sections.draft_status
Order	theme_sections.draft_sort_order

A draft column is nulled when it would equal the live value, so toggling a section off and back on leaves nothing staged rather than an empty pending change. hasDraft() is true when any of the three is set, and that is what the editor's unsaved-changes count and per-row dot read.

publishDraft() promotes all three and then purges media the published options no longer reference; discardDraft() clears all three and purges the same way.

Non-negotiables

• The storefront reads live values, the preview reads drafts. The switch is SectionRepository::PREVIEWING, set in the request's internal attribute bag — never from a query parameter, or a visitor could ask a storefront page for unpublished content. Use getRenderable() for the storefront and getDraftedForPreview() for the preview; do not branch on the flag yourself.
• The preview is admin-only. appearance-preview aborts unless bouncer()->hasPermission('appearance.sections') — an authenticated admin without that permission is not enough.
• Sanitise on the way in. The repository's sanitizeOptions() hands options to the type's sanitize() — StaticContent runs sanitizeHtml() (Purify) and sanitizeCss() — on the draft, publish and preview paths. A new write path must go through sanitizeOptions().
• Only an active theme is customized. The editor and every section action refuse a theme its channel does not run — server-side, not only by hiding Customize in the gallery.
• Section types are theme-aware. Resolve them through SectionSchema::types() or $section->getTypeInstance(), never a hardcoded list or raw string.
• One footer per channel. footer_links is a singleton, guarded server-side in the controller — not only by hiding the type in the UI.
• Clear the page cache on every change. FPC listens to section.create.after, section.update.after and section.delete.before; a type whose rendersInLayout() is true (footer_links, services_content, or a theme's own $layout type) clears the whole cache rather than just the home page.
• Fire before and after events. Every action dispatches a pair — section.create.*, section.update.*, section.delete.*, section.draft.save.*, section.draft.discard.*, section.media.upload.*, section.reorder.*. A new action needs both, or FPC and third-party listeners miss it.
• Guard against a section deleted in another tab. Every action resolves through sectionOrFail() and answers with a plain "no longer exists" rather than a 500.
• A section's media directory is removed by SectionObserver on delete, not by the controller.

REQUIRED SUB-SKILL: Use bagisto-change-verification before calling any change done.