Ana içeriğe geç

4.1 Bileşen Öntanımlı Değerleri#

Bu döküman bir projede tekrar eden bileşen özellik değerlerinin yönetilmesi için altyapı tarafından geliştirilmiş çözümü açıklamaktadır.

4.1.1 Senaryolar#

Projelerimizde kullandığımız bazı bileşenlerin özelliklerinin değeri birçok yerde tekrar eder. Örneğin tarih bileşeninin format özelliği bir projede muhtemelen her yerde aynıdır, format="dd.mm.yy" gibi. Aşağıdaki örneği inceleyiniz.

<p-calendar 
    format="dd.mm.yy" 
    placeholder="Tarih seçiniz" 
    showIcon="true" 
    [(ngModel)]="birthDate" 
    name="birthDate" > 
</p-calendar>

Yukarıdaki kodda p-calendar bileşeni kullanımı örneklenmiştir. Bu örnekteki format, placeholder ve showIcon özelliklerinin projedeki birçok tarih bileşenlerinde aynı şekilde (aynı özellik değerleri ile) kullanılması çok görülen bir durumdur. Bu kullanımda dikkat çekici sorunlar şunlardır:

  • Tekrarlamalar: aynı değerler proje boyunca tekrar etmektedir. format, placeholder ve showIcon özelliklerinin değerleri birçok yerde aynı şekilde kullanılmaktadır format özelliğinin değeri ise muhtemelen her yerde aynı şekilde kullanılmaktadır. Bu durumun ortaya çıkardığı sorun bir değişiklik yapılmak istenildiğinde tüm kullanımların bulunup değiştirilme ihtiyacıdır. Örneğin placeholder'ı "Seçiniz" olarak değiştirmeye karar verdiğinizi düşünün. Bu durumda projedeki tüm p-calendar kullanımları bulunup placeholder değeri değiştirilmelidir.
  • Tek yerden yönetememe: format gibi özellikler müşteri bazında farklı olabilir. Örneğin ürününüzü farklı bir ülkeye sattığınızı ve buradaki tarih formatının "mm.dd.yy" olduğunu düşünün. Bu durumda bir müşteriniz için format "dd.mm.yy" olmalı iken başka bir müşteri için "mm.dd.yy" olmalıdır. Bu durumda p-calendar'ın format özelliğini yukarıdaki gibi kullanamazsınız. Bir konfigürasyonda p-calendar format değerini tutup oradan kullanmanız gerekmektedir. Üstelik bunu p-calendar kullandığınız her yerde yapmalısınız.
  • Disipline edememe: ürün yöneticinizin üründeki tüm tarih bileşenlerinin showIcon=true ile yani tarih seçme ikonu gözükecek şekilde kullanılmasını istediğini düşünün. Bu disiplin nasıl sağlanabilir? Bir geliştirici bazı tarih bileşenlerine bu özelliği vermeyi unutursa "gözden kaçma" durumları nasıl yönetilebilir? Muhtemelen kod gözden geçirmeleri daha sıkı tutmak gibi çözümler uygulanacaktır.

4.1.2 Daha Gerçekçi Bir Örnek#

Yukarıdaki örneği okurken muhtemelen tarih bileşenini tüm projede aynı şekilde kullanmayız bazı ekranlarda sadece tarihi bazılarında ise tarih ve saati alacak şekilde kullanırız demiş olabilirsiniz. Bu durumda format özelliği projedeki ekranların %70'inde "dd.mm.yy" iken %30'unda "dd.mm.yy HH:MM" olarak kullanıldığı bir durumdan söz edilebilir. 

<p-calendar 
    format="dd.mm.yy" 
    placeholder="Tarih seçiniz" 
    showIcon="true" 
    [(ngModel)]="dogumTarihi" 
    name="dogumTarihi" > 
</p-calendar>
<p-calendar 
    format="dd.mm.yy HH:MM" 
    placeholder="Saat seçiniz" 
    showIcon="true" 
    [(ngModel)]="basvuruZamani" 
    name="basvuruZamani" > 
</p-calendar>

Öyleyse aynı bileşenin farklı sık kullanılan durumları olmasının bir önceki başlıkta bahsedilen sorunlara bir seviye daha getirirerek bahsedilen sorunları bir tık daha karmaşıklaştırdığını söyleyebiliriz.

4.2 Öntanımlı Değer Direktifleri#

Bileşenlerin her yerde tekrar eden özellik değerlerinin yönetilmesi için altyapı'da bileşen direktifleri geliştirilmiştir. Bir önceki başlıkta anlatılan p-calendar bileşeni için geliştirilmiş direktif hvlCalendarDefaults (HvlCalendarDefaultsDirective) direktifidir. Kullanımı aşağıda örneklenmiştir.

<p-calendar 
    hvlCalendarDefaults
    [(ngModel)]="birthDate" 
    name="birthDate" > 
</p-calendar>

Bu direktif ile öntanımlı değerler bileşene direktif tarafından verilmektedir. Önceki örnekteki format, placeholder, showIcon gibi özelliklerin değerleri bu şekilde yönetilebilir.

Bir direktifi projenizde kullanmak için direktif sınıfını modül tanımızda imports'a eklemeniz yeterlidir.

Bir bileşenin birden fazla sık kullanıldığı durumları ele almak için direktife değer verilebilir. Aşağıdaki örneği inceleyiniz:

<p-calendar 
    hvlCalendarDefaults
    [(ngModel)]="birthDate" 
    name="birthDate" > 
</p-calendar>
<p-calendar 
    hvlCalendarDefaults="time"
    [(ngModel)]="basvuruZamani" 
    name="basvuruZamani" > 
</p-calendar>
Yukarıdaki kodda ilk tarih bileşeni hvlCalendarDefaults direktifini direkt kullanırken ikinci tarih bileşeni hvlCalendarDefaults direktifini "time" değeri ile kullanmıştır. Bu şekilde farklı sık kullanım durumları ele alınabilir.

4.2.1 Öntanımlı Değer İstisnaları#

Ön tanımlı değerler projede sıklıkla tekrar eden değerlerdir. Fakat bazen bir özelliğin değerini kasten farklı kullanmak isteriz. Bu durumu ele almak için bileşende özelliği değeri ile kullanmak yeterlidir. Aşağıdaki örneği inceleyin:

<p-calendar 
    hvlCalendarDefaults
    placeHolder="Doğum Tarihi"
    [(ngModel)]="birthDate" 
    name="birthDate" > 
</p-calendar>

Yukarıdaki örnekte bileşenin özelliklerin öntanımlı değerlerini kullanmak için hvlCalendarDefaults kullanılmıştır. placeHolder özelliğinin de öntanımlı değer olarak "Tarih seçiniz" verildiğini varsayın. Yukarıda örnekte placeholder özelliğinin değeri "Doğum Tarihi" verilerek öntanımlı değer ezilmiştir. Ekranda "Doğum Tarihi" gözükecektir.

Yukarıda örnekteki gibi tekrarlanan özellik değerleri projede birçok yerde aynı şekilde kullanılırken farklı bir değer kullanılması gereken durumlar kolayca ele alınabilir.

4.2.2 Hazır Gelen Direktifler#

Altyapı tarafından sağlanmış öntanımlı değer direktifler ve bu direktiflerin ilişkili olduğu bileşenler şunlardır:

  • hvlCalendarDefaults (p-calendar)
  • hvlDropdownDefaults (p-dropdown)
  • hvlAutoCompleteDefaults (p-autoComplete)
  • hvlCheckboxDefaults (p-checkbox)
  • hvlInputMaskDefaults (p-inputMask)
  • hvlInputSwitchDefaults (p-inputSwitch)
  • hvlInputNumberDefaults (p-inputNumber)
  • hvlTableDefaults (p-table)
  • hvlNativeElementDefaults (temel html elementleri)

Bu diretifler hvlng/framework-core paketinde HvlFormModule modülünde yer almaktadır. Projenizde kullanmak için proje bağımlılıklarında hvlng/framework-core 'un 2.2.0 yada daha üzeri bir versiyonunun yer aldığından emin olunuz. Ayrıca direktifleri kullanacağınız modülün -module.ts dosyasında @NgModule dekorasoyunu imports kısmına HvlFormModule 'ü eklemeyi unutmayın.

hvlNativeElementDefaults direktifi temel html elementleri (input, div, span, select gibi) ile kullanılabilecek ortak direktiftir. Bu direktif tüm temel html bileşenlerine ön tanımli özellik değeri vermek için kullanılabilir.

4.2.3 Yeni Direktif İhtiyacı#

Bir önceki başlıkta belirtilen altyapı tarafından sağlanan direktifler dışında henüz desteklenmemiş bir bileşen için öntanımlı değerleri yönetme ihtiyacınız olduğunda iki farklı yol izleyebilirsiniz.

  • Yeni bileşen için direktif ihtiyacınızı altyapıdan isteyebilirsiniz. Direktif geliştirimi basit bir iştir. İşinizin aciliyetine göre yama versiyon ile yada minor versiyon ile size istediğiniz direktif hızlıca sağlanacaktır.

  • Direktifi kendiniz geliştirebilirsiniz. Bu durumda geliştirdiğiniz kısmın bakımı ve altyapı değişikliklerinde direktifi altyapıya uygun değiştirme gibi durumları ele alma maliyetini üstlenirsiniz. Bu yöntemi acil durumlar dışında tercih etmeyin. Aşağıda hvlCalendarDefaults direktifinin kodu yeni bir direktif geliştirmeniz durumunda örnek olması için verilmiştir.

```typescript @Directive({ selector: '[hvlCalendarDefaults]', }) export class HvlCalendarDefaultsDirective extends HvlComponentDefaultsBase {

constructor( private calendar: Calendar, protected override configService: HvlConfigurationService, protected override translateService: TranslateService, protected override changeDetectorRef: ChangeDetectorRef, private elementRef: ElementRef ) { super(calendar, configService, translateService, changeDetectorRef, 'p-calendar', elementRef.nativeElement.getAttribute('hvlCalendarDefaults')); }

} ```

4.3 Öntanımlı Değerlerin Yönetimi#

Öntanımlı değer direktifleri bileşenlerin öntanımlı değerlerini proje konfigürasyonundan alacak şekilde geliştirilmiştir. Bu amaçla config.json'da core'un altında componentDefaults alanı açılmıştır. Bu alana aşağıdaki örnekteki gibi bileşenlerin öntanımlı değerleri verilebilir

{
    "core": {
        "componentDefaults": {
            "p-calendar": {
                "format": "dd.mm.yy",
                "placeholder": "Tarih seçiniz",
                "showIcon": "true"
            },
            "p-dropdown": {
                "placeholder":"Seçenekler"
            }
            ....
    }
}
Yukarıda görüldüğü gibi bileşenlerin öntanımlı değerleri componentDefaults alanı altında bileşen tag'i ile (p-calendar gibi) verilmelidir.

4.3.1 Farklı Sık Kullanım Durumlarının Ele Alınması#

"Daha Gerçekçi Bir Örnek" başlığında tarih bileşeninin bir projede iki farklı sık kullanım durumu olduğu bu sebeple iki farklı durumu da ele almamız gerektiği belirtilmişti. Tarih bileşeninin sadece tarih ile kullanıldığı durum ve tarih - saat ile birlikte kullanıldığı durum için öntanımlı değerlerin verildiği aşağıdaki örneği inceleyiniz:

{
    "core": {
        "componentDefaults": {
            "p-calendar": {
                "format": "dd.mm.yy",
                "placeholder": "Tarih seçiniz",
                "showIcon": "true",
                "#time": {
                    "format": "dd.mm.yy HH:MM",
                    "placeholder": "Zaman seçiniz",
                }
            }
            ....
    }
}

Bir bileşenin farklı sık kullanım durumları var ise bileşen içine yeni bir alan "#" ön eki ile yukarıdaki örnekteki gibi verilmelidir. Farklı sık kullanım durumları ile ilgili kod örneği "Öntanımlı Değer Direktifleri" başlığında verilmişti, şimdi isterseniz konfigürasyon ile birleştirerek üstünden geçmek için bu başlığı tekrar inceleyebilirsiniz.

Yukarıdaki örnekte showIcon özelliği "#time" durumu için verilmemiştir. Direktif "#time" ile kullanıldığı durumda da showIcon=true öntanınlı değerini alacaktır. Bu sebeple farklı sık kullanım durumlarını ele alırken sadece değişen özellikleri ele almanız gereksiz tekrarlardan kaçınmak için daha doğru bir kullanım olacaktır. Eğer farklı sık kullanım durumunda bileşenin öntanımlı diğer değerlerini kullanmak istemiyorsanız bu değleri boş verebilirsiz, showIcon="" gibi.

4.3.2 Çoklu Dil Tanımları#

Bileşenlerin özellik değerleri çoklu dil tanımları ile ilişkili olabilir. Örneğin placeholder özelliğinin değeri "Tarih seçiniz" şeklinde değil de "general.date-select" şeklinde çoklu dil anaktarı ile kullanılması daha doğru ve tercih edilen yöntemdir. Konfigürasyon içinde öntanımlı değerler için çoklu dil anahtarları aşağıdaki gibi kullanılabilir:

{
    "core": {
        "componentDefaults": {
            "p-calendar": {
                "format": "dd.mm.yy",
                "placeholder": "${general.select-date}",
            }
            ....
    }
}

Örnekteki gibi çoklu dil anahtarını ${ } formatında vermeniz beklenmektedir. Bir değer içinde birden fazla çoklu dil anahtarı da kullanabilirsiniz "${x.y} - ${a.b}" gibi.

4.4 Bileşenlerin Hangi Özellikleri Öntanımlı Değerleri ile Kullanılabilir?#

Bir bileşenin herhangi bir özelliği için öntanımlı değerleri kullanabilirsiniz. Bu anlamda bir kısıtlama bulunmamaktadır.

Fakat ön tanımlı değerleri sık sık tekrar eden değerler için kullanılması gerektiğini unutmamalısınız. Ender olarak verilen bir özellik için öntanımlı değer kullanmaktan sakının.

Ayrıca geliştirilmesi büyük ölçüde tamamlanmış bir projede ön tanımlı değer kullanırken dikkatli olmalısınız. Örneğin placeholder özelliğini ön tanımlı olarak kullanmak istediğiniz durumda bazı ekranlar için bunun anlamsız yada saçma gözükübileceğini mutlaka düşünün. Daha önemlisi minimumValue gibi bir özelliği ön tanımlı değeri ile kullanmak istediğinizde bazı ekranlarda beklemediğiniz davranışlara dahası hatalara sebep olabileceğini göz önünde bulundurun. minimumValue için öntanımlı değer 5 verdiğiniz durumda eğer 5'den küçük bir değer alabilecek ekran varsa bu durumda ekranın çalışması bozulacaktır. Bu gibi büyük müdehalelerde ilgili ekranları tekrar teste sokmayı mutlaka değerlendirin.

Bileşen özelliklerinin öntanımlı değerlerini yönetirken basit alanlar için kullanmaya önem gösterin. Karmaşık özellikler için mutlaka test ettikten sonra kullanın. Bileşen özelliğinin değeri hesaplanan bir değerse yada bir değişkene referans ediyorsa öntanımlı değer olarak kullanmaktan sakının.