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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Додай у директорію модуля файл:

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

  У ньому коротко опиши: що робить модуль, як його встановити і налаштувати, а також вкажи контакти розробника.

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

• Перевір, щоб усі шляхи, назви директорій і залежності були прописані коректно, а структура модуля відповідала вимогам OkayCMS та стандартам маркетплейсу.

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

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

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

   У терміналі вашого редактора введіть команду:

   git clone https://github.com/OkayCMS/OkayCMS.git

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

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

   Для цього перейдіть у папку проєкту та в терміналі редактора виконайте команду:

   rm -rf .git

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

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

   У терміналі редактора виконайте команду:

   git init

   Ця команда ініціалізує новий репозиторій у вашій поточній папці проєкту. Після цього Git почне відстежувати зміни у файлах, і ви зможете додавати коміти, створювати гілки.

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

   Після ініціалізації репозиторію потрібно налаштувати підключення до бази даних.
   Для цього у папці config/ створіть новий файл config.local.php.
   Цей файл використовується тільки у вашому локальному середовищі
   і зберігає дані для підключення до вашої бази даних.

   Вміст файлу можна взяти за прикладом із config/config.php, але потрібно вказати власні параметри підключення:

   [database] db_server = "localhost" db_user = "root" db_password = "root" db_name = "okaycms"

   Файл config.local.php уже доданий у .gitignore за замовчуванням, тому він не потрапляє до репозиторію і не зберігає конфіденційні дані в публічному доступі.

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

   Щоб підготувати базу даних для роботи OkayCMS, потрібно імпортувати початкову структуру таблиць.
   Файл із базовими даними знаходиться за шляхом:

   1DB_changes/okay_clean.sql

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

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

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

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

   composer install

   Composer автоматично завантажить усі залежності, зазначені в проєкті, і підготує систему до запуску.

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

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

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

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

Кожен коміт у гілці master бажано називати відповідно до версії OkayCMS,
яка в ньому присутня, наприклад:

OkayCMS 3.3.5

OkayCMS 3.4.1

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

Найкраще — дотримуватись тієї ж послідовності версій, що й в офіційному репозиторії OkayCMS. 

Як оновити версію OkayCMS у master

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

   git checkout master

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

   .git

   config/config.local.php

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

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

   git clone https://github.com/OkayCMS/OkayCMS.git  temp

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

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>

   Приклади як назвати гілку:

   popup_cart — модуль вспливаючого кошика

   set або kit — модуль комплектів товарів

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

Файли кожного модуля повинні бути ізольовані в окремій директорії:

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

Така структура дозволяє встановлювати або видаляти модуль без будь-якого впливу на ядро системи.

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

Іноді для роботи модуля потрібно внести невеликі зміни до шаблону — наприклад, додати шорткод або розмістити новий елемент на сторінці.

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

Для цього створіть файл:

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

У ньому коротко опишіть:

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

• як додати необхідні елементи у шаблон;

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

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

Для кожного модуля потрібно вести власну систему версій.

Номер версії складається з трьох чисел, розділених крапкою:

1.0.0

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

Як змінюється номер версії

Як прив’язати тег до версії

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

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

<branch_name>_<version>

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

git tag custom_module_1.0.0 git push origin custom_module_1.0.0

Після оновлення до нової версії:

git tag custom_module_1.1.0 git push origin custom_module_1.1.0

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

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

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

Як правильно оновити модуль

1. Спочатку переконайтесь, що гілку master у вашому репозиторії вже оновлено до потрібної версії OkayCMS.

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

   git checkout <module_branch>

3. Виконайте merge з гілки master:

   git merge master

4. Якщо вам потрібна не остання версія OkayCMS, а конкретний стан системи,
   можна зробити merge за хешем коміту, що відповідає потрібній версії:

   git merge <commit_hash>

5. Вирішіть конфлікти, якщо вони виникнуть.

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

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

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

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

У ньому можна додавати товари, банери, категорії, сторінки та інші елементи, необхідні для презентації модуля.

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

Увесь демо-контент бази даних має зберігатися лише у файлі:

1DB_changes/demo.sql

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

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

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

• категорії

• меню

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

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

Медіафайли (зображення) розміщуються у директорії /files/originals

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

1. У адмінці додайте все, що потрібно для демонстрації: товари, категорії, банери, меню, тексти тощо.

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

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

4. У налаштуваннях експорту оберіть:

   ✅  Tables → DROP+CREATE

   ✅  Data → позначаємо тільки таблиці, що містять демо-контент

   ✅  Data export mode → TRUNCATE + INSERT

   ✅  Format → SQL

   

5. Збережіть дамп у файл:

   1DB_changes/demo.sql

Що заборонено додавати в demo.sql

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

Кожен шаблон оформлюється та розробляється в окремій гілці (branch).

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

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

Гілку шаблону рекомендується називати зрозуміло та однозначно — за назвою теми.

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

Кожен шаблон зберігається в директорії:

design/<theme_name>/

Приклади:

design/modern_store/ design/beauty_shop/

README для шаблону

Якщо шаблон вимагає додаткових дій для коректної роботи, у його директорії потрібно створити файл:

design/<theme_name>/README.md

У README рекомендується описати:

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

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

• які налаштування потрібні (банери, меню, слайдери тощо);

• які модулі мають бути увімкнені;

• особливості роботи та корисні поради.

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

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

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

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

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

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

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

• надати доступ до репозиторію через SSH-ключ;

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

Після цього маркетплейс зможе отримувати оновлення, а модуль стане доступним користувачам після ручної перевірки та підтвердження адміністратором.

Надаємо доступ по SSH

1. Відкрийте ваш репозиторій на Bitbucket.

2. Перейдіть у меню: Repository settings → Access keys

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

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

   okay-modules

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

   ❗ Ключ не є публічним.

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

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

Налаштування автоматичної синхронізації (Webhook)

1. Перейдіть у меню: Repository settings → Webhooks

2. Натисніть кнопку Add webhook.

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

   okay-modules-sync

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

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

5. Збережіть налаштування.

Як це працює

Після створення нового тегу (версії модуля або шаблону), маркетплейс:

• отримує інформацію про нову версію;

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

• додає версію до списку доступних.

Ручна модерація перед публікацією

Хоча система отримує нові версії, модуль не стає одразу доступним у каталозі.

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

• коректність структури модуля;

• відповідність стандартам OkayCMS;

• наявність та якість README;

• наявність і правильність demo.sql;

• відсутність критичних помилок;

• працездатність модуля на демо та чистій установці.

Лише після схвалення модераторами модуль:

• з’являється у каталозі;
• стає доступним для завантаження або покупки.

Модерація зазвичай триває 1–3 робочі дні, але залежить від навантаження.