Ana içeriğe atla
Bu doküman, Zonely için modül geliştiren ekiplerin kullanacağı genel standartları anlatır. Amaç: modül paketini doğru hazırlamak, doğru şablonlara uygulamak ve sorunsuz yayın almaktır.

​
Modül mantığı

Zonely modülleri ZIP paket olarak yüklenir. Panel, paketi doğrular ve uygun ise seçilen alan adına uygular. Genel akış:
  1. Modül ZIP olarak hazırlanır.
  2. Panel ZIP içeriğini kontrol eder.
  3. Modül seçilen alan adına uygulanır.
  4. Gerekirse şablon değişiklikleri devreye alınır.
  5. Herkese Açık işaretlenirse topluluk listesinde görünür.

​
Güncelleme mantığı

Mevcut bir modülü güncellemek için modül kimliği (id) aynı kalmalıdır.
  • Aynı id ile yükleme yapılırsa panel bunu güncelleme olarak işler.
  • Sürüm (version) arttırılarak değişiklik takibi yapılır.
  • Yapımcı, açıklama, sürüm gibi bilgiler paket içindeki config dosyasından okunur.

​
ZIP yapısı

ZIP içinde en az bir config dosyası bulunmalıdır: 
config.json
module.json
manifest.json
manifest/config.json
Modül paketinde şablon, kaynak ve API dosyaları düzenli klasör yapısıyla tutulmalıdır. Paket içinde gereksiz/ilgisiz dosya taşınmaması önerilir.

​
Şablon kuralları

  • Şablon tarafında .tpl formatı kullanılmalıdır.
  • Tema yolları doğru ve tutarlı olmalıdır.
  • Yeni şablon ekliyorsanız tema yapısına uygun klasöre koyun.
Örnek: 
templates/Views/Themes/Norix/Pages/Store/main.campaigns.tpl
templates/Views/Themes/Norix/Navigations/campaigns.menu.tpl
admincp_templates/Drawers/main.campaigns.tpl

​
Route bağlantısı

Yeni eklenen bir şablonun çalışması için route tarafında çağrılması gerekir. Örnek frontend route: 
RewriteRule ^campaigns/?$ /Files/Controllers/ControllersAll.php?main=Handlers&container=MainHandlers&route=main.campaigns [L,QSA,NC]
Örnek admin route: 
RewriteRule ^admin/campaigns/?$ /Files/Controllers/ControllersAll.php?main=Handlers&container=AdminHandlers&route=main.campaigns [L,QSA,NC]

​
Mevcut dosyada değişiklik yaklaşımı

Modül güncellemelerinde en güvenli yöntem:
  1. Hedef dosyayı aynı relatif yol ile modüle eklemek.
  2. Sadece gereken bölümü değiştirmek.
  3. Gereksiz geniş değişiklikten kaçınmak.
Bu yaklaşım hem bakım sürecini kolaylaştırır hem de fark takibini temiz tutar.

​
API kuralları (genel)

Modül API dosyaları modül paketi içinde tanımlanmalı ve action bazlı kullanılmalıdır. Temel prensip:
  • Her action açık şekilde tanımlı olmalı.
  • Method (GET/POST vb.) net belirlenmeli.
  • Cevaplar standart JSON formatında dönmelidir.
  • Hata durumunda tutarlı hata mesajı dönülmelidir.

​
API çağrısının çalışması için gerekenler

Bir modül action çağrısında:
  1. module_id ve action gönderilmelidir.
  2. İlgili action, modül config içinde tanımlı olmalıdır.
  3. Modül ilgili alanda aktif olmalıdır.
  4. Method kuralı ile çağrı methodu uyumlu olmalıdır.
  5. Action private ise yetkili oturum gereklidir.

​
Örnek modül yapısı

campaign-module.zip
|- config.json
|- preview.png
|- templates/
|  `- Views/
|     `- Themes/
|        `- Norix/
|           `- Pages/
|              `- Widgets/
|                 `- campaign.widget.tpl
|- template_changes/
|  `- Views/
|     `- Themes/
|        `- Norix/
|           `- Pages/
|              `- Main/
|                 `- main.home.tpl
`- api/
   `- campaign/
      `- list.php

​
Örnek config.json

{
  "id": "campaign-module",
  "name": "Campaign Module",
  "version": "1.0.0",
  "author": "Zonely Team",
  "description": "Ana sayfaya kampanya widget'i ekler.",
  "image": "preview.png",
  "targetThemes": ["Norix"],
  "api": {
    "campaign.list": { "public": true, "methods": ["GET"] }
  }
}

​
Örnek widget dosyası

<div class="campaign-widget">
  <h3>Kampanyalar</h3>
  <div id="campaign-list"></div>
</div>

​
Örnek API dosyası

<?php
$stmt = $db->prepare("SELECT id, title FROM campaigns WHERE domain = ? ORDER BY id DESC LIMIT 5");
$stmt->execute([$moduleDomain]);
$rows = $stmt->fetchAll(PDO::FETCH_ASSOC);

$moduleRespond([
    "status" => "success",
    "data" => $rows
], 200);
return;

​
Frontend tarafında API çağrısı

const base = '/Files/Controllers/ControllersAll.php?main=Handlers&container=TemplatesModulesApiController';
const url = new URL(base, window.location.origin);
url.searchParams.set('module_id', 'campaign-module');
url.searchParams.set('action', 'campaign.list');

fetch(url.toString(), {
  method: 'GET',
  credentials: 'same-origin'
})
  .then((r) => r.json())
  .then((payload) => {
    console.log(payload.data);
  });

​
Hata dönüşleri

Panel yükleme veya çağrı sırasında hata döndürdüğünde genelde şu alanlar kullanılır: 
message
errors[]
errorType

​
Kısa kontrol listesi

Yayın öncesi kontrol:
  • Config dosyası mevcut mu.
  • Modül kimliği ve sürüm doğru mu.
  • Şablon yolları tema yapısıyla uyumlu mu.
  • API action tanımları eksiksiz mi.
  • JSON cevap formatı düzgün mü.
  • Modül doğru alan adı ve doğru tema için test edildi mi.

​
Son not

Modül geliştirirken sade paket, net action yapısı ve kontrollü şablon değişikliği yaklaşımı uzun vadede en stabil sonucu verir.