Developing Modules and Themes for the Marketplace

What You Need to Do First

Before publishing modules, you need to complete several preparation steps.

Make sure that you have already:

1. Reviewed the benefits of the OkayCMS Partner Program

2. Read the terms and conditions of cooperation

3. Submitted a partnership application through the official OkayCMS website

4. Received feedback from the support team

5. Registered in the marketplace as a partner

After completing these steps, you will gain access to the Partner Dashboard and be able to proceed with module preparation and publication.

In the following sections, we will cover the entire process, from repository setup to publishing your module in the OkayCMS Marketplace.

How Module Publishing Works

Below is an overview of the module publishing workflow in OkayCMS.

The process starts with a clean OkayCMS installation. A separate branch is then created for each module. All development and code changes are performed within that branch. Once development is complete, a Git tag is created, and the marketplace automatically retrieves the new module version from the repository.

1. master. A clean version of OkayCMS without third-party modules or modifications. It serves as the base for creating new modules.

2. Creating a module branch. A separate Git branch is created for each new module. This branch contains all code related exclusively to that module.

3. Module development. The stage where functionality, business logic, templates, settings, and all required module files are developed.

4. Commit. Saving changes to Git with a short description of the completed work.

5. Git tag. Creating a specific module version. Git tags are used by the marketplace to identify and import new releases.

6. Bitbucket. The repository where the module source code, version history, and releases are stored.

7. modules.okay-cms.com. The service automatically checks the repository, detects new tags, and imports new module versions.

8. OkayCMS Marketplace. After processing, the module or its new version becomes available to users in the marketplace.

Required Tools and Knowledge

Before getting started, make sure your development environment is properly set up and that you have the basic knowledge required to work with OkayCMS modules.

You will need:

Setting Up the Local Environment

Step 1. Clone OkayCMS

Clone the official OkayCMS repository:

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

For example:

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

Or, if you are already inside the desired empty directory:

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

The dot means that the repository will be cloned into the current directory.

Step 2. Remove the Git History

Navigate to the project directory:

cd <folder_name>

Then run:

rm -rf .git

This will detach the project from the official OkayCMS Git history.

Step 3. Initialize a New Repository

git init

After running the command, a new .git directory will be created.

Important: without this step, the git add, git commit, and git push commands will not work.

Step 4. Create a Local Configuration File

Create the following file:

config/config.local.php

Example:

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

This file is used to connect to your local database.

Step 5. Import the Database

Import the following file:

1DB_changes/okay_clean.sql

You can use phpMyAdmin, Adminer, or TablePlus to import the database.

Step 6. Install Dependencies

composer install

This command will install all required libraries and dependencies for OkayCMS.

Creating and Connecting a Bitbucket Repository

After preparing your local environment, you need to create your own Bitbucket repository. It will be used to store module source code, maintain version history, and provide automatic integration with the OkayCMS Marketplace.

It is important to configure the repository correctly from the beginning. Incorrect settings at this stage may lead to issues with Git, webhooks, or automatic module imports into the marketplace.

At this stage, you will:

1. Create a new Bitbucket repository

2. Configure its initial settings

3. Specify the correct default branch

4. Connect your local project to the repository

5. Prepare the repository for future module development and publishing

Pay special attention to the master branch.

In the OkayCMS workflow, the master branch is used as the base for module development and should contain only a clean OkayCMS installation without third-party modifications, test code, or module files.

All module branches will be created from master, so when creating the repository you should use:

Default branch → master

Using the main branch is not recommended because the documentation, module publishing process, and update mechanisms in OkayCMS are designed around the master branch.

The repository settings should be configured as follows:

• Include README → No

• Include .gitignore → No

• Default branch → master

You do not need to create a README or .gitignore file because they are already included in the project source code or can be added later if necessary.

Connecting the Local Project to the Repository

After creating the repository, you need to link your local project to it by adding a remote repository named origin.

If you are using SSH:

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

Or using HTTPS:

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

You can verify the connection with the following command:

git remote -v

After that, your local project will be linked to the Bitbucket repository, and you will be able to use git push, create Git tags, and publish new module versions.

After completing this step, the repository will be ready, your local project will be connected to Bitbucket, and you can proceed with the first commit of the clean OkayCMS version.

First Commit of a Clean OkayCMS Installation

After creating the Bitbucket repository, you need to add a clean OkayCMS installation and create the first commit in the master branch.

This step serves as the foundation for future module development, as all module branches will later be created from this repository state.

Run the following commands:

git add . git add -f files/ -- ":!files/resized" git commit -m "OkayCMS 4.5.2" git push -u origin master

At this stage, you will:

1. Add all OkayCMS files to Git

2. Add the default OkayCMS demo content to the repository

3. Create the first commit containing the clean system version

4. Push the code to the Bitbucket repository

5. Create the base master branch for future module development

Why is this necessary?

The master branch should contain only a clean OkayCMS installation without any modifications or additional files. All future module branches will be created from this branch.

After running these commands, it is recommended to review the repository in Bitbucket and make sure it contains only the clean OkayCMS file structure.

After completing this step, the repository will be ready for creating the first module branch.

Creating a Module Branch

In OkayCMS, each module is developed in a separate Git branch created from the master branch. This approach isolates module code, simplifies project maintenance, and prevents module code from accidentally being added to the main system branch.

Before creating a new branch, make sure you are currently on the master branch:

git checkout master

Then create a new branch for your module:

git checkout -b popup_cart

Where popup_cart is the name of your module and the name of the new branch.

At this stage, you will:

1. Switch to the clean master branch

2. Create a separate branch for the new module

3. Prepare the environment for further development

4. Isolate the module code from other projects and modules

Examples of branch names:

• popup_cart — popup cart;

• set — product bundles;

• fast_order — quick order.

Why is this necessary?

Each module in the OkayCMS Marketplace must have its own dedicated branch. This makes it possible to develop, update, and publish modules independently without affecting other branches in the repository.

After creating the branch, you can proceed with module development and add the module files to the OkayCMS structure.

Module File Structure

All module files must be placed exclusively inside the following directory:

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

For example:

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

This is the standard structure used by OkayCMS and supported by the Marketplace during module validation, import, and installation.

At this stage, you will:

1. Create the correct directory structure for the module

2. Separate module files from the OkayCMS core

3. Ensure Marketplace compatibility

4. Prepare the module for further development and publishing

Why is this necessary?

Keeping all module files inside the Okay/Modules directory allows you to:

• easily install the module;
• easily remove the module;
• avoid modifying the system core;
• prevent conflicts during OkayCMS updates;
• ensure proper Marketplace operation.

Correct file placement:

All module files, templates, settings, controllers, entities, and service files must be located only inside the following directory:

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

Such placement breaks the project structure, makes module maintenance more difficult, and may cause issues during system updates.

Following the Okay/Modules/<Vendor>/<ModuleName>/ structure is the standard approach for OkayCMS module development and ensures proper operation in the Marketplace.

Module Version

Each module must contain information about its current version. This is done using the module.json file located in the module initialization directory.

The file must be located at:

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

Example file content:

{ "version": "1.0.0" }

At this stage, you will:

1. specify the current module version

2. prepare the module for Marketplace publication

3. configure proper release tracking

4. ensure compatibility with the OkayCMS update mechanism

Why is this necessary?

The OkayCMS Marketplace uses the version specified in module.json to determine the current module release. During import, the Marketplace validates that the module version matches the Git tag version.

Important:

The version value in the module.json file must exactly match the version used in the Git tag.

Correct:

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

Incorrect:

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

The Git tag format is mandatory:

<branch_name>_<version>

For example:

popup_cart_1.0.0

The following formats are not recommended:

• 1.0.0
• v1.0.0
• master_1.0.0

Other tag formats are not supported by the OkayCMS Marketplace.

After configuring the version, you can proceed with creating the first module release and publishing the Git tag.

Versioning Rules

OkayCMS modules use the following versioning format:

MAJOR.MINOR.PATCH

For example:

1.0.0

Each number in the version has a specific purpose and should be updated depending on the type of changes made.

Example of version progression:

1.0.0 → 1.0.1 → 1.0.2 → 1.1.0 → 1.2.0 → 2.0.0

Important: the version specified in module.json must match the Git tag version.

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

If the versions do not match, the Marketplace will not be able to correctly identify the new module release.

Publishing a Module to the Repository

After development is complete, the module must be published to the repository and a Git tag must be created. The OkayCMS Marketplace uses Git tags to detect new module versions and import them automatically.

The publishing process consists of two steps:

1. Save the changes in Git (commit).

2. Create a Git tag for the new module version.

Step 1. Create a Commit

After finishing development, add all changes to Git and create a commit in the module branch.

git add . git commit -m "First release" git push origin popup_cart

After running these commands, the module code will be saved and pushed to the Bitbucket repository.

Step 2. Create a Git Tag

After publishing the code, create a version tag. For the first release, this is typically version 1.0.0.

git tag popup_cart_1.0.0 git push origin popup_cart_1.0.0

Once the tag is pushed, Bitbucket will send the information through a webhook, and the Marketplace will automatically import the new module version.

For example:

popup_cart_1.0.0 popup_cart_1.1.0 popup_cart_1.2.0

After creating the Git tag, the new module version will automatically appear in the OkayCMS Marketplace.

Updating OkayCMS in a Module

During module development, the main master branch may receive updates over time. To keep your module compatible with the latest OkayCMS version, you should update your module branch using Git merge.

All module development should be performed only within the module's own branch.

First, switch to the module branch:

git checkout popup_cart

Then merge the latest changes from the master branch:

git merge master

At this stage, you will:

1. Receive the latest changes from the clean OkayCMS version;

2. Update your module branch;

3. Preserve your module-specific changes;

4. Maintain compatibility with the current OkayCMS version.

How does it work?

After running git merge master, the latest changes from master are merged into your module branch, while the module itself remains in its own branch and continues to evolve independently.

Such actions may lead to conflicts, lost changes, or problems during future updates.

Demo Content

If your module requires demonstration data, it should be placed in a separate file:

1DB_changes/demo.sql

This file is used to import demo content during module installation or testing.

At this stage, you will:

1. prepare demonstration data for the module;

2. simplify functional testing;

3. show the module's capabilities on a test website;

4. maintain compatibility with the system and the Marketplace.

Use only: 1DB_changes/demo.sql

Do not use: 1DB_changes/okay_clean.sql

The okay_clean.sql file is used to deploy a clean OkayCMS installation and is not intended for storing module demo data.

Why use a separate demo.sql file?

1. provides demonstration data for the module;

2. is safe to import on test websites;

3. does not affect OkayCMS settings;

4. can be easily removed together with the module.

README for Users

It is recommended to create a README.md file for every module. This serves as the primary user documentation and helps users quickly install, configure, and use the module.

The file should be placed at:

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

At this stage, you will:

1. prepare documentation for users;

2. simplify module installation;

3. reduce the number of support requests;

4. improve the overall user experience.

The README should ideally describe:

• the installation process;

• module configuration;

• required template modifications (if any);

• the main module features and settings.

Example README structure:

1. Installation

2. Configuration

3. Required Template Changes

4. Additional Information

If the module requires adding code to a template, it is recommended to provide a ready-to-use example and specify exactly where the code should be inserted.

A well-written README.md file makes module installation and configuration much easier for end users.

Connecting the Marketplace

After creating the repository, you need to grant the Marketplace access to it and configure automatic update notifications. To do this, add the SSH key and Webhook information available in your modules account.

Step 1. Add the SSH Key

In Bitbucket, open:

Repository settings → Access keys

Add the SSH key provided in your modules account.

The SSH key allows the Marketplace to access your repository and download module files.

Step 2. Configure the Webhook

In Bitbucket, open:

Repository settings → Webhooks

Add the Webhook URL provided in your modules account.

After every Git tag creation or repository update, Bitbucket will automatically notify the Marketplace about the changes.

What happens after the setup?

When a new Git tag is created, the Marketplace automatically:

1. receives a notification from Bitbucket;

2. downloads the new module version from the repository;

3. updates the module information;

4. publishes the new version in the Marketplace.

Workflow:

Git tag ↓ Bitbucket ↓ Webhook ↓ OkayCMS Marketplace ↓ New module version

Without a configured SSH key and Webhook, the Marketplace will not be able to automatically retrieve changes from your repository or publish new module versions.

How to Avoid Common Mistakes

When publishing modules for the first time, developers often make the same mistakes. Most of these issues lead to problems with module imports, release creation, or the automatic operation of the Marketplace.

In most cases, these mistakes can be detected before publishing the first module release.

These simple checks help identify most issues before publication and significantly reduce the risk of problems during the first module release.