AjaxFlow - Dokümantasyon

Bilgilendirme: AjaxFlow sürekli olarak güncellenmektedir. Sorularınız için admin@xkhod.com adresine mail atabilirsiniz.

AjaxFlow Kullanımı

AjaxFlow, projelerinize kolayca AJAX işlevselliği eklemenizi sağlayan hafif bir JavaScript kütüphanesidir. Formları ve input alanlarını AJAX ile gönderme, API'lerden veri çekme ve bu verileri sayfaya dinamik olarak yazdırma gibi işlemleri kolaylaştırır.

Projeye AjaxFlow Dahil Etme

AjaxFlow'un doğru çalışabilmesi için her iki dosyanın da projeye dahil edilmesi gerekir:

<script src="https://xkhod.com/lib/ajaxflow/ajaxflow.js" defer></script>
<script src="https://xkhod.com/lib/ajaxflow/lang.js" defer></script>

Geliştirme Modu

Geliştirme modunu aktif etmek için aşağıdaki kodu kullanmalısınız:

<body ajaxflow="dev">

Bu mod aktif edildiğinde, hata ayıklama ve bildirim loglarına konsoldan erişebilirsiniz.

Dil Desteği

AjaxFlow dil desteği sağlar. Türkçe veya İngilizce dil ayarını aşağıdaki gibi yapabilirsiniz:

<body ajaxflow="dev tr">

veya

<body ajaxflow="dev en">

Form Seçme İşlemi

Bir formu AJAX ile başlatmak için aşağıdaki kodu kullanabilirsiniz:

<form ajaxflow="start-form"></form>

Dilerseniz, formun ismini belirterek daha detaylı loglar alabilirsiniz:

<form ajaxflow="start-form" flow-name="girisformu"></form>

Birden fazla form veya input kullanıyorsanız, form isimlendirmesi önerilir. Bunun nedeni yanıtı yazdıracağınız elementi seçmenize yaramasıdır.

Input Seçme İşlemi

Bir input alanını AJAX ile başlatmak için aşağıdaki kodu kullanabilirsiniz:

<input type="text" ajaxflow="start-input">

Dilerseniz, input ismini belirterek daha detaylı loglar alabilirsiniz:

<input type="text" ajaxflow="start-input" flow-name="fiyat">

Birden fazla form veya input kullanıyorsanız, input isimlendirmesi önerilir. Bunun nedeni yanıtı yazdıracağınız elementi seçmenize yaramasıdır.

Yükleniyor Animasyonu (Loading)

Bir form veya input üzerinde AJAX işlemi gerçekleştirilirken, kullanıcıya bir yükleniyor animasyonu göstermek isteyebilirsiniz. Bunun için yapmanız gereken tek şey, sayfanıza ajaxflow="loading" eklemek:

<div ajaxflow="loading"></div>

Bu element, işlemler sırasında otomatik olarak ekranda siyah bir dönen yükleniyor çemberi olarak gösterilecek ve işlem tamamlandığında kaybolacaktır. Ayrıca, sayfada ortalanmış bir şekilde konumlanır ve herhangi bir ek CSS tanımlamanıza gerek kalmaz.

Yönlendirme (re-flow)

AJAX isteği başarılı olduğunda kullanıcıyı başka bir sayfaya yönlendirmek için re-flow özelliğini kullanabilirsiniz. Bu özellik, işlem tamamlandığında sayfanın nereye yönlendirilmesi gerektiğini belirtir.

Örneğin, bir form gönderildiğinde başarılı bir yanıt aldıktan sonra kullanıcıyı bir teşekkür sayfasına yönlendirmek için şu kodu kullanabilirsiniz:

<form ajaxflow="start-form" flow-name="exampleForm" action="test.php" re-flow="https://example.com/thankyou"></form>

Bu durumda, form başarılı bir şekilde gönderildiğinde kullanıcı belirtilen URL'ye yönlendirilir.

Yanıt (Response) Özelliği

Bir input veya formdan gelen yanıtı bir alana yazdırmak için ajaxflow="response" özelliğini kullanabilirsiniz. Yanıtı bir <div>, <span>, <p> gibi herhangi bir elemente yazdırabilirsiniz.

Bir örnek:

<div ajaxflow="response" flow-name="flowTest"></div>
Bilgilendirme: Burada dikkat etmeniz gereken nokta; flow-name kısmının her iki tarafta da aynı olmasıdır. 
<input type="text" ajaxflow="start-input" flow-name="flowTest" action="test.php" name="test">

Bu örnekte, formdan gelen yanıt bu <div> içine yazılacaktır.

Yanıt Zamanlayıcı (flow-set)

Response alanlarına yazılan mesajların belirli bir süre sonra kaybolmasını istiyorsanız, flow-set özelliğiyle süre tanımlayabilirsiniz.

Örneğin, yanıtın 3 saniye sonra kaybolmasını istiyorsanız:

<div ajaxflow="response" flow-name="formTest" flow-set="time-3"></div>

Bu örnek, yanıtın 3 saniye sonra kaybolmasını sağlar. time-1 ile 1 saniye, time-5 ile 5 saniye gibi zamanlayıcılar kullanabilirsiniz.

Flow-Tag Özelliği

Bir form veya input üzerinden veri gönderirken, belirli bir alan ile eşleşme yapmak istiyorsanız flow-tag özelliğini kullanabilirsiniz. Örneğin, bir ürünün fiyatını güncellerken, ürünü barkod gibi benzersiz bir değer ile eşleştirmek için bu özelliği kullanabilirsiniz.

Bu özelliği flow-tag ile tanımlayıp, form veya input ile ilişkili bir data özelliğiyle eşleştirebilirsiniz.

Bir örnek kullanım:

<form ajaxflow="start-form" flow-name="urunFormu" flow-tag="barkod" data-barkod="1342342342" action="test.php">
    <input type="text" name="fiyat" value="100.50">
    <button type="submit">Güncelle</button>
</form>

Bu örnekte, form gönderildiğinde barkod ve fiyat değerleri sunucuya gönderilecektir. Gönderilen JSON verisi şu şekilde olacaktır:

{
    "fiyat": "100.50",
    "barkod": "1342342342"
}

Sayfada bir JSON verisi almak ve bu veriyi HTML yapısına yazdırmak için get-link ve flow-get özelliklerini kullanabilirsiniz. Bu özellikler, API'lerden veri alıp, JSON verisindeki belirli alanları istediğiniz HTML elementine yazdırmak için kullanılır.

Get-Link Özelliği

Öncelikle, JSON verisinin nereden alınacağını belirtmek için get-link kullanılır. Bu özellik bir <div> içinde tanımlanır ve belirttiğiniz URL'den gelen JSON verisini alır.

Örneğin:

<div get-link="https://example.com/api/product">
    <p>Ürün Adı: <span flow-get="name"></span></p>
    <p>Fiyat: <span flow-get="price"></span></p>
    <p>Stok Durumu: <span flow-get="stock"></span></p>
</div>

Bu örnekte, get-link özelliği, belirtilen URL'ye istek gönderir ve dönen JSON verisindeki name, price, ve stock gibi alanları ilgili yerlere yazdırır.

Flow-Get Özelliği

flow-get ile, JSON verisindeki belirli alanları, HTML elementlerine yazdırabilirsiniz. flow-get özelliği, span, div, p gibi HTML etiketlerine eklenir ve API'den dönen JSON verisinin anahtarlarıyla eşleştirilir.

Örneğin, JSON verisi şu şekilde olabilir:

{
    "name": "Laptop",
    "price": 1500,
    "stock": 20
}

Bu JSON verisini flow-get kullanarak ilgili elementlere yazdırabilirsiniz:

<div get-link="https://example.com/api/product">
    <p>Ürün Adı: <span flow-get="name"></span></p>
    <p>Fiyat: <span flow-get="price"></span></p>
    <p>Stok Durumu: <span flow-get="stock"></span></p>
</div>

Bu kod çalıştırıldığında, API'den gelen ürün adı, fiyat ve stok durumu, belirtilen <span> elementlerine yazdırılacaktır.

Multi Özelliği (flow-set="multi")

Birden fazla veri içeren bir JSON yapısını HTML elementlerine yazdırmak için flow-set="multi" özelliğini kullanabilirsiniz. Bu özellik, JSON'dan dönen birden fazla öğeyi dinamik olarak sayfaya yazdırmak için kullanılır.

Multi Özelliği Kullanımı

Aşağıda, birden fazla ürün bilgisini içeren bir JSON örneği ve bunun flow-set="multi" ile nasıl işlendiğini görebilirsiniz:

[
    {
        "name": "Sample Product 1",
        "price": 100.50,
        "stock": 20
    },
    {
        "name": "Sample Product 2",
        "price": 150.00,
        "stock": 10
    },
    {
        "name": "Sample Product 3",
        "price": 200.00,
        "stock": 5
    }
]

Multi Özelliği ile HTML Kullanımı

Aşağıdaki örnekte, flow-set="multi" özelliği kullanılarak her bir ürün ayrı bir div içerisinde gösterilmektedir:

<div get-link="https://example.com/api/products" flow-set="multi">
    <div class="product-item">
        <p>Ürün Adı: <span flow-get="name"></span></p>
        <p>Fiyat: <span flow-get="price"></span></p>
        <p>Stok Durumu: <span flow-get="stock"></span></p>
    </div>
</div>

Bu örnekte, her ürün için flow-set="multi" özelliği, JSON verisindeki her bir öğe için ayrı bir div oluşturacaktır.

Önemli:
  • Multi Özelliği: flow-set="multi" özelliği sadece JSON dizilerini işler. Eğer JSON verisi bir dizi (array) değilse bu özellik çalışmaz.
  • Dev Mode: Geliştirme modunu açarak, JSON verisinin doğru işlenip işlenmediğini konsoldan takip edebilirsiniz.

Filtre Özelliği

AjaxFlow ile dinamik filtreleme işlemleri yapabilirsiniz. Kullanıcıların belirli kriterlere göre veri filtrelemesini sağlamak için ajaxflow="filter" ve flow-name özelliklerini kullanabilirsiniz.

Filtre Kullanımı

Aşağıdaki örnekte, ürünleri kategori ve arama terimine göre filtreleyebilirsiniz:

<!-- Filtreleme Alanları -->
<div ajaxflow="filter" flow-name="urunFiltre">
    <input type="text" name="arama" placeholder="Ara...">
    <select name="kategori">
        <option value="">Tüm Kategoriler</option>
        <option value="elektronik">Elektronik</option>
        <option value="kitap">Kitap</option>
    </select>
</div>

<!-- Sonuçları Gösterme Alanı -->
<div get-link="filter.php" flow-set="multi" flow-name="urunFiltre">
    <div class="product-item">
        <h4>Ürün Adı: <span flow-get="isim"></span></h4>
        <p>Fiyat: <span flow-get="fiyat"></span></p>
        <p>Stok: <span flow-get="stok"></span></p>
    </div>
</div>

Bu örnekte:

  • ajaxflow="filter" ile filtre alanlarını belirttik ve flow-name="urunFiltre" ile bu filtreye bir isim verdik.
  • get-link ve aynı flow-name ile sonuçların gösterileceği alanı belirledik.
  • Kullanıcı filtreleri değiştirdiğinde, sonuçlar otomatik olarak güncellenir.

PHP Örnek Dosyası (filter.php)

Sunucu tarafında filtreleme işlemini gerçekleştirmek için aşağıdaki örnek PHP kodunu kullanabilirsiniz:

<?php
// CORS ayarları
header("Access-Control-Allow-Origin: *");
header("Content-Type: application/json; charset=UTF-8");

// Statik ürün verileri
$urunler = [
    [
        "isim" => "Laptop",
        "fiyat" => 15000,
        "stok" => 5,
        "kategori" => "elektronik"
    ],
    [
        "isim" => "Kitap",
        "fiyat" => 25,
        "stok" => 100,
        "kategori" => "kitap"
    ],
    // Diğer ürünler...
];

// İstek metodunu al
$method = $_SERVER['REQUEST_METHOD'];

// Filtre verilerini al
if ($method === 'POST') {
    $input = json_decode(file_get_contents('php://input'), true);
    $filterData = $input;
} else {
    $filterData = $_GET;
}

// Filtreleme işlemi
$filteredProducts = array_filter($urunler, function ($urun) use ($filterData) {
    $arama = isset($filterData['arama']) ? $filterData['arama'] : '';
    $kategori = isset($filterData['kategori']) ? $filterData['kategori'] : '';

    // Arama filtresi
    if ($arama !== '' && stripos($urun['isim'], $arama) === false) {
        return false;
    }

    // Kategori filtresi
    if ($kategori !== '' && $urun['kategori'] !== $kategori) {
        return false;
    }

    return true;
});

// Sonuçları JSON formatında döndür
echo json_encode(array_values($filteredProducts), JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);

Bu kod ile kullanıcı filtreleri değiştirdiğinde, sonuçlar dinamik olarak güncellenecektir.

Not: Sunucu tarafında gerekli güvenlik ve doğrulama kontrollerini yapmayı unutmayınız.

Ek Özellikler

Error Handling ve Gelişmiş Bildirimler

AjaxFlow gelişmiş hata yönetimi ve bildirim desteği sunar. Sunucudan dönen hata mesajları ve kodları kullanıcıya daha detaylı iletilir.

Hata durumlarında ajaxflow="response" özelliği ile belirlediğiniz elemente hata mesajı yazdırılır. Başarı ve hata durumları için farklı CSS sınıfları kullanarak stil verebilirsiniz:

[ajaxflow="response"].success {
    color: green;
}

[ajaxflow="response"].error {
    color: red;
}

Örneğin:

<div ajaxflow="response" flow-name="loginForm"></div>

Esnek GET ve POST İstekleri

Artık isteklerin HTTP metodunu dinamik olarak belirleyebilirsiniz. Form veya input elementlerine method attribute'u ekleyerek istek metodunu seçebilirsiniz. Varsayılan olarak POST kullanılır.

Örneğin, bir PUT isteği göndermek için:

<form ajaxflow="start-form" flow-name="updateProduct" action="update.php" method="PUT">
    <input type="text" name="productName" value="Yeni Ürün">
    <button type="submit">Güncelle</button>
</form>

Benzer şekilde, input elemanlarında da kullanabilirsiniz:

<input type="text" ajaxflow="start-input" flow-name="deleteProduct" action="delete.php" method="DELETE" name="productId">

Event Emitters ve Listener'lar

AjaxFlow özel olaylar tanımlayarak akışın farklı noktalarında bu olayları yayınlamanıza olanak tanır. Bu sayede isteklere müdahale edebilir veya özel işlemler gerçekleştirebilirsiniz.

Tanımlanan olaylar:

  • ajaxflow:beforeSend: İstek gönderilmeden önce tetiklenir.
  • ajaxflow:afterReceive: İstek başarılı bir şekilde tamamlandıktan sonra tetiklenir.
  • ajaxflow:onError: İstek sırasında bir hata oluştuğunda tetiklenir.

Olayları dinlemek için aşağıdaki gibi kullanabilirsiniz:

document.addEventListener('ajaxflow:beforeSend', function (e) {
    console.log('İstek gönderilmek üzere:', e.detail);
});

document.addEventListener('ajaxflow:afterReceive', function (e) {
    console.log('İstek başarıyla tamamlandı:', e.detail);
});

document.addEventListener('ajaxflow:onError', function (e) {
    console.error('İstek sırasında bir hata oluştu:', e.detail);
});

Modüler Yapı ve Plugin Desteği

AjaxFlow modüler bir yapıya sahip ve plugin desteği sunar. Bu sayede kütüphanenin işlevselliğini genişletebilir ve kendi pluginlerinizi oluşturabilirsiniz.

Plugin eklemek için AjaxFlow.use(plugin) metodunu kullanabilirsiniz.

Örnek bir plugin oluşturma ve kullanma:

// Logger Plugin
const LoggerPlugin = {
    install(ajaxFlowInstance) {
        document.addEventListener('ajaxflow:beforeSend', function (e) {
            console.log('LoggerPlugin - İstek gönderiliyor:', e.detail);
        });

        document.addEventListener('ajaxflow:afterReceive', function (e) {
            console.log('LoggerPlugin - İstek tamamlandı:', e.detail);
        });
    }
};

// Plugin'i kullanmak için
AjaxFlow.use(LoggerPlugin);

Bu örnekte, isteklerin öncesinde ve sonrasında loglama yapan bir plugin oluşturulmuştur.

Dosya Yükleme Desteği

Formlarınızda dosya yükleme işlemleri yapmak istiyorsanız, AjaxFlow bunu destekler. Formunuzda dosya inputu varsa, veriler otomatik olarak FormData ile gönderilir.

Örnek kullanım:

<form ajaxflow="start-form" flow-name="uploadFile" action="upload.php" method="POST">
    <input type="file" name="file">
    <button type="submit">Yükle</button>
</form>

Bu şekilde, dosya sunucuya başarıyla gönderilecektir.

Not: Sunucu tarafında dosya yükleme işlemlerinin uygun şekilde işlenmesi gerekmektedir.