Інструкція для розробки модулів або шаблонів для OkayCMS

Як викласти модуль на маркетплейс OkayCMS

Ця інструкція призначена для розробників, які хочуть розмістити свій модуль на маркетплейсі OkayCMS. У ній детально описано повний процес — від підготовки середовища до публікації модуля.

Необхідні знання

Для роботи знадобляться базові технічні навички:

• Розуміння принципів роботи з Git — створення репозиторіїв, коміти, гілки, пуші.

• Знання структури OkayCMS та основ побудови модулів.

• Базові навички роботи в терміналі.

• Розуміння основ HTML, PHP та JavaScript — для внесення змін у код або шаблони.

💡 Якщо ви вперше працюєте з Git або Bitbucket — рекомендується перше викладання виконати разом із представником команди OkayCMS, щоб уникнути технічних помилок.

Необхідні інструменти

Перед початком переконайтеся, що у вас встановлено та налаштовано:

• Git — для керування версіями коду.

• Bitbucket — основний репозиторій, з якого здійснюється викладка модулів на маркетплейс.

• Редактор коду (Visual Studio Code, PhpStorm тощо).

• Тестове середовище OkayCMS — локально або на сервері, щоб перевірити роботу модуля перед публікацією.

Рекомендації перед початком

• Переконайтеся, що модуль повністю працездатний і не викликає конфліктів з базовими модулями OkayCMS.

• Додайте файл README.md із коротким описом, інструкцією встановлення, контактами розробника й, за бажання, посиланням на демо.

• Якщо модуль використовує сторонні бібліотеки, переконайтеся, що вони мають відповідні ліцензії.

Створення репозиторію для модулів

Щоб створити власний репозиторій для розробки модулів OkayCMS, виконайте такі дії:

1. Склонуйте офіційний репозиторій OkayCMS:

   Це потрібно, щоб отримати актуальну структуру системи.

   git clone [email protected]:OkayCMS/OkayCMS.git

2. Видаліть директорію .git:

   Таким чином ви від’єднаєтесь від історії комітів оригінального репозиторію й зможете вести власну.

   rm -rf .git

3. Ініціалізуйте новий Git-репозиторій:

   git init

4. Створіть файл локальних налаштувань:

   У директорії config/ створіть файл config.local.php.
   Він використовується для підключення до вашої локальної бази даних.
   Зміст файлу можна взяти за зразком із config/config.php, але вказати свої доступи:

   <?php $config = [ 'db_host' => 'localhost', 'db_user' => 'root', 'db_pass' => '', 'db_name' => 'okaycms', ];

5. Імпортуйте дамп бази даних:

   Файл із базовою структурою бази знаходиться за шляхом:

   1DB_changes/okay_clean.sql

   Імпортуйте його через phpMyAdmin, Adminer або команду MySQL у терміналі.

6. Встановіть залежності через Composer:

   Виконайте команду:

   composer install

   Це завантажить необхідні бібліотеки, потрібні для роботи OkayCMS.

Після виконання цих кроків ваш робочий репозиторій буде готовий до створення гілок із модулями.

Ведення репозиторію

Гілка master у вашому репозиторії використовується як основа для створення модулів.
У ній повинні зберігатися чисті версії OkayCMS, без внесених змін модулями.

Як організувати гілку master

• Кожен коміт у master рекомендується називати версією OkayCMS, яка в ньому присутня.

  Наприклад:

  OkayCMS 3.3.5
OkayCMS 3.4.1

• У master мають бути всі версії OkayCMS, під які ви плануєте створювати модулі.
  Ідеально — зберігати послідовність версій так само, як в офіційному репозиторії.

Це дозволить:

• створювати модулі під різні версії OkayCMS;

• у майбутньому коректно оновлювати модуль через git merge (а не ручне копіювання файлів).

Рекомендація: Як легко оновити версію OkayCMS у master

1. Перейдіть у master:

   git checkout master

2. Видаліть усі каталоги, крім:

   .git config/config.local.php

   (також можна залишити свої робочі файли типу .idea, якщо потрібно)

3. Склонуйте офіційний репозиторій OkayCMS у будь-яку тимчасову директорію.

4. Перейдіть у тимчасовому репозиторії на версію, до якої хочете оновитися.

5. Скопіюйте файли OkayCMS з тимчасової директорії у ваш репозиторій модулів
   — таким чином Git зафіксує лише відмінності, а не створить “забруднену” історію.

6. Імпортуйте оновлений дамп бази:

   1DB_changes/okay_clean.sql

7. Виконайте:

   composer install

Після цього у гілці master буде актуальна версія OkayCMS, готова для створення або оновлення модулів.

Ведення модулів у репозиторії

Кожен модуль розробляється в окремій гілці (branch). Гілка обов`язково створюється від тієї версії OkayCMS у master, для якої розробляється модуль.

Документація щодо модульності

Правила створення гілки модуля

1. Перейдіть у master:

   git checkout master

2. Переконайтеся, що у master знаходиться потрібна версія OkayCMS.

3. Створіть гілку з назвою модуля:

   git checkout -b <module_name>

Приклади назв гілок:

📌 Гілки з модулями не потрібно і не можна зливати назад у master.
Кожна гілка — це окремий модуль, і він “живе” тільки в ній.

Де розміщувати файли модуля

Усі файли модуля повинні бути ізольовані в директорії:

Okay/Modules/<vendor>/<moduleName>/

Таким чином модуль може бути встановлений або видалений без впливу на ядро системи.

Якщо модуль потребує доповнень у шаблон

Іноді для роботи модуля потрібно:

• додати шорткод у шаблон,

• підключити js/css,

• розмістити елемент на сторінці.

У цьому випадку:

1. Додайте необхідні зміни до демо-шаблону в цій же гілці, щоб модуль коректно працював на демо.

2. Архів модуля буде збиратися без цих змін, тому:

3. Додайте інструкцію з встановлення та налаштування для кінцевого користувача.

Наприклад, файл:

Okay/Modules/<vendor>/<moduleName>/README.md

Він повинен описувати:

• як встановити модуль,

• як додати потрібні елементи у шаблон,

• які параметри використовувати.

Хороша практика

Додайте контролер за замовчуванням у модуль, у якому буде описано:

• як його встановити,

• як налаштувати,

• які є опції.

Це значно полегшує публікацію модуля та роботу партнера-клієнта.

Версионність модулів

Для кожного модуля необхідно вести окрему систему версій. Номер версії модуля складається з трьох цілих чисел, розділених крапкою.

Наприклад:

1.0.0

Це перша (початкова) версія модуля.

Принцип інкрементації версій

Таким чином:

• Patch-рівень (третья цифра) — дрібні виправлення.

• Minor-рівень (друга цифра) — зміни логіки і функціоналу.

• Major-рівень (перша цифра) — повна переробка або несумісні зміни.

Прив`язка тегів у репозиторії

Щоб зафіксувати версію модуля у репозиторії, потрібно поставити тег на коміт.

Формат тегу обов’язково має бути:

<branch_name>_<version>

Наприклад, модуль ведеться у гілці custom_module, і ми випускаємо першу версію:

git tag custom_module_1.0.0 git push origin custom_module_1.0.0

Якщо модуль оновлюється до версії 1.1.0, тег буде:

git tag custom_module_1.1.0 git push origin custom_module_1.1.0

Важливо: кожен тег повинен однозначно відповідати стану модуля у цій гілці.

Оновлення OkayCMS у модулі

Якщо потрібно оновити версію OkayCMS у гілці з модулем,
оновлення виконується тільки через merge з гілки master.

Заборонено оновлювати файли ядра OkayCMS безпосередньо в гілці модуля —
це призводить до розходжень, конфліктів та неможливості підтримувати модуль.

Правильний спосіб оновлення

1. Перейдіть у гілку модуля:

   git checkout <module_branch>

2. Зробіть merge тієї версії OkayCMS з master, яка вам потрібна:

   git merge master

3. Вирішіть можливі конфлікти (якщо є).

4. Перевірте роботу модуля після оновлення.

Чому саме merge?

Оновлення повинно бути саме merge-коммітом, який має два батьківські комміти:

• перший — історія вашої гілки модуля

• другий — зміни з master

Це дозволяє:

• зберігати чисту історію

• точно розуміти, до якої версії OkayCMS прив’язана поточна версія модуля

• без проблем оновлювати модуль при виході нових версій CMS

Неприпустимі дії

Створення демо-контенту

Демоконтент використовується для демонстрації роботи модуля у тестовому середовищі або на демо-стенді.
У демо можна додавати товари, банери, категорії, сторінки тощо.

Де зберігається демоконтент

Демоконтент бази даних повинен знаходитись виключно у файлі:

1DB_changes/demo.sql

❗ Заборонено змінювати файл 1DB_changes/okay_clean.sql — це чиста вихідна база для встановлення OkayCMS.

Що можна додавати в демо

• товари та їх зображення

• банери / слайди

• категорії

• прості сторінки (наприклад “Доставка та оплата”)

• налаштування, що стосуються саме модуля

Завантаження медіафайлів (зображень) допускається — вони мають бути додані в files/origin або files/resized після створення демо.

Як створити demo.sql

• Через адмінку додайте необхідні:

  • товари

  • банери

  • меню

  • категорії

  • тексти і т. д.

• Підключіться до бази через Adminer / phpMyAdmin / TablePlus.

• Виберіть експорт (dump) тільки даних таблиць, які були змінені.

  У налаштуваннях експорту:

  Tables → нічого не вибираємо (жодна не повинна бути позначена) Data → позначаємо тільки таблиці, які містять демо-контент

• У полі форматування задаємо:

  Data export mode: TRUNCATE + INSERT Format: SQL

  

• Зберігаємо дамп у файл:

  1DB_changes/demo.sql

Заборонено додавати в демо:

Демоконтент не входить в архів модуля під час публікації на маркетплейсі.
Він використовується тільки для внутрішньої демонстрації та перевірки.

Ведення шаблонів у репозиторії

Кожен шаблон оформлюється і розвивається в окремій гілці (branch), яка обов’язково створюється від гілки master тієї версії OkayCMS, під яку створюється шаблон.

Гілки з шаблонами не мержаться назад у master.
В одній гілці розвивається тільки один шаблон.

Іменування гілок

Гілку рекомендується називати іменем шаблону, наприклад:

❗ Заборонено вносити зміни в базовий шаблон okay_shop.
Новий шаблон повинен мати власну назву і бути окремий від оригінального.

Розміщення шаблону в файловій структурі

Шаблон повинен знаходитись у директорії:

design/<theme_name>/

Приклади:

design/modern_store/ design/beauty_shop/

Інструкція для користувача (README)

Якщо для коректної роботи шаблону необхідно виконати додаткові кроки, наприклад:

• створити групи банерів

• увімкнути певні модулі

• додати слайдер

• змінити налаштування меню

Тоді у шаблоні потрібно створити файл:

design/<theme_name>/README.md

У цьому файлі описується:

• що робить шаблон

• як його встановити

• як налаштувати банери, меню або сторінки

Демонстраційна версія шаблону (демо)

Щоб шаблон коректно відображався на демо-маркетплейсі, необхідно:

1. Створити потрібні банерні групи / слайдери / меню у демо-сайті.

2. Додати їх у демо-контент (1DB_changes/demo.sql).

Таким чином користувач одразу побачить готовий вигляд шаблону, без ручної настройки.

Додавання репозиторію в маркетплейс

Щоб маркетплейс міг автоматично отримувати версії модулів і шаблонів з вашого репозиторію, необхідно надати доступ по SSH і налаштувати webhook.

Надання доступу по SSH

1. Перейдіть у ваш репозиторій на Bitbucket.

2. Відкрийте меню:

   Repository settings → Access keys

3. Натисніть Add key.

4. У полі Label введіть довільну назву, наприклад:

   okay-modules

5. У полі Key вставте SSH-ключ, який вам надасть адміністрація OkayCMS.

Примітка: Ключ не є публічним.
Щоб отримати його, зверніться до підтримки або менеджера, який підключає вас до маркетплейса.

Збережіть ключ.

Налаштування автоматичного оновлення (Webhook)

Щоб модулі автоматично з’являлися або оновлювалися в маркетплейсі:

1. Перейдіть:

   Repository settings → Webhooks

2. Натисніть Add webhook.

3. У полі Title вкажіть довільну назву, наприклад:

   okay-modules-sync

4. У полі URL введіть:

   https://modules.okay-cms.com/bitbucket/hook/initial </code

5. Збережіть webhook.

Після налаштування

При створенні тега з версією модуля маркетплейс автоматично:

• виявить нову версію

• імпортує її до системи

• оновить сторінку модуля в каталозі

Додаткові ручні дії не потрібні.