Skip to content

Theme Settings Engine

Это перевод английского документа docs/theme-settings-engine.md. Английская версия является source of truth. Если перевод противоречит английскому документу, английский документ имеет приоритет.

Purpose

Теме Shop3 нужен один поддерживаемый admin centre для theme configuration, без чтения множества database settings на каждый storefront request.

Этот документ описывает архитектуру будущего Theme Settings Engine. Это design document only; implementation сейчас не вводится.

Reference UX Notes

Centralised settings UX patterns из reference themes рассматривались только как internal research. Полезные generic patterns:

  • одна central theme settings page;
  • left sidebar sections для быстрой навигации;
  • grouped settings вместо scattered module pages;
  • overview module placement;
  • понятные actions для save, reset/back и cache clearing.

Не копировать third-party code, storage, routes, naming или vendor-specific implementation. Shop3 должен следовать canonical OpenCart conventions.

Goals

  • Все theme settings доступны из одного admin controller/page.
  • Settings разделены на independent sections.
  • Сохраняется только current section.
  • Settings используют namespace prefix shop3_.
  • Storefront не делает repeated database reads.
  • Поддерживается OpenCart multi-store configuration.
  • Schema, naming, section model и cache strategy должны быть portable для будущего OpenCart 4 layer.

Sections

Initial sections:

  • general
  • header
  • footer
  • home
  • category
  • product
  • checkout
  • stickers
  • typography
  • colors
  • performance
  • custom_css_js
  • integrations

Technical identifier colors сохраняется как часть approved design.

Namespaced Keys

Settings используют shop3_ prefix и section-based keys:

shop3_theme_general
shop3_theme_header
shop3_theme_footer
shop3_theme_home
shop3_theme_category
shop3_theme_product
shop3_theme_checkout
shop3_theme_stickers
shop3_theme_typography
shop3_theme_colors
shop3_theme_performance
shop3_theme_custom_css_js
shop3_theme_integrations

Keys сохраняются per store_id через OpenCart settings system where appropriate.

Data Model

Default persistence layer для OC3 — OpenCart setting/setting model.

Рекомендуемый stored value per section:

{
  "version": 1,
  "updated_at": "2026-06-08T00:00:00Z",
  "settings": {}
}

Database должна хранить explicit section values for each store. Defaults живут в code и не дублируются в database rows без необходимости.

Admin UI Structure

Canonical future route:

extension/theme/shop3

Canonical OC3 controller file:

admin/controller/extension/theme/shop3.php

Recommended UI:

  • standard OpenCart admin header/footer and breadcrumbs;
  • left sidebar with section navigation;
  • main panel with one active section form;
  • save current section;
  • reset current section;
  • dirty state indicator;
  • preview/storefront link;
  • optional cache clear action;
  • module placement overview separately from raw theme configuration.

Save Strategy

Use a single controller action with a section parameter unless separate endpoints are simpler:

admin/index.php?route=extension/theme/shop3/save&section=header&user_token=...

Save flow:

  1. verify user_token;
  2. verify modify permission for extension/theme/shop3;
  3. read store_id, default 0;
  4. read only submitted section payload;
  5. validate the section;
  6. merge submitted values with defaults;
  7. persist only that section key for that store_id;
  8. invalidate cache for that section/store;
  9. redirect back with success or error state.

Do not resave unrelated sections.

Partial Persistence

Partial save is mandatory. Saving header changes only shop3_theme_header for selected store_id.

Validation failure must not overwrite existing stored values. Reset current section affects only the selected section.

Read and Cache Strategy

Storefront should load all shop3_theme_* values once for the current store_id, merge with defaults, expose an aggregate config via helper/service, cache it per store, and invalidate cache only after relevant section save/reset/cache clear.

Conceptual API:

shop3_config.get('header.logo_mode')
shop3_config.section('performance')

Cache key should include at least:

shop3.theme_config.store_{store_id}

Add language_id or currency only when resolved values truly differ.

Multi-store Awareness

  • store_id = 0 is the default store.
  • Each saved section belongs to one store_id.
  • Unsaved stores inherit code defaults unless inheritance is explicitly added later.
  • UI must show which store is being edited.
  • Partial save must not overwrite another store's values.

File Structure Proposal

admin/controller/extension/theme/shop3.php
admin/language/en-gb/extension/theme/shop3.php
admin/view/template/extension/theme/shop3.twig
catalog/model/extension/theme/shop3.php
catalog/controller/extension/theme/shop3.php

catalog/controller/extension/theme/shop3.php should exist only if controller behaviour is genuinely needed.

Anti-patterns

Do not:

  • create one huge unstructured setting blob;
  • save all sections on every submit;
  • read dozens of database settings repeatedly on storefront requests;
  • copy third-party internals;
  • edit OpenCart core files;
  • mix module placement with theme configuration without clear boundary;
  • add dependencies without PR Notes justification;
  • add build pipeline as part of settings engine design.

Open Questions

  • Where should defaults live during implementation?
  • Should admin sections be one rendered page or lazy-loaded?
  • How should multilingual text settings be stored?
  • Should cache use OpenCart cache only or also generated config for hot paths?