Ana içeriğe atla
Bu belge, Zonely için modül geliştiren ekiplerin uyması gereken genel standartları açıklar. Amaç; temiz paketler hazırlamak, paketleri doğru şablonlara uygulamak ve güvenli şekilde yayınlamaktır.

​
Modül Mantığı

Zonely modülleri ZIP paketi olarak yüklenir. Panel paketi doğrular ve geçerliyse seçilen alan adına uygular. Genel akış:
  1. Modülü ZIP dosyası olarak hazırlayın.
  2. Panel ZIP içeriğini doğrular.
  3. Modül seçilen alan adına uygulanır.
  4. Gerekirse şablon değişiklikleri etkinleştirilir.
  5. Public etkinse modül 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 yüklenirse panel bunu güncelleme olarak işler.
  • Yayın takibi için version değerini artırın.
  • Yazar, açıklama ve sürüm bilgileri paket yapılandırmasından okunur.

​
ZIP Yapısı

ZIP içinde en az bir yapılandırma dosyası bulunmalıdır: 
config.json
module.json
manifest.json
manifest/config.json
Şablon, varlık ve API dosyaları tutarlı bir klasör yapısını izlemelidir. Paket içinde ilgisiz veya gereksiz dosya bulundurmayın.

​
Şablon Kuralları

  • Şablonlar için .tpl formatını kullanın.
  • Tema yollarını doğru ve tutarlı tutun.
  • Yeni şablon ekliyorsanız bunları tema uyumlu yolların altına yerleştirin.
Örnek: 
templates/Views/Themes/Norix/Pages/Store/main.campaigns.tpl
templates/Views/Themes/Norix/Navigations/campaigns.menu.tpl
admincp_templates/Drawers/main.campaigns.tpl

​
Rota Eşleştirme

Yeni eklenen bir şablon otomatik olarak rotaya bağlanmaz. Rota üzerinden çağrılması gerekir. Örnek frontend rotası: 
RewriteRule ^campaigns/?$ /Files/Controllers/ControllersAll.php?main=Handlers&container=MainHandlers&route=main.campaigns [L,QSA,NC]
Örnek yönetici rotası: 
RewriteRule ^admin/campaigns/?$ /Files/Controllers/ControllersAll.php?main=Handlers&container=AdminHandlers&route=main.campaigns [L,QSA,NC]

​
Mevcut Dosya Değiştirme Stratejisi

Kararlı modül güncellemeleri için:
  1. Hedef dosyayı modülünüzde aynı göreli yol ile ekleyin.
  2. Yalnızca gerekli kısımları değiştirin.
  3. Geniş kapsamlı ve gereksiz düzenlemelerden kaçının.
Bu yaklaşım bakımı kolaylaştırır ve fark takibini daha temiz hale getirir.

​
API Kuralları (Genel)

Modül API dosyaları modül paketi içinde tanımlanmalı ve işlem adları üzerinden kullanılmalıdır. Temel ilkeler:
  • Her işlem açıkça tanımlanmalıdır.
  • İzin verilen yöntemler (GET/POST vb.) net olmalıdır.
  • Yanıtlar tutarlı bir JSON formatını izlemelidir.
  • Hatalar açık ve tutarlı mesajlar döndürmelidir.

​
API Çağrıları İçin Gereksinimler

Bir modül işlem isteği için:
  1. module_id ve action gönderilmelidir.
  2. İşlem modül yapılandırmasında tanımlanmış olmalıdır.
  3. Modül mevcut alan adı için aktif olmalıdır.
  4. İstek yöntemi izin verilen yöntemlerle eşleşmelidir.
  5. Özel işlemler kimliği doğrulanmış bir oturum gerektirir.

​
Örnek Modül Yerleşimi

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": "Adds a campaign widget to the homepage.",
  "image": "preview.png",
  "targetThemes": ["Norix"],
  "api": {
    "campaign.list": { "public": true, "methods": ["GET"] }
  }
}

​
Örnek Widget Dosyası

<div class="campaign-widget">
  <h3>Campaigns</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 API Çağrısı Örneği

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 Yanıtı Alanları

Yükleme sırasında veya çalışma zamanında oluşan panel hataları genellikle şunları içerir: 
message
errors[]
errorType

​
Hızlı Kontrol Listesi

Yayından önce:
  • Yapılandırma dosyası mevcut.
  • Modül kimliği ve sürüm doğru.
  • Şablon yolları tema yapısıyla eşleşiyor.
  • API işlem tanımları eksiksiz.
  • JSON yanıt formatı geçerli.
  • Modül doğru alan adı ve tema üzerinde test edildi.

​
Son Not

En kararlı modüller; temiz paketler, açık işlem tanımları ve kontrollü şablon değişiklikleriyle oluşturulur.