Максофт е основа на 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.4)

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

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

• Съдържа теми, групирани по engine / renderer.
• Осигурява споделени helpers и assets на ниво engine.
• Позволява темите да работят със стандартизиран ViewData слой.

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

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

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

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

3. Основна ViewData структура

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

streams.main.items съдържа основните content blocks на страницата.

streams.subpages съдържа relation stream с подстраниците. Темата решава къде да го визуализира.

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

/themes
    /ms
    /wp
    /joomla

Всеки engine определя:

• формата на ViewData;
• helpers;
• asset registry;
• render conventions;
• default blocks и components.

5. Engine-level структура: /themes/ms

/themes/ms
    _bootstrap.php
    theme.json
    cms_assets.php
    functions.php

    /helpers
        block_dom.php
        meta_tags.php
        footer_inc.php
        breadcrumbs.php

    /blocks
        text.php
        image.php

    /components
        menu.php
        navigation.php
        subpages.php

    /base
        theme.json
        /none
            theme.json
            index.php
            meta_tags.php
            footer_inc.php

            /blocks
                text.php
                image.php

            /components
                menu.php
                navigation.php
                subpages.php

            /layout
                head.php
                header.php
                footer.php
                scripts.php

            /partials
                menu.php
                breadcrumbs.php
                banners.php

            /assets
                /css
                /js
                    theme.js
                    /blocks
                        text.js
                        image.js
                    /components
                        subpages.js
                /images

            README.md

6. Blocks

Blocks са основните content елементи на страницата.

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

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

Всеки block съдържа:

[
    'id'   => 1,
    'type' => 'text',
    'data' => [...],
    'dom'  => [
        'data-block'    => 'text',
        'data-id'       => '1',
        'data-editable' => '0'
    ]
]

Blocks се рендерират чрез:

BlockResolver чете $page['streams']['main']['items'], намира подходящия template и връща HTML.

Block template resolution

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

7. Components

Components са визуални елементи, които не са задължително част от основния body content.

Примери:

• menu;
• navigation;
• breadcrumbs;
• subpages;
• banners;
• footer elements.

Components позволяват на темата да контролира къде точно се рендерира даден елемент.

8. Subpages contract

Subpages не се добавят автоматично в streams.main.items.

Официалният source за подстраници е:

$page['streams']['subpages']

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

$page['streams']['subpages'] = [
    'id'      => 'children',
    'name'    => 'subpages',
    'kind'    => 'relation',
    'binding' => 'strong',
    'role'    => 'subpages',
    'display' => [
        'enabled'  => 1,
        'layout'   => 'auto',
        'columns'  => 3,
        'elements' => ['image', 'title', 'excerpt'],
        'links'    => 'full',
        'limit'    => null,
        'order'    => 'manual'
    ],
    'items' => [...]
];

Темата рендерира subpages чрез:

Това позволява на темата да избере дали подстраниците да се покажат:

• след основния текст;
• преди основния текст;
• в отделна секция;
• в sidebar;
• в slider;
• в grid/gallery зона.

Default renderer-ът за subpages се намира в:

/themes/ms/components/subpages.php

Темата може да го презапише чрез:

theme/components/subpages.php

9. Main content и subpages

main_content и sub_pages са отделни render hooks.

Препоръчителна структура в тема:

<main>
    <?= $o_page->hook('main_content') ?>
    <?= $o_page->hook('phpcode') ?>
    <?= $o_page->hook('sub_pages') ?>
    <?= $o_page->hook('pageurl') ?>
</main>

Така темата запазва контрол върху реда и мястото на отделните секции.

10. DOM Integration

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

data-block
data-id
data-editable

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

block_dom($block)

Пример:

<section<?= block_dom($block) ?>>
    ...
</section>

Резултат:

<section data-block="text" data-id="1" data-editable="0">
    ...
</section>

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

11. JavaScript lifecycle

Темите могат да инициализират JS поведение чрез DOM markers.

document.querySelectorAll("[data-block]").forEach(function(el) {
    var type = el.getAttribute("data-block");

    if (window.Theme && Theme.blocks && typeof Theme.blocks[type] === "function") {
        Theme.blocks[type](el);
    }
});

Пример:

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

Theme.blocks.text = function(el) {
    console.log("Text block init", el.getAttribute("data-id"));
};

За components може да се използва отделен namespace:

window.Theme = window.Theme || {};
Theme.components = Theme.components || {};

Theme.components.subpages = function(el) {
    console.log("Subpages component init", el.getAttribute("data-id"));
};

12. Assets

Assets се управляват на две нива.

Engine-level

/themes/ms/cms_assets.php

Дефинира споделени зависимости:

• Bootstrap;
• Tailwind;
• Alpine;
• Core JS runtime;
• общи component styles.

Theme-level

theme/assets/css
theme/assets/js
theme/assets/images

Темите не трябва да enqueue-ват assets директно в templates. Те използват asset registry и hooks.

13. 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

14. Maksoft Template Language (MTL)

Maksoft Template Language (MTL) е compatibility и extension слой върху стандартните PHP templates.

MTL позволява legacy PHP include файлове като edit.php, PageURL и phpCode да декларират JavaScript, CSS и други embedded code blocks без да нарушават нормалното PHP изпълнение.

MTL не заменя PHP. Legacy Maksoft CMS PHP остава валиден execution layer.

Directive marker

<!-- @push('js') -->
<script>
$j(document).ready(function(){
    // Legacy JavaScript code
});
</script>
<!-- @endpush -->

MTL-aware engine премества този блок към:

Asset declaration

<!-- @asset('jquery') -->
<!-- @asset('jquery-alias-j') -->
<!-- @asset('fancybox') -->

Engine behavior:

$o_page->add_asset('jquery');
$o_page->add_asset('jquery-alias-j');
$o_page->add_asset('fancybox');

15. Theme development checklist

• Създайте директория в /themes/ms/....
• Добавете index.php.
• Заредете /themes/ms/_bootstrap.php.
• Използвайте $o_page->hook('main_content') за основните blocks.
• Използвайте $o_page->hook('sub_pages'), ако темата трябва да показва подстраници.
• Добавете block overrides в /blocks само за основни content blocks.
• Добавете component overrides в /components за menu, navigation, subpages и други relation/render components.
• Използвайте block_dom($block) за DOM markers.
• Инициализирайте JS чрез Theme.blocks и/или Theme.components.

16. Key principles

• Single page object: $o_page.
• CMS управлява data layer.
• Theme управлява HTML и визуализацията.
• Blocks са част от streams.main.items.
• Subpages са отделен relation stream: streams.subpages.
• Theme контролира layout и позициониране.
• DOM markers са JS integration API.
• Page cache кешира крайния HTML.

17. 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
      ↓
$o_page->hook('sub_pages')
      ↓
Subpages component renderer
      ↓
HTML output
      ↓
page cache

18. Status

• Version: v1.4
• Change: ViewData streams contract, BlockResolver, Components, Subpages relation stream, DOM helper.
• Backward compatible: Да.
• Runtime cost: минимален.

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

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

<!-- @push('js') -->
<script type="text/javascript">
$j(document).ready(function(){
    // Legacy JavaScript code
});
</script>
<!-- @endpush -->

<!-- @push('css') -->
<style>
.edit-page-form {
    margin-top: 10px;
}
</style>
<!-- @endpush -->

<!-- @asset('jquery') -->
<!-- @asset('jquery-alias-j') -->
<!-- @asset('fancybox') -->

$o_page->add_asset('jquery');
$o_page->add_asset('jquery-alias-j');
$o_page->add_asset('fancybox');

main_content
→ include(edit.php)
→ HTML + PHP + CSS + JS render inline

main_content
→ capture include output
→ extract @push blocks
→ render remaining HTML/PHP

head
→ hook('css')

footer
→ render_assets('js')
→ hook('js')

<!-- @lang('twig') -->
...
<!-- @endlang -->

<!-- @lang('scss') -->
...
<!-- @endlang -->