Розробка модуля і шаблону для маркетплейсу

Підготовка до розробки модулів

Ця інструкція призначена для розробників, які планують створювати та публікувати власні модулі або шаблони на маркетплейсі OkayCMS.

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

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

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

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

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

• знання структури OkayCMS і логіки побудови модулів;

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

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

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

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

• 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

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

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

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

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

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

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

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