Citrus CMS - Geliştirici Dokümantasyonu

İçindekiler

1. Proje Genel Bakış
2. Klasör Yapısı
3. Modül Sistemi
4. Kimlik Doğrulama (Auth) Sistemi
5. Types Tablosu ve Kullanımı
6. Controller Yapısı
7. Helper Fonksiyonlar
8. DevExtreme Entegrasyonu
9. Admin-AJAX Sistemi
10. Şablonlar ve Bileşenler
11. Yeni Modül Geliştirme
12. Middleware ve İzin Sistemi

Proje Genel Bakış

Bu proje, Laravel framework'ü üzerine inşa edilmiş, Trunçgil Teknoloji tarafından geliştirilen Citrus CMS yönetim paneli uygulamasıdır. Temel olarak aşağıdaki özellikleri içermektedir:

• Modüler yapı
• Kullanıcı yetkilendirme ve rol bazlı izin sistemi
• DevExtreme ile gelişmiş kullanıcı arayüzü
• Excel import/export işlemleri
• Dinamik form ve alan yönetimi
• Çoklu dil desteği
• Çeşitli helper fonksiyonlar

Klasör Yapısı

Projenin ana klasör yapısı Laravel'in standart yapısına uygundur, ancak bazı özel klasör ve dosyalar eklenmiştir:

• app/ - Uygulamanın ana kaynak kodu
  • Functions/ - Özel fonksiyonlar
  • Helpers/ - Yardımcı fonksiyonlar
  • Models/ - Veritabanı modelleri
  • DevExtreme/ - DevExtreme entegrasyonu için gerekli sınıflar
  • Http/Controllers/ - Controller sınıfları
• resources/ - Görünüm şablonları ve ön yüz varlıkları
• routes/ - Uygulama rotaları
• config/ - Yapılandırma dosyaları
• public/ - Genel erişilebilir dosyalar
• storage/ - Uygulama tarafından oluşturulan dosyalar için depolama alanı

Modül Sistemi

Proje modüler bir yapıda geliştirilmiştir. Her bir modül (örneğin WeldLog, TestPackage, vb.) kendi Model, Controller ve View dosyalarına sahiptir. Modüller, Types tablosu üzerinden yönetilmektedir.

Modül Yapısı

Tipik bir modül şu bileşenlerden oluşur:

1. Model - app/Models/ altında
2. Controller - app/Http/Controllers/ altında
3. Views - resources/views/admin/ altında
4. Routes - routes/web.php içinde tanımlı

Kimlik Doğrulama (Auth) Sistemi

Laravel'in varsayılan kimlik doğrulama sistemi kullanılmaktadır, ancak genişletilmiş yetkilendirme ve rol yönetimi uygulanmıştır.

Kullanıcı Seviyeleri

Kullanıcılar farklı seviyelere (level) sahip olabilir:

• Admin
• Manager
• User
• vb.

Her seviye için farklı izin ayarları tanımlanabilir.

Middleware

Uygulamada PermissionControl adlı özel bir middleware kullanılmakta, bu middleware kullanıcının erişim isteklerini kontrol etmektedir.

// Middleware örneği
if(in_array($thisPath, $onlyAdminPath)) {
    if(!isAdmin()) {
        echo "Only admin can access this area.";
        exit();
    }
}

Types Tablosu ve Kullanımı

types tablosu, sistemdeki modülleri tanımlamak için kullanılır. Bu tablo aşağıdaki alanları içerir:

• id - Benzersiz tanımlayıcı
• title - Modül başlığı
• slug - URL-dostu benzersiz string
• fields - Modülün içerdiği alanlar (virgülle ayrılmış liste)

Her modül için gerekli alanlar Fields tablosunda saklanır ve bu tablo aracılığıyla formlar ve tablolar dinamik olarak oluşturulur.

Controller Yapısı

Projede controller'lar genellikle şu yapıda düzenlenmiştir:

AdminController

AdminController temel CRUD işlemleri ve admin paneli yönetimi için kullanılır. Örnek metotlar:

• index() - Admin panel ana sayfası
• action() - İçerik ekleme, silme, güncelleme
• importExcel() - Excel'den veri içe aktarma
• exportExcel() - Veriyi Excel olarak dışa aktarma
• delete() - Kayıt silme

Modül Controllerleri

Her modül genellikle kendi controller'ına sahiptir. Örneğin WeldLogController, TestPackageController vb.

Helper Fonksiyonlar

Projede çeşitli yardımcı fonksiyonlar bulunmaktadır. Bunlar app/Functions/ ve app/Helpers/ dizinlerinde saklanır.

Sık kullanılan helper fonksiyonlardan bazıları:

• u() - Mevcut kullanıcıyı döndürür
• db($table) - Belirtilen tabloya erişim sağlar
• setting($key) - Sistem ayarlarına erişim
• isAdmin() - Kullanıcının admin olup olmadığını kontrol eder
• userPermissions() - Kullanıcı izinlerini döndürür

DevExtreme Entegrasyonu

Proje, kullanıcı arayüzü için DevExtreme bileşenlerini kullanmaktadır. DevExtreme, veri tablolarını ve formları hızlı bir şekilde oluşturmak için kullanılan JavaScript tabanlı UI komponent kütüphanesidir.

DevExtreme Bileşenleri ve Yapısı

DevExtreme entegrasyonu için özel sınıflar app/DevExtreme/ klasöründe bulunur:

• Utils - Genel yardımcı fonksiyonlar
• FilterHelper - Filtreleme için yardımcı fonksiyonlar
• DbSet - Veritabanı sorguları için yardımcı sınıf

CRUD İşlemleri

Önemli Not: Sistemdeki tüm modüllerin CRUD (Create, Read, Update, Delete) işlemleri AdminController.php üzerinden yürütülmektedir. Bu merkezi yaklaşım, kod tekrarını önler ve tutarlı bir API sağlar.

AdminController içindeki temel CRUD metotları:

• tableToJson - Veritabanı tablosunu JSON formatına dönüştürür (Read)
• insertJson - Yeni kayıt ekler (Create)
• saveJson - Mevcut kaydı günceller (Update)
• removeJson - Kaydı siler (Delete)

Tüm modüller, işlemlerini bu metotlar üzerinden gerçekleştirir ve özel bir controller geliştirmeye gerek kalmaz.

DevExtreme DataGrid

DataGrid, veri tablosunu görüntülemek için kullanılan ana bileşendir. JavaScript tarafında aşağıdaki özellikleri destekler:

• Filtreleme ve sıralama
• Sayfalama
• Satır düzenleme
• Grup oluşturma
• Özet bilgileri
• Özel düğmeler ve işlemler

Admin-AJAX Sistemi

Projede AJAX tabanlı istekler için özel bir sistem kullanılmaktadır. Bu sistem, AdminAjaxController tarafından yönetilir ve admin paneli içerisinde yapılan asenkron istekleri işler.

URL Yapısı

Admin-AJAX istekleri için URL yapısı şu şekildedir:

/admin-ajax/{işlem_adı}

Burada {işlem_adı}, gerçekleştirilecek AJAX işlemini belirtir. Örneğin:

/admin-ajax/get-users
/admin-ajax/update-status
/admin-ajax/save-form

Controller Yapısı

Admin-AJAX Controller'ı şu şekilde çalışır:

// app/Http/Controllers/AdminAjaxController.php
public function index(Request $request, string $var) {
    $u = Auth::user();
    if(!isset($u->level)) {
        echo("permission error");
        exit();
    }
    
    $url = "admin-ajax.$var";
    
    return view($url, array(
        "request" => $request     
    ));
}

Bu yapı, AJAX isteğini uygun view dosyasına yönlendirir. View adı admin-ajax.{işlem_adı} formatında olmalıdır.

View Dosyaları

AJAX view dosyaları resources/views/admin-ajax/ dizininde bulunur. Her bir AJAX işlemi için ayrı bir blade dosyası oluşturulmalıdır:

resources/views/admin-ajax/get-users.blade.php
resources/views/admin-ajax/update-status.blade.php
resources/views/admin-ajax/save-form.blade.php

Yeni AJAX İşlemi Ekleme

Yeni bir AJAX işlemi eklemek için:

1. İlgili view dosyasını oluşturun:

// resources/views/admin-ajax/yeni-islem.blade.php
@php
// İsteği işleyin
$data = db('tablo_adi')->get();

// JSON formatında yanıt döndürün
echo json_encode([
    'status' => 'success',
    'data' => $data
]);
@endphp

2. View dosyasını çağıran JavaScript kodu:

$.ajax({
    url: '/admin-ajax/yeni-islem',
    type: 'POST',
    data: {
        parametre1: deger1,
        parametre2: deger2,
        _token: csrf_token // CSRF koruması için gerekli
    },
    success: function(response) {
        // Başarılı yanıtı işleyin
    },
    error: function(error) {
        // Hatayı işleyin
    }
});

Güvenlik Önlemleri

Admin-AJAX isteklerinde şu güvenlik önlemleri uygulanmaktadır:

• Tüm istekler için kimlik doğrulama kontrolü
• CSRF koruma tokeni
• Kullanıcı seviyesine göre yetkilendirme

Şablonlar ve Bileşenler

Proje, birçok tekrar kullanılabilir şablon ve bileşen içerir. Bu bileşenler, modül geliştirme sürecini kolaylaştırır ve tutarlı bir kullanıcı arayüzü sağlar.

Şablon Sistemi

Sistem içinde kullanılan ana şablonlar:

sablon4.blade.php

resources/views/admin/type/sablon4.blade.php dosyası, modül sayfalarını oluşturmak için kullanılan temel şablondur. Yeni bir modül geliştirirken, model ve migration oluşturduktan sonra bu şablonu kullanmak genellikle yeterlidir. Şablonun başında tanımlanan değişkenler ile özelleştirilebilir.

Temel özelleştirme değişkenleri:

// Modül başlığı
$title = "Radiographic Test";
// Tabloyu oluşturmak için kullanılan model
$listDatas = RadiographicTest::orderBy("id","DESC")->paginate(setting('row_count'));
// Veritabanı tablo adı
$tableName = "radiographic_tests";
// Blok grupları - alanları kategorilere bölmek için
$blockGroup = [    
    'Info' => [
        'report_file',
        'contractor',
    ],
    // Diğer gruplar...
];
// Dosya yükleme klasörü
$firstUploadFolder = '004_QA/0001_RT/';
// Dosya yükleme başlığı
$firstUploadTitle = 'Upload PDF';

module-block.blade.php

resources/views/components/blocks/module-block.blade.php dosyası, modülün ana içeriğini oluşturan ve DataGrid'i görüntüleyen bileşendir. Bu bileşen, sablon4.blade.php içinde çağrılır ve aşağıdaki özellikleri içerir:

• Alan listesi oluşturma
• Alan tiplerini belirleme
• Sütun seçimini yönetme
• Excel içe/dışa aktarma işlemleri
• DataGrid entegrasyonu

// Dışa aktarma, sütun seçimi ve diğer işlemler için temel ayarlar
$options = [
    'export' => $tableName,
];
// DataGrid dahil etme
@include("components.table.$tableType")

datagrid.blade.php

resources/views/components/table/datagrid.blade.php dosyası, DevExtreme DataGrid'i entegre eder ve aşağıdaki özellikleri sağlar:

• Sütun tiplendirme ve düzenleme
• Filtreleme ve sıralama
• Veri işleme (CRUD)
• Klavye kısayolları
• Özel stil ve davranışlar
• Validation işlemleri

Bu dosya, JavaScript kodunu da içerir ve DataGrid'in tüm davranışlarını yapılandırır:

var dataGrid = $("#dataGrid").dxDataGrid({
    // DataGrid ayarları
    dataSource: dataSource,
    keyExpr: "{{$tableName}}",
    allowColumnResizing: true,
    // Diğer yapılandırmalar...
});

upload.blade.php

resources/views/admin/type/document/upload.blade.php dosyası, dosya yükleme işlemlerini yönetir. Özellikle PDF dosyalarını yüklemek için kullanılır. Aşağıdaki özellikleri içerir:

• Dropzone.js entegrasyonu
• Modal pencere ile yükleme arayüzü
• Birden fazla yükleme bölümü
• Özel klasörlere dosya yükleme

Bu bileşen, sablon4.blade.php içinde @include("admin.type.document.upload") ile dahil edilir.

Form Elemanları ve Alan Tipleri

DataGrid içinde kullanılabilen farklı alan tipleri vardır:

• text - Standart metin girişi
• date - Tarih seçici
• number - Sayısal değer girişi
• select - Dropdown liste
• auto-complete - Otomatik tamamlama
• link-search - Bağlantı ve arama
• decimal - Ondalık sayı girişi
• checkbox - Onay kutusu

Her alan tipi için components/table/datagrid/{tip}.blade.php altında bir şablon vardır.

Örnek olarak select tipi için kullanım:

$relationDatas = [
    'field_name' => [
        'type' => 'select',
        'datas' => [
            'option1' => 'Option 1',
            'option2' => 'Option 2'
        ]
    ]
];

Yeni Modül Geliştirme

Citrus CMS'de yeni bir modül oluşturmak için iki yöntem bulunmaktadır: Module Generator Wizard (Önerilen) ve Manuel Yöntem.

1. Module Generator Wizard (Önerilen)

Sistemde bulunan "Module Generator" sihirbazı, bir modül için gerekli olan tüm dosyaları ve veritabanı işlemlerini otomatik olarak gerçekleştirir.

Adımlar:

1. Sol menüden İçerik Yönetimi (Content Management) > Module Generator sayfasına gidin.
2. Temel Bilgiler: Modül başlığını girin ve bir ikon (PNG) yükleyin.
3. Veritabanı Sütunları: Modülde yer alacak alanları tanımlayın:
   • Sütun adı, veri tipi (String, Integer, Long Text, Date, Boolean vb.) seçin.
   • Açılır menüler (Select) veya API bağlantılı listeler (API Dropdown) için gelişmiş ayarları yapın.
4. Onay ve Oluştur: "Generate Module Now" butonuna tıkladığınızda sistem şunları otomatik yapar:
   • Veritabanı Migration dosyasını oluşturur ve çalıştırır.
   • Eloquent Model dosyasını (app/Models/) oluşturur.
   • Gelişmiş Datagrid içeren Blade View dosyasını (resources/views/admin/type/) oluşturur.
   • types tablosuna gerekli kaydı ekler.

Bu işlemden sonra modülünüz hemen kullanıma hazır hale gelir.

2. Manuel Yöntem

Daha özel ihtiyaçlar için modülü manuel olarak da oluşturabilirsiniz:

1. Model ve Migration Oluşturun:

   // app/Models/YeniModul.php
   namespace App\Models;
   
   use Illuminate\Database\Eloquent\Model;
   
   class YeniModul extends Model
   {
       protected $table = 'yeni_modul';
       protected $primaryKey = 'id';
       public $timestamps = true;
   }
   

   // database/migrations/xxxx_create_yeni_modul_table.php
   public function up()
   {
       Schema::create('yeni_modul', function (Blueprint $table) {
           $table->id();
           $table->string('ad')->nullable();
           $table->text('aciklama')->nullable();
           $table->timestamps();
       });
   }
   

2. Şablonu Kopyalayın ve Özelleştirin:

   • resources/views/admin/type/ dizini altında yeni bir blade dosyası oluşturun (Örn: yeni-modul.blade.php).
   • datagrid-module-template.blade.php veya sablon4.blade.php temel alınarak özelleştirme yapabilirsiniz.

3. Type Tablosuna Kayıt Ekleyin:

   • Admin panelinden Modüller sayfasına gidin ve yeni bir kayıt ekleyin.
   • Slug kısmına oluşturduğunuz blade dosyasının adını yazın.

Önemli Not: Tüm CRUD işlemleri otomatik olarak AdminController.php üzerinden yönetilir. Özel bir controller kodlamanıza genellikle gerek yoktur.

Middleware ve İzin Sistemi

Uygulamada izin kontrolü şu şekilde yapılmaktadır:

1. Kullanıcı Seviyeleri: Her kullanıcı bir seviyeye sahiptir (level alanı)
2. İzin Tanımları: Her modül için okuma, yazma, tam kontrol izinleri tanımlanır
3. Middleware Kontrolü: Kullanıcının sahip olduğu seviyeye göre izin kontrolleri yapılır

// İzin kontrolü örneği
if(isAuth($modulAdi, "read")) {
    // Okuma izni var, işleme devam et
} else {
    // İzin yok, erişim engellendi
}

Kullanıcı İzin Kontrolü

userPermissions() fonksiyonu kullanıcının izinlerini döndürür ve isAuth() fonksiyonu belirli bir işlem için izin kontrolü yapar.

---

Bu dokümantasyon, projenin temel yapısını ve özelliklerini kapsamaktadır. Daha detaylı bilgi için ilgili kaynak kodları inceleyebilir veya ekip ile iletişime geçebilirsiniz.