truncgit/citrus-cms

Fork 0

Files

T

Ümit Tunç 551d642325 docs: update README documentation to reflect current project configuration

2026-04-29 07:57:37 +03:00

17 KiB

Raw Blame History

Citrus CMS - Geliştirici Dokümantasyonu

İçindekiler

Proje Genel Bakış
Kurulum
Klasör Yapısı
Modül Sistemi
Kimlik Doğrulama (Auth) Sistemi
Types Tablosu ve Kullanımı
Controller Yapısı
Helper Fonksiyonlar
DevExtreme Entegrasyonu
Admin-AJAX Sistemi
Şablonlar ve Bileşenler
Yeni Modül Geliştirme
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

Kurulum

Projeyi yerel ortamınızda ayağa kaldırmak için aşağıdaki adımları izleyin:

Bağımlılıkları Yükleyin:
```
composer install
```
Yapılandırma Dosyasını Hazırlayın: .env.example dosyasını .env olarak kopyalayın ve veritabanı bilgilerinizi düzenleyin.
```
cp .env.example .env
```
Uygulama Anahtarını Oluşturun:
```
php artisan key:generate
```
Veritabanı Migrasyonlarını Çalıştırın:
```
php artisan migrate
```

Admin Hesabı Oluşturma ve Şifre Üretme

Sisteme giriş yapabilmek için bir admin hesabı oluşturmanız veya mevcut admin hesabının şifresini sıfırlamanız gerekebilir. Bunun için özel bir Artisan komutu mevcuttur:

php artisan admin:create

Bu komutu çalıştırdığınızda:

admin@citrus.com e-posta adresi ile bir kullanıcı oluşturulur (varsa şifresi sıfırlanır).
12 karakterli rastgele ve güvenli bir şifre üretilir.
Kullanıcıya tam yetki (ALL PRIVILEGES) tanımlanır.
Üretilen giriş bilgileri terminal ekranında görüntülenir.

Important

Güvenlik nedeniyle, üretim (production) ortamında admin şifresini oluşturduktan sonra bu bilgileri güvenli bir yerde saklamanız ve gerekirse panel üzerinden değiştirmeniz önerilir.

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:

Model - app/Models/ altında
Controller - app/Http/Controllers/ altında
Views - resources/views/admin/ altında
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:

İ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

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:

Sol menüden İçerik Yönetimi (Content Management) > Module Generator sayfasına gidin.
Temel Bilgiler: Modül başlığını girin ve bir ikon (PNG) yükleyin.
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.
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:

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();
    });
}

Ş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.
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:

Kullanıcı Seviyeleri: Her kullanıcı bir seviyeye sahiptir (level alanı)
İzin Tanımları: Her modül için okuma, yazma, tam kontrol izinleri tanımlanır
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.

17 KiB Raw Blame History Unescape Escape

Citrus CMS - Geliştirici Dokümantasyonu

İçindekiler

Proje Genel Bakış

Kurulum

Admin Hesabı Oluşturma ve Şifre Üretme

Klasör Yapısı

Modül Sistemi

Modül Yapısı

Kimlik Doğrulama (Auth) Sistemi

Kullanıcı Seviyeleri

Middleware

Types Tablosu ve Kullanımı

Controller Yapısı

AdminController

Modül Controllerleri

Helper Fonksiyonlar

DevExtreme Entegrasyonu

DevExtreme Bileşenleri ve Yapısı

CRUD İşlemleri

DevExtreme DataGrid

Admin-AJAX Sistemi

URL Yapısı

Controller Yapısı

View Dosyaları

Yeni AJAX İşlemi Ekleme

Güvenlik Önlemleri

Şablonlar ve Bileşenler

Şablon Sistemi

sablon4.blade.php

module-block.blade.php

datagrid.blade.php

upload.blade.php

Form Elemanları ve Alan Tipleri

Yeni Modül Geliştirme

1. Module Generator Wizard (Önerilen)

2. Manuel Yöntem

Middleware ve İzin Sistemi

Kullanıcı İzin Kontrolü

17 KiB

Raw Blame History

`sablon4.blade.php`

`module-block.blade.php`

`datagrid.blade.php`

`upload.blade.php`