bagisto-theme-sections

テーマセクション

packages/Webkul/Theme は 外観 エリアを担当します。テーマギャラリーと、テーマのストアフロントを構成するセクションです。セクションは従来の settings/themes CRUD に代わるもので、ルートはなくなり、セクションは専用フォームではなくライブプレビューの横で編集するようになりました。

参照ファイル

ファイル	読み込むタイミング
drafts.md	ステージングモデル — 保留されるもの、公開時の処理、プレビュー
sections.md	セクションの種類、フィールドスキーマ、メディア、種類ごとのルール

各機能の場所

パス	内容
admin/appearance/themes	ギャラリー — インストール済みのテーマと提供中のテーマ
admin/appearance/themes/{code}/sections	1つのチャネルにおける、1つのテーマのエディター
appearance-preview (ショップ)	下書きからレンダリングされ、エディター内に表示されるストアフロント

ThemeCatalog はギャラリーを提供し、isInstalled() / isActive() に応答します。SectionSchema はテーマが提供するセクションの種類とそのフィールドスキーマを解決します。SectionRepository はすべての読み取りと書き込みを担います。

公開するまで、何も反映されません

エリア全体はこのルールに基づいています。コンテンツの編集、セクションのオン／オフの切り替え、新しい位置へのドラッグなど、すべての変更はステージングされます。それぞれ行に保留され、オペレーターが公開したときにのみ適用されます。

変更	保留先
ロケールごとのコンテンツ	theme_section_translations.draft_options
オン／オフ	theme_sections.draft_status
順序	theme_sections.draft_sort_order

下書き列は、公開値と同じになる場合はNULLにされます。そのため、セクションをオフにしてから再びオンにしても、空の変更が保留されるのではなく、ステージングされた内容は残りません。3つのいずれかが設定されている場合、hasDraft() は true を返します。これが、エディターの未保存変更数と各行のドット表示に使われます。

publishDraft() は3つすべてを反映し、その後、公開済みのオプションから参照されなくなったメディアを削除します。discardDraft() は3つすべてをクリアし、同じ方法でメディアを削除します。

絶対に守るべき事項

• ストアフロントでは公開中の値を、プレビューでは下書きを読み込みます。 切り替えにはリクエストの 内部属性バッグ に設定する SectionRepository::PREVIEWING を使用します。クエリパラメーターから設定してはいけません。そうすると、訪問者がストアフロントのページで未公開コンテンツを要求できてしまいます。ストアフロントでは getRenderable() を、プレビューでは getDraftedForPreview() を使用し、フラグに応じた分岐を独自に行わないでください。
• プレビューは管理者専用です。 appearance-preview は bouncer()->hasPermission('appearance.sections') を満たさない場合に処理を中断します。この権限を持たない認証済み管理者では不十分です。
• 入力時にサニタイズします。 リポジトリの sanitizeOptions() は、下書き、公開、プレビューの各経路でオプションをタイプの sanitize() に渡します。StaticContent では sanitizeHtml()（Purify）と sanitizeCss() が実行されます。新しい書き込み経路では sanitizeOptions() を経由する必要があります。
• カスタマイズできるのは有効なテーマだけです。 エディターと各セクションアクションは、チャネルで実行されていないテーマを拒否します。ギャラリーで「カスタマイズ」を非表示にするだけでなく、サーバー側で拒否してください。
• セクションタイプはテーマに対応します。 ハードコードされたリストや生の文字列ではなく、SectionSchema::types() または $section->getTypeInstance() を通して解決してください。
• チャネルごとにフッターは1つだけです。 footer_links はコントローラーでサーバー側のシングルトンとして制限します。UIでタイプを非表示にするだけでは不十分です。
• 変更のたびにページキャッシュを消去します。 FPC は section.create.after、section.update.after、section.delete.before を監視します。rendersInLayout() が true のタイプ（footer_links、services_content、またはテーマ独自の $layout タイプ）の場合、ホームページだけでなくキャッシュ全体を消去します。
• 変更前後のイベントを発火します。 各アクションは一組のイベントをディスパッチします。section.create.*、section.update.*、section.delete.*、section.draft.save.*、section.draft.discard.*、section.media.upload.*、section.reorder.* です。新しいアクションには両方が必要です。そうしないと、FPC とサードパーティーのリスナーがイベントを受け取れません。
• 別のタブで削除されたセクションに対処します。 各アクションでは sectionOrFail() を通してセクションを解決し、500 エラーではなく、通常の「すでに存在しません」という応答を返してください。
• セクションのメディアディレクトリはコントローラーではなく、削除時に SectionObserver が削除します。

必須のサブスキル： 変更を完了したと判断する前に、bagisto-change-verification を使用してください。