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

Темите работят върху стандартизиран слой от данни (ViewData), предоставен от CMS. Темата не комуникира директно с базата данни или CMS класове.

Създаването на нова тема започва със създаването директория на темата в папка /themes/ms/... и записването на основния index.php файл в нея.

Файлът index.php зарежда engine bootstrap /themes/ms/_bootstrap.php, инициализира ViewData и използва предоставения обект $o_page за достъп до CMS hooks.

Темата се регистрира в CMS чрез запис в таблица Templates. Това я прави достъпна за конкретен сайт (SiteID) или за всички сайтове (SiteID = 0).

CSS/JS активите се управляват централизирано чрез cms_assets.php, което предотвратява дублиране на зависимости и осигурява контрол на версиите.

---

/themes – Official Theme Architecture Spec (v1.3)

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

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

• теми, групирани по engine (renderer)
• споделени helpers и assets на ниво engine
• теми, които работят със ViewData

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

---

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

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

• ❌ темите не четат база
• ❌ не инстанцират CMS класове
• ❌ не съдържат бизнес логика
• ✅ рендерират подадени данни

---

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

/themes
    /ms
    /wp
    /joomla

Engine определя:

• формата на ViewData
• helpers
• asset registry
• render conventions

---

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

/themes/ms

    /base
    /components
    /helpers
    /blocks

    _bootstrap.php
    cms_assets.php
    functions.php

_bootstrap.php

• инициализира theme runtime
• зарежда helpers
• зарежда engine functions

пример:

require_once __DIR__.'/helpers/block_dom.php';

cms_assets.php

• дефинира CSS/JS зависимости за engine-а
• Bootstrap, Tailwind, Alpine и др.
• използва се от всички теми

functions.php

• engine helpers
• hooks
• филтри
• НЕ е theme-specific

/helpers

• shared helper функции
• block_dom.php
• meta_tags.php
• breadcrumbs.php
• pagination.php

/blocks

• default CMS block templates
• fallback ако темата няма собствен template

пример:

/themes/ms/blocks

    text.php
    image.php
    subpages.php

---

5. Theme-level структура

/themes/ms/base/none

    theme.json
    index.php

    /blocks
        text.php
        image.php
        subpages.php

    /js
        theme.js
        /blocks
            gallery.js
            hero.js

    /css
        theme.css

    header.php
    footer.php

Theme index.php е основният render файл.

---

6. ViewData структура

view

 ├ context
 ├ auth
 ├ user
 ├ user_context
 ├ site
 ├ page
 │   └ streams
 │       └ main
 │           └ items[]
 └ theme

Blocks се намират в:

$page['streams']['main']['items']

Всеки блок съдържа:

[
    id
    type
    data
    dom
]

---

7. Block Rendering

Block rendering се управлява от BlockResolver.

Theme index.php извиква:

BlockResolver:

• чете $page['streams']['main']['items']
• намира block template
• рендерира HTML

Template resolution:

theme/blocks/{pageType}/{block}.php
theme/blocks/{block}.php
themes/ms/blocks/{pageType}/{block}.php
themes/ms/blocks/{block}.php

---

8. DOM Integration (CMS → Theme JS API)

CMS добавя стандартни DOM markers:

data-block
data-id
data-editable

DOM markers се генерират чрез helper:

block_dom($block)

пример:

<section>

резултат:

DOM markers са официалният JS API между CMS и темата.

---

9. JavaScript Block Lifecycle

Темите инициализират JS блокове чрез DOM markers.

document.querySelectorAll("[data-block]").forEach(el => {

    const type = el.dataset.block

    if (Theme.blocks[type]) {
        Theme.blocks[type](el)
    }

})

Пример:

Theme.blocks.gallery = function(el) {

    console.log("Gallery init", el.dataset.id)

}

---

10. Recommended Theme JS Structure

/themes/ms/themeX

    /js
        theme.js
        /blocks
            gallery.js
            hero.js

Пример runtime:

window.Theme = window.Theme || {}
Theme.blocks = {}

---

11. ContentTools Integration

CMS маркира editable области чрез:

data-editable

ContentTools се инициализира върху:

*[data-editable]

---

12. Theme configuration (theme.json)

theme.json е незадължителен конфигурационен файл. CMS използва overwrite cascade.

Използва се първият намерен theme.json, тръгвайки от директорията на темата нагоре.

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

---

13. Theme Development Checklist

• Създайте директория в /themes/ms/
• Добавете index.php
• Заредете /themes/ms/_bootstrap.php
• Използвайте $o_page->hook('main_content')
• Добавете block templates в /blocks
• Използвайте block_dom($block)
• Инициализирайте JS чрез Theme.blocks

---

14. Key Principles

• Single page object ($o_page)
• CMS → data layer
• Theme → presentation layer
• Blocks се подават като streams
• Theme контролира layout
• DOM markers са JS integration API
• Page cache кешира крайния HTML

---

15. Status

• Version: v1.3
• Change: BlockResolver + DOM helper
• Backward compatible: Да
• Runtime cost: минимален

---

16. Theme Runtime Flow

HTTP Request
      ↓
page.php
      ↓
loader.php
      ↓
$o_page->init_page_blocks()
      ↓
PageData
      ↓
ThemeMapper
      ↓
ViewData
      ↓
resolveTheme()
      ↓
include theme/index.php
      ↓
$o_page->hook('main_content')
      ↓
BlockResolver
      ↓
block templates
      ↓
HTML output
      ↓
page cache

Theme получава готов ViewData и е отговорна само за визуализацията.

Основният принцип е:

CMS управлява данните → Theme управлява HTML и визуализацията