Максофт е основа на headless CMS система и целта на бъдещия рендерер на теми е да осигури лесна адаптация и визуализация на сайтове създадени както за legacy Maksoft CMS, така и нови дизайни и теми писани за Maksoft CMS, Wordpress, Joomla и т.н. 

/themes – Official Theme Architecture Spec (v1)

1. Цел на директорията /themes

/themes е новият стандартен слой за рендериране в CMS-а.

Тя съдържа:

• теми, групирани по engine (renderer / CMS adapter)

• споделени helpers, assets и функции на ниво engine

• теми, които работят с ViewData, а не директно с базата или CMS API

/themes НЕ замества legacy /Templates, а съществува паралелно.

 

2. Основен принцип

CMS подава ViewData → Theme engine рендерира → Theme решава структурата

Темите:

• ❌ не четат база

• ❌ не инстанцират CMS класове

• ❌ не съдържат бизнес логика

• ✅ рендерират подадени данни
  
  

3. Йерархия на директориите

 

• всяка подпапка е engine / renderer

• engine определя:

  • формата на ViewData

  • helpers

  • assets

  • conventions

 

/themes

/ms
/wp
/joomla
/tailwin

 

4. Engine-level структура (пример: /themes/ms)

 

Описание:

cms_assets.php

• дефинира CSS/JS зависимости за engine-а

• Bootstrap, Tailwind, Alpine, etc.

• използва се от всички теми в engine-а

functions.php

• engine-level helpers

• hooks

• филтри

• НЕ е theme-specific

/helpers

• споделени partial-и:

  • meta_tags.php

  • breadcrumbs.php

  • pagination.php

/components

• reusable view components:

  • header.php

  • navigation.php

  • subpages.php

  • footer.php

 

5. Theme-level структура (пример: /themes/ms/base/none)

6. Theme configuration (theme.json) – overwrite resolution

6.1 Статус на theme.json

• theme.json е НЕзадължителен

• темата може да работи без собствен theme.json

• конфигурацията се определя чрез overwrite cascade

---

6.2 Правило за overwrite (основно правило)

Използва се първият намерен theme.json, тръгвайки от директорията на темата нагоре.
НЯМА merge между конфигурации.

• няма наследяване по ключове

• няма сливане на масиви

• няма частични override-и

➡️ Един файл = един източник на истина

6. Theme configuration (theme.json) – overwrite resolution

6.1 Статус на theme.json

• theme.json е НЕзадължителен

• темата може да работи без собствен theme.json

• конфигурацията се определя чрез overwrite cascade

---

6.2 Правило за overwrite (основно правило)

Използва се първият намерен theme.json, тръгвайки от директорията на темата нагоре.
НЯМА merge между конфигурации.

• няма наследяване по ключове

• няма сливане на масиви

• няма частични override-и

➡️ Един файл = един източник на истина

 

6.3 Алгоритъм за търсене на theme.json

При theme path:

/themes/ms/base/none

CMS търси theme.json в следния ред:

1. /themes/ms/base/none/theme.json

2. /themes/ms/base/theme.json

3. /themes/ms/theme.json

4. /themes/theme.json (по избор, global fallback)

Търсенето СПИРА:

• при първия намерен theme.json

• или при достигане на /themes

• или при достигане на filesystem root /

➡️ Никога не се преминава над /themes, за да няма зацикляне или неочаквани конфигурации.

 

6.4 Какво означава overwrite на практика

Примерна структура:

/themes/ms/theme.json
/themes/ms/base/theme.json
/themes/ms/base/none/index.php

/themes/ms/theme.json
/themes/ms/base/theme.json
/themes/ms/base/none/index.php

6.5 Какво НЕ се прави

• ❌ няма merge между конфигурации

• ❌ няма implicit inheritance

• ❌ няма runtime override

• ❌ темата НЕ знае откъде идва конфигурацията

Всичко се resolve-ва в resolveTheme().

6.6 Връзка с engine-level файлове

• cms_assets.php и functions.php се зареждат на ниво engine
  (напр. /themes/ms/)

• те НЕ участват в overwrite логиката

• всички подтеми автоматично ги използват

theme.json контролира поведение, не файлова логика.

6.6 Връзка с engine-level файлове

• cms_assets.php и functions.php се зареждат на ниво engine
  (напр. /themes/ms/)

• те НЕ участват в overwrite логиката

• всички подтеми автоматично ги използват

theme.json контролира поведение, не файлова логика.

 

7. Статус на спецификацията

• Version: v1.1

• Change: overwrite cascade вместо merge

• Backward compatible: Да

• Runtime cost: минимален