SuggestBox

Hem görsel hem de işlevsel açıdan tüm ihtiyaçları karşılayabilecek şekilde tasarlanmış olan SuggestBox, seçilmesi gereken bilginin çok olması durumunda kullanılabilecek bir elemandır. Kullanıcıya seçenek olarak sunulan bilgi miktarının yüksek olması durumunda klasik karma kutu elemanları hem performans açısından hem de kullanışlılık açısından elverişli değildir.

Oysa SuggestBox elemanı ile kullanıcı giriş yaptıkça, veri kaynakları ile etkileşimli olarak seçenekler hazırlanır ve böylelikle hem tüm bilginin sadece bir kısmı arayüze taşınmış ve iyi bir performans elde edilmiş hem de filtrelenmiş veri sunulduğu için kullanıcıya seçim kolaylığı tanınmış olur.

Açılır kutunun tüm görünümü, gösterilecek olan satır sayısı ve satır alanlarına atanacak veri kaynağı alanları tümüyle ihtiyaçlara göre belirlenebilir. Eleman Genel Tanımlar sayfasında (CTRL + F7) tanımlanmış olan bir veri kaynağı ile beraberce çalışır.

Bu eleman, amacı açısından, bir karma kutuya benzer. Tek farkı seçeneklerinin, kullanıcı giriş yaptıkça veri kaynaklarından, otomatik olarak doldurulmasıdır. Karma kutularda olduğu gibi, kullanıcıya gözüken ve kullanıcı tarafından değiştirilen "seçenek" verisi ve kullanıcıya gözükmeyen ancak seçilen seçenek ile ilişkili bir değer verisi mevcuttur. Seçenek değeri bir gizli girdi alanında saklanır. Kullanıcı yukarı ve aşağı tuşları veya fare ile seçenekler üzerinde gezindikçe bu gizli kutunun değeri otomatik olarak atanır.

İçinde bir SuggestBox bulunan bir form gönderildiğinde seçili seçenek ve onunla ilişkili olan değer istek parametreleri haline gelir. Değer parametresinin adı eleman adı ile aynı, seçenek parametresinin adı ise "HTML Adı" özelliğinde belirlenen değerdir.

SuggestBox elemanının yenileme fonksiyonu ESC tuşuna basarak etkin veya etkisiz hale getirilebilir. Bu fonksiyon elemana her odaklanıldığında kendiliğinden etkin hale gelir.

Not: Tüm "SuggestBox" özelliklerine $vof() fonksiyonu kullanarak dinamik değerler atanabilir.

SuggestBox elemanının değerini tutacak olan gizli girdi alanının HTML eleman adı.

SuggestBox gizli elemanının başlangıç değeri. Dikkat: Bu yazı kutusunun içinde gözüken seçenek için başlangıç değeri değildir. Seçeneğin başlangıç değerini belirlemek için İşlevsel sekmesinde bulunan "Değer" özelliğini kullanın.

Açılır kutu içindeki seçeneklerin verisini oluşturacak olan veri kaynağının adı. Veri kaynağı özellikleri içinde, örneğin; ilişkisel veritabanı veri kaynağı "Sorgu" özelliğinde, parametre sembolleri kullanılarak veri kaynağı dinamik hale getirilmelidir.

Veri kaynağının döndüreceği sonuç kümesi içinde bulunan alanlardan hangilerinin şifreleneceği (encrypt) bu özellikte belirtilir. Alan adları virgüller ile ayrılarak verilmelidir.

True durumunda kullanıcı giriş yaptıkça açılır kutuya gelen sonuçlardan ilki otomatik olarak yazı kutusu alanına getirilir.

Veri kaynağı tarafından kullanılacak olan istek parametreleri bu özellikte belirtilmelidir. Birden fazla parametre gönderileceği zaman , karakteri kullanımı unutulmamalıdır.

SuggestBox elemanı kullanıcı bir tuşa bastığında hemen isteği göndermez; bu özellikle belirlenen süre kadar bekler. Eğer süre dolmadan yeni bir tuşa basılırsa geçen süre sıfırlanır. Süre dolduğunda ise o anda yazı kutusunda bulunan değer veri kaynağını harekete geçirmek için sunucuya gönderilir.

Bu değer belirlenirken uygulamanın çalışacağı ortamdaki geçikme süresi (latency) ve sunucu performansı göz önüne alınmalıdır.

Bu özelliğe true verilirse, üzerine fare ile tıklandığında SuggestBox harekete geçecektir. Ayrıca açılır kutuda gösterilen kayıtlar da fare tekerleğinin çevrilmesi ile sayfalar halinde ileri/geri kaydırılabilecektir.

SuggestBox yazı kutusunun ve açılır kutunun görünümünü farklılaştırmak için bu alanda verilen bir tema ismi kullanılabilir. Burada eğer "default" tan farklı bir isim kullanılırsa bu yeni ismi adının içinde barındıran CSS tanımları da sağlanmalıdır. Bunu yapmanın en pratik yolu
{KURULUM_DİZİNİ}lib\sys\moremotion\ROOT\moremotion\face\Ajax\SuggestBox\default\0.css dosyası kopyalayıp değiştirmek ve sayfaya bağlamaktır.

Önerilen seçeneklerin gösterileceği ve kendiliğinden yazı kutusunun hemen altında açılan alan.

Açılır kutunun tasarım Yazı kutusuna göre nasıl hizalanacağı belirlenir. Seçenekler: left (sola), right (sağa) ve center (ortaya)

Açılır kutunun piksel olarak genişliği. Başlangıç değeri olan %vof(rect.width), yazı kutusu ile aynı genişlik anlamındadır.
Öneri Alanı

Satır içinde yer alan veri kaynağı alanlarından biri (adı bu özellikte belirlenen) öneri alanı olarak alınır kullanıcı seçenekler üzerinde gezindikçe bu alanın değeri yazı kutusuna taşınır.

Satır içinde yer alan veri kaynağı alanlarından biri (adı bu özellikte belirlenen) değer alanı olarak alınır kullanıcı seçenekler üzerinde gezindikçe bu alanın değeri bir gizli kutu olarak tutulan girdi alanına taşınır.

Sütun etiketleri. Eğer bu özellik boş bırakılırsa Açılır kutu başlıksız olarak üretilir.

Adları bu özellikte belirlenen veri kaynağı alanları veya setSymbolValue() fonksiyonu ile oluşturulan sembol adları sütunların içeriğini oluşturacaktır

Sütunların içeriklerinin yatay hizaları. Geçerli değerler "left", "center" ve "right".

SuggestBox, geliştiricinin kontrolünü arttırmak için olay Kotarıcıları desteği verir. Olay Kotarıcıları özelliklerinde tanımlanan Javascript fonksiyonları, ilgili olay gerçekleştiğinde çağrılır ve kendilerine parametre olarak SuggextBox nesnesi iletilir.

SuggestBox nesnesine ait detaylar için MoreMotion Face API dokümanına bakın.

Yazı kutusuna girilen değere karşılık gelen sonuçların elde edilmesi için sunucuya Ajax isteğinin gönderilmesinden hemen önce çağrılır. Eğer olay kotarıcısı false değeri döndürürse istek iptal edilir.

Ajax isteğine yanıt alındıktan sonra açılır kutuda yer alacak satırların oluşturulma işlemi başlar. Eğer tanımlanırsa bu kotarıcı, her bir satır oluşturmadan önce çağrılır.

Veri kaynağında yer alan bir alan değerine bağlı olarak satırlar içinde farklı resimler göstermek istediğimizi varsayalım.Bu özelliğe fonksiyon adını SetSymbol yazdığımız düşünülecek olursa

function ResimYerlestir(sbox) {
var icon = sbox.getFieldValue("ICON");
sbox.setSymbolValue("ICON",'<img src="images/'+icon+'.gif"/>');
}

Kullanıcı açılır kutudaki seçenekler üzerinde fare veya klayve tuşları ile yukarı aşağı gezinebilir. Eğer tanımlanırsa bu kotarıcı bir seçeneğin her odak kazanmasında çağrılır.

1. Hiçbiri. SuggestBox alanına giriş yapmak zorunlu olmadığında kullanılır.

2. Değer. Sadece SuggestBox yazı kutusuna bir değer girilmesini zorlamak için kullanılır.

3. Değer ve İlişkili Değer. Bu seçenek hem SuggestBox yazı kutusunun hem de ilişkili olduğu ve SuggestBox değerini tutan gizli girdi alanının boş kalmamasını sağlamak için kullanılır.

4. İlişkili Değer. Bu seçenek, İlişkili değerin ancak SuggestBox alanına bir değer girilmesi durumunda kontrol edilmesi, boş bırakıldığında ise kontrol edilmemesi için kullanılır.

5. Sadece Değer (İlişkili Değer Olmamalı). Bu seçenek kullanıcıya sistemde var olmayan yeni bir değer girdirmek için kullanılabilir. Yazı kutusuna bir değer girilmeli ama bu değere karşı gelen bir ilişkili değer olmamalıdır.

SuggestBox yazı kutusuna girilen değer üzerinde ilave doğrulama yapmak için özel bir javascript fonksiyonu hazırlayabilir ve bu fonksiyonun adını bu özellikte belirleyebilirsiniz.

Örnekteki, doğrulama fonksiyonunu devreye almak için "Özel Doğrulama Fonksiyonu" özelliğine sadece OzelDogrulama değerini verin. sbox nesnesi bu fonksiyona geçirilecektir.

function OzelDogrulama(sbox){

var elm = sbox.elm;

if (elm.value.indexOf("'") > -1) {

alert("Tırnak karakteri girilemez...");

elm.focus();

elm.select();

return false;

}

var elm_S = sbox.selm; // (*)
if (elm_S.value < 5) {
    alert("İlişkili değer 5 ten küçük olamaz...");
    elm.focus();
    elm.select();
    return false;
}

return true;

}

Örnekte olduğu gibi, eğer doğrulama başarısız ise "false", başarılı ise "true" değeri döndürülmelidir. Başarısız olma durumunda, yine örnekte görüldüğü gibi, hatalı eleman üzerine odaklanmak için elm.focus() veya eleman üzerindeki hatalı metni seçili hale getirmek için elm.select() metodları kullanılabilir.

SuggestBox elemanının ilişkili olduğu gizli girdi alanına, örnekte (*) ile işaretlenmiş olan satırdaki gibi erişebilirsiniz.

Eğer tanımlanırsa Doğrulama Kotarıcısı, sistem tarafından yapılan doğrulama sonucu başarısız olması durumunda, mesaj vermeden önce çağrılacaktır.