🇺🇦 Збір на ремонт дронів для батальйону Antares Підтримати
ua
ru en ua
Дивитися демо
  1. Головна
  2. Інструкції
  3. Розробка модуля і шаблону для маркетплейсу

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

Закрити
Розділи інструкції
Категорії

Що потрібно зробити спочатку

Marketplace start

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

Переконайтеся, що ви вже:

  1. Ознайомилися з перевагами партнерської програми OkayCMS

  2. Ознайомилися з умовами та правилами співпраці

  3. Подали заявку на партнерство через офіційний сайт OkayCMS

  4. Отримали зворотний зв'язок від служби підтримки

  5. Зареєструвалися в маркетплейсі як партнер

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

Далі у цій інструкції розглянемо повний процес: від підготовки репозиторію до появи модуля в маркетплейсі OkayCMS.

Як працює публікація модулів

Нижче показано загальну схему роботи публікації модулів у OkayCMS.

Процес починається з чистої версії OkayCMS, після чого для кожного модуля створюється окрема гілка. У цій гілці виконується вся розробка та внесення змін. Після завершення роботи створюється версія модуля через Git tag, а маркетплейс автоматично отримує нову версію з репозиторію.

  1. master. Чиста версія OkayCMS без сторонніх модулів та змін. Вона використовується як база для створення нових модулів.

  2. Створення гілки модуля. Для кожного нового модуля створюється окрема Git-гілка. У ній зберігається весь код, який стосується лише цього модуля.

  3. Розробка модуля. Етап створення функціоналу, логіки роботи, шаблонів, налаштувань та необхідних файлів модуля.

  4. Commit. Фіксація виконаних змін у Git із коротким описом виконаної роботи.

  5. Git tag. Створення окремої версії модуля. Саме Git tag використовується маркетплейсом для створення нової версії.

  6. Bitbucket. Репозиторій, у якому зберігається код модуля, історія змін та всі його версії.

  7. modules.okay-cms.com. Сервіс автоматично перевіряє репозиторій, знаходить нові теги та імпортує нові версії модулів.

  8. Маркетплейс OkayCMS. Після обробки модуль або його нова версія стає доступною користувачам у маркетплейсі.

Важливо:

✅ Один модуль = одна окрема гілка

✅ Один Git tag = одна окрема версія модуля

✅ Гілка модуля створюється від master

❌ Гілки модулів не зливаються назад у master

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

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

Для роботи знадобляться:

Інструмент Для чого потрібен
Git Керування версіями
Bitbucket Зберігання коду та репозиторіїв
VS Code / PhpStorm Редагування коду
Локальна копія OkayCMS Розробка та тестування модуля

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

✅ Робота з Git (commit, push, branch)

✅ Структура OkayCMS

✅ Базові знання PHP / HTML / JS

✅ Робота з терміналом

Налаштування локального середовища

Крок 1. Склонуйте OkayCMS

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

git clone https://github.com/OkayCMS/OkayCMS.git <folder_name>

Наприклад:

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

Або, якщо ви вже перебуваєте в потрібній порожній папці:

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

Крапка означає клонування репозиторію в поточну директорію.

Крок 2. Видаліть історію Git

Перейдіть у директорію проєкту:

cd <folder_name>

Після цього виконайте:

rm -rf .git

Це від'єднає репозиторій від офіційної історії OkayCMS.

Крок 3. Ініціалізуйте новий репозиторій

git init

Після виконання буде створено директорію .git.

Важливо: без цього кроку команди git add, git commit та git push не працюватимуть.

Крок 4. Створіть локальний конфіг

Створіть файл:

config/config.local.php

Приклад:

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

Файл використовується для підключення локальної бази даних.

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

Імпортуйте файл:

1DB_changes/okay_clean.sql

Для імпорту можна використовувати phpMyAdmin, Adminer або TablePlus.

Крок 6. Встановіть залежності

composer install

Команда встановить усі необхідні бібліотеки для роботи OkayCMS.

Створення та підключення репозиторію Bitbucket

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

Під час створення репозиторію важливо одразу вказати правильні параметри. Неправильні налаштування на цьому етапі можуть призвести до проблем із Git, webhook або автоматичним імпортом модулів у маркетплейс.

На цьому етапі ви:

  1. Створите новий репозиторій у Bitbucket

  2. Налаштуєте його початкові параметри

  3. Вкажете правильну основну гілку

  4. Підключите локальний проєкт до репозиторію

  5. Підготуєте репозиторій до подальшої розробки та публікації модулів

Особливу увагу зверніть на гілку master.

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

Саме від гілки master у майбутньому створюватимуться окремі гілки модулів, тому при створенні репозиторію необхідно використовувати:

Default branch → master

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

Параметри репозиторію повинні бути такими:

  • Include README → No

  • Include .gitignore → No

  • Default branch → master

README та .gitignore створювати не потрібно, оскільки вони вже присутні у вихідному коді проєкту або будуть додані пізніше за необхідності.

Підключення локального проєкту до репозиторію

Після створення репозиторію необхідно прив'язати до нього локальний проєкт. Для цього потрібно додати віддалений репозиторій origin.

Якщо використовується SSH:

git remote add origin [email protected]:<workspace>/<repository>.git

Або через HTTPS:

git remote add origin https://<login>@bitbucket.org/<workspace>/<repository>.git

Перевірити підключення можна командою:

git remote -v

Після цього локальний проєкт буде пов'язаний із репозиторієм Bitbucket і ви зможете виконувати git push, створювати Git tag та публікувати нові версії модулів.

Важливо:

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

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

Перший commit чистої OkayCMS

Після створення репозиторію в Bitbucket необхідно додати до нього чисту версію OkayCMS та виконати перший commit у гілку master.

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

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

git add . git commit -m "OkayCMS 4.5.2" git push -u origin master

На цьому етапі ви:

  1. Додасте всі файли OkayCMS до Git

  2. Створите перший commit із чистою версією системи

  3. Відправите код у репозиторій Bitbucket

  4. Створите базову гілку master для подальшої розробки модулів.

 

Навіщо це потрібно?

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

Важливо у гілці master не повинно бути:

❌ файлів модулів;

❌ тестового коду;

❌ демо-контенту;

❌ тимчасових файлів розробки

Після виконання команд рекомендується перевірити репозиторій у Bitbucket та переконатися, що в ньому знаходиться лише чиста структура файлів OkayCMS.

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

Створення гілки модуля

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

Перед створенням нової гілки переконайтеся, що ви знаходитесь у гілці master:

git checkout master

Після цього створіть нову гілку для модуля:

git checkout -b popup_cart

Де popup_cart — це назва вашого модуля та майбутньої гілки.

На цьому етапі ви:

  1. Перейдете в чисту гілку master

  2. Створите окрему гілку для нового модуля

  3. Підготуєте середовище для подальшої розробки

  4. Відокремите код модуля від інших проєктів та модулів

 

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

  • popup_cart — спливаючий кошик;

  • set — комплекти товарів;

  • fast_order — швидке замовлення.

 

Навіщо це потрібно?

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

Важливо:

  • гілка модуля завжди створюється від master;
  • одна гілка = один модуль;
  • гілки модулів не зливаються назад у master;
  • у гілці master повинна залишатися лише чиста версія OkayCMS.

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

Структура файлів модуля

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

Okay/Modules/<Vendor>/<ModuleName>/

Наприклад:

Okay/Modules/VendorName/PopupCart/ Okay/Modules/Partner/PopupCart/

Саме така структура використовується в OkayCMS та підтримується маркетплейсом під час перевірки, імпорту та встановлення модулів.

На цьому етапі ви:

  1. Створите правильну структуру каталогів для модуля

  2. Відокремите файли модуля від ядра OkayCMS

  3. Забезпечите сумісність із маркетплейсом

  4. Підготуєте модуль до подальшої розробки та публікації

 

Навіщо це потрібно?

Розміщення всіх файлів модуля в каталозі Okay/Modules дозволяє:

  • легко встановлювати модуль;
  • легко видаляти модуль;
  • не змінювати ядро системи;
  • уникати конфліктів під час оновлення OkayCMS;
  • забезпечити коректну роботу маркетплейсу.

 

Правильне розташування файлів:

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

Okay/Modules/<Vendor>/<ModuleName>/

Не рекомендується розміщувати файли модуля:

❌ У каталозі backend;

❌ У каталозі design;

❌ У корені проєкту;

❌ У каталозі files або будь-яких інших системних каталогах.

Таке розташування порушує структуру проєкту, ускладнює підтримку модуля та може призвести до помилок під час оновлення системи.

Важливо:

  • усі файли модуля повинні бути ізольовані всередині каталогу Okay/Modules
  • один модуль = один окремий каталог
  • не рекомендується вносити зміни до ядра OkayCMS для реалізації функціоналу модуля
  • структура модуля повинна відповідати стандартам OkayCMS

Дотримання структури Okay/Modules/<Vendor>/<ModuleName>/ є стандартом розробки модулів для OkayCMS та забезпечує їх коректну роботу в маркетплейсі.

Версія модуля

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

Файл повинен знаходитися за шляхом:

Okay/Modules/<Vendor>/<ModuleName>/Init/module.json

Приклад вмісту файлу:

{ "version": "1.0.0" }

На цьому етапі ви:

  1. вкажете поточну версію модуля

  2. підготуєте модуль до публікації в маркетплейсі

  3. налаштуєте коректне відстеження релізів

  4. забезпечите сумісність із механізмом оновлень OkayCMS

 

Навіщо це потрібно?

Маркетплейс OkayCMS використовує версію з файлу module.json для визначення поточного релізу модуля. Під час імпорту маркетплейс перевіряє відповідність версії та Git tag.

Важливо:

Значення поля version у файлі module.json повинно повністю збігатися з версією, яка використовується в Git tag.

Правильно:

module.json { "version": "1.0.0" } Git tag popup_cart_1.0.0

Неправильно:

module.json { "version": "1.0.0" } Git tag popup_cart_0.9.9 module.json { "version": "1.0.0" } Git tag popup_cart_1.0.1

Формат Git tag є обов'язковим:

<branch_name>_<version>

Наприклад:

popup_cart_1.0.0

Не рекомендується використовувати:

  • 1.0.0
  • v1.0.0
  • master_1.0.0

Інші формати тегів не підтримуються маркетплейсом OkayCMS.

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

Правила версій

Для версіонування модулів у OkayCMS використовується формат:

MAJOR.MINOR.PATCH

Наприклад:

1.0.0

Кожна цифра у версії має своє призначення та змінюється залежно від типу внесених змін.

Ситуація Що змінюється Приклад
Виправлення помилки третя цифра (PATCH) 1.0.0 → 1.0.1
Нова логіка або функціонал друга цифра (MINOR) 1.0.1 → 1.1.0
Повна переробка перша цифра (MAJOR) 1.1.0 → 2.0.0

 

Приклад розвитку версії:

1.0.0 → 1.0.1 → 1.0.2 → 1.1.0 → 1.2.0 → 2.0.0

Важливо: версія у файлі module.json повинна збігатися з версією Git tag.

{ "version": "1.1.0" } popup_cart_1.1.0

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

Публікація модуля в репозиторій

Після завершення розробки модуль необхідно опублікувати в репозиторії та створити Git tag. Саме Git tag використовується маркетплейсом OkayCMS для визначення нової версії модуля та її автоматичного імпорту.

Процес публікації складається з двох кроків:

  1. Збереження змін у Git (commit).

  2. Створення Git tag для нової версії модуля.

 

Крок 1. Створіть commit

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

git add . git commit -m "Перша версія" git push origin popup_cart

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

Крок 2. Створіть Git tag

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

git tag popup_cart_1.0.0 git push origin popup_cart_1.0.0

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

Важливо:

✅ Версія в module.json повинна збігатися з версією Git tag;

✅ Кожна нова версія повинна мати новий Git tag;

✅ Формат тегу повинен бути <branch_name>_<version>

❌ Не змінюйте вже опубліковані теги;

Наприклад:

popup_cart_1.0.0 popup_cart_1.1.0 popup_cart_1.2.0

Після створення Git tag нова версія модуля автоматично з'явиться в маркетплейсі OkayCMS.

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

Під час розробки модуля в гілці можуть накопичуватися зміни в основній гілці master. Щоб отримати нові оновлення ядра OkayCMS, необхідно виконувати оновлення через Git merge.

Усі роботи над модулем виконуються тільки в його власній гілці.

Спочатку перейдіть у гілку модуля:

git checkout popup_cart

Після цього виконайте merge з гілкою master:

git merge master

На цьому етапі ви:

  1. Отримаєте останні зміни з чистої версії OkayCMS;

  2. Оновите свою гілку модуля;

  3. Збережете власні зміни модуля;

  4. Забезпечите сумісність із поточною версією OkayCMS.

 

Як це працює?

Після виконання git merge master у вашу гілку потрапляють останні зміни з master, але сам модуль залишається у своїй гілці та продовжує розвиватися незалежно.

Навіщо використовувати merge?:

✅ Зберігається історія змін;

✅ Легко відстежувати оновлення OkayCMS;

✅ Зменшується ризик конфліктів;

✅ Гарантується сумісність із поточною версією системи.

Не можна:

❌ Копіювати файли OkayCMS вручну;

❌ Оновлювати ядро напряму у гілці модуля;

❌ Замінювати файли системи вручну.

Такі дії можуть призвести до конфліктів, втрати змін або проблем під час подальших оновлень.

Важливо:

Оновлення OkayCMS у модулі завжди виконується тільки через git merge master. Це стандартний і рекомендований спосіб підтримувати модуль у актуальному стані.

Демо-контент

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

1DB_changes/demo.sql

Цей файл використовується для імпорту демо-контенту під час встановлення або тестування модуля.

На цьому етапі ви:

  1. підготуєте демонстраційні дані для модуля;

  2. спростите тестування функціоналу;

  3. покажете можливості модуля на тестовому сайті;

  4. збережете сумісність із системою та маркетплейсом.

 

Використовуйте тільки: 1DB_changes/demo.sql

Не використовуйте: 1DB_changes/okay_clean.sql

Файл okay_clean.sql використовується для розгортання чистої системи OkayCMS і не призначений для зберігання демо-даних модуля.

У demo.sql дозволяється додавати:

✅ Товари;

✅ Банери;

✅ Категорії;

✅ Сторінки;

✅ Зображення та пов'язані з ними дані.

Не можна додавати або змінювати:

❌ ok_managers — користувачі та права доступу;

❌ ok_settings — налаштування системи;

❌ ok_modules — список встановлених модулів.

Навіщо окремий файл demo.sql?

  1. додає демонстраційні дані для модуля;

  2. безпечний для імпорту на тестових сайтах;

  3. не впливає на налаштування OkayCMS;

  4. легко видаляється разом із модулем.

Важливо:

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

README для користувача

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

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

Okay/Modules/<Vendor>/<ModuleName>/README.md

На цьому етапі ви:

  1. підготуєте документацію для користувачів;

  2. спростите встановлення модуля;

  3. зменшите кількість запитань до підтримки;

  4. підвищите зручність використання модуля..

 

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

  • процес встановлення;

  • налаштування модуля;

  • необхідні зміни шаблону (якщо вони потрібні);

  • основні параметри та можливості модуля.

 

Приклад структури README:

  1. Встановлення

  2. Налаштування

  3. Необхідні зміни шаблону

  4. Додаткова інформація

 

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

Поради:

✅ Пишіть простою та зрозумілою мовою;

✅ Додавайте приклади коду там, де це необхідно;

✅ Описуйте лише те, що потрібно користувачу для роботи з модулем;

✅ Оновлюйте README при додаванні нового функціоналу.

Якісний файл README.md значно спрощує встановлення та налаштування модуля для кінцевого користувача.

Підключення маркетплейсу

Після створення репозиторію необхідно надати маркетплейсу доступ до нього та налаштувати автоматичне отримання оновлень. Для цього потрібно додати SSH-ключ і Webhook, дані для яких доступні у вашому кабінеті на modules.

Крок 1. Додайте SSH-ключ

У Bitbucket відкрийте:

Repository settings → Access keys

Додайте SSH-ключ, який вказаний у вашому кабінеті на modules.

SSH-ключ використовується для надання маркетплейсу доступу до вашого репозиторію та завантаження файлів модуля.

Крок 2. Налаштуйте Webhook

У Bitbucket відкрийте:

Repository settings → Webhooks

Додайте Webhook URL, який вказаний у вашому кабінеті на modules.

Після кожного створення Git tag або відправлення змін у репозиторій Bitbucket буде автоматично повідомляти маркетплейс про оновлення.

Що відбувається після налаштування?

Після створення нового Git tag маркетплейс автоматично:

  1. отримує повідомлення від Bitbucket;

  2. завантажує нову версію модуля з репозиторію;

  3. оновлює інформацію про модуль;

  4. публікує нову версію в маркетплейсі.

Схема роботи:

Git tag ↓ Bitbucket ↓ Webhook ↓ Marketplace OkayCMS ↓ Нова версія модуля

 

Важливо:

✅ Використовуйте тільки SSH-ключ із вашого кабінету на modules;

✅ Використовуйте тільки Webhook URL із вашого кабінету на modules;

✅ Webhook повинен бути активований;

✅ Репозиторій повинен містити гілку master.

Без налаштованих SSH-ключа та Webhook маркетплейс не зможе автоматично отримувати зміни з вашого репозиторію та публікувати нові версії модулів.

Що допоможе уникнути помилок

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

Найпоширеніші помилки:

❌ Створено гілку main замість master;

❌ Git tag створений до commit або до відправлення змін у репозиторій;

❌ Версія в module.json не збігається з версією Git tag;

❌ Файли модуля потрапили в гілку master;

❌ SSH-ключ доданий не в той репозиторій;

❌ Webhook відкривається вручну в браузері замість автоматичного виклику Bitbucket;

❌ Файл demo.sql доданий у master замість гілки модуля.

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

Корисна рекомендація.

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

✅ Створити тестову копію сайту;

✅ Перевірити встановлення модуля з архіву;

✅ Перевірити оновлення через Git tag;

✅ Переконатися, що README містить інструкцію зі встановлення та налаштування.

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

увійдіть в особистий кабінет
Завантажити OkayCMS
version 4.5.2
Підписатися на розсилку
Ви будете отримувати добірку корисних статей по роботі з сайтом на OkayCMS, знижки на модулі і шаблони