Şablon Sihirbazı

Görünüm dosyalarını manipüle etmek için ve daha basit php komutlarını kullanabilmeniz için oluşturulmuştur. Views/ dizindeki görünüm sayfalarının sonuna .wizard uzantısı eklenirse  mesela test.wizard.php gibi artık bu dosya aşağıda anlatılan yöntemlerle kullanılabilir hale gelir. Şablon sihirbazının kurallarına uygun yazacağınız her görünüm sayfası bu sihirbaz ile ayrıştırılarak normal php kodlarına çevrilir. Şimdi bu sihirbazı nasıl kullanırız onu gösterelim.

Öncelikle yapmanız gereken Views/test.wizard.php örnek bir görünüm dosyası oluşturmak.

# Bölüm Başıkları

# Kurulum
# Yapılandırma 
# Özel Karakterler

# Amaç Dışılığın Öncelenmesi
# Hatalı Kullanım
# Doğru Kullanım

# PHP Taglarının Kullanımı

# Gerçek PHP Taglarının İzolasyonu

# Açıklama Satırlarının Kullanımı
# Yazdırma Yöntemleri

# İki Küme Parantezli Notasyon
# Üç Küme Parantezli Notasyon
# At ve İki Nokta Notasyonu
# Satır Sonu 
# Null Coalesce 

# Javascript Kütüphaneleri Veri Yazdırma Kullanımı 

# Döngüler ve Karar Yapılarının Kullanımları 

# Foreach
# Forelse
# Loop
# For
# While
# If - Else If - Else
# Login - Not 
# Valid - Invalid 

# Görünüm ve İçerik Yerleştirme 

# Referans Değişken Gönderme

# Geriçağrım İşlevine Standart Kod Yazımı
# Bootstrap Gridsistem ve Sayfa Düzeni  
# Jquery Birleştiricisi 
# Kısa Form ve HTML Nesnelerinin Kullanımı
# HTML Kullanımı 

# Kapatılan Etiketler
# Kapatılmayan Etiketler

# Kütüphaneler ile Kullanım

# Kurulum

ZN dağıtımları için kurulum gerektirmez.

↓ composer require znframework/package-template-engine

# Yapılandırma

Şablon sihirbazında nelerin çevirilip çevirilmeyeceği ayarlayabilirsiniz. Parse edilmesini istemediğiniz yapıları açıp kapayalabilirsiniz. Bu size aynı zamanda kontrol etmek zorunda olacağınız karakterlerin sayısını azaltmanıza olanak sağlar.

$callableJS = true

# Özel Karakterler

Şablon sihirbazında @ işareti ile birlikte : sembolü amaçları dışında kullanılmaları durumunda / sembolü ile öncelenmesinde fayda vardır. Yapılandırma dosyasından # karakterli html kullanımına izin verildiği taktirde bu karakter içinde aynı durum geçerlidir.

Amaç dışılık @phpcode: kullanımına benzer ama aslında kod olmayan durumlarda / sembolü ile öncelenmelidir. Özellikle kod içinde aynı karaketerlerin benzer maksatla kullanılmasından dolayı böyle bir istisna oluşur.

@Form::id('@data:')->text('example'):

@Form::id('/@data/:')->text('example'):

Bu tip kullanımlarda sembollerin öncelenmesini string ifadelerin kullanımında karşılaşılan print('your\'s code') tırnak belirsizliğini çözme durumu gibi düşünebilirsiniz.

# PHP Taglarının Kullanımı

Şablon görünüm sayfasında eğer gerekli olursa aşağıdaki gibi alternatif kullanım ile php etiketleri kullanılabilir.

{[ echo 'Hi, ZERONEED' ]}

PHP etiketleri aşağıdaki gibi de kullanılabilir.

@php 
# your codes...
@endphp

Şablon sihirbazında klasik PHP tagları kullanamazsınız. Bu taglar izole edilir. Bu da sayfanızın istenilen çıktıyı oluşturmamasına neden olabilir. İzolasyon şablon sihirbazı PHP taglarına dönüştürülerek yapılır.

# Açıklama Satırlarının Kullanımı

Şablon görünüm sayfasında aşağıdaki şekilde açıklama kullanılabilir.

{-- Views/test.wizard.php --}

# Yazdırma Yöntemleri

Şablon görünüm sayfasında aşağıdaki şekilde yazdırma işlemi uygulanabilir. Metinsel ifadeleri, sayıları, değişkenleri veya fonksiyonları yazdırmak için kullanılabilir. String ifadeler tırnak işaretleri içinde yazılmalıdır.

Yazdırılacak olan yöntem, değişken veya sabit çift küme parantezleri arasına alınır.

{{ $example }}

Yazdırılacak olan komuta ait içeriğin html ve tırnak karaketerlerinin numerik koda çevrilerek yazdırılması sağlanır.

{{{ $example }}}

Yazdırılacak olan değişken, yöntem ve sabitin başına @ sembolü getirilir. Sonuna ise : sembolü eklenir. Eğer ifadenin sonu satır sonu ise : kullanımına gerek yoktur. Bu kullanım, uzunluğu alt satıra geçmeyecek kodların yazdırılmasında tercih edilmelidir.

Değişkenler için;

@$example:

Yöntemler ve fonksiyonlar için;

@URL::base('example'):

Sabitler için;

@CURRENT_CONTROLLER:

kullanılır.

Yöntem veya değişkenin sonu satır sonuna denk geliyorsa : kullanımına gerek yoktur.

@Import::script('jquery')
<title>{{ $title }}</title>
@if( ! $value )
    @$value
@endif

Tanımlı olmayan veya NULL tanımlı olan değişken ve sabit kullanımlarında alınan tanımsız hatalarını manipüle etmek için kullanılır.

Değişkenler için;

@$varname?:

Sabitler için;

@CONST_NAME?:

kullanılır.

# Javascript Kütüphaneleri Veri Yazdırma Kullanımı

Vue, react gibi javascript kütüphanelerinde kullanılan {{data}} kullanımı şablon sihirbazının kullanımı ile çakışacağından dolayı gerçek {{ }} sembollerinin yazımı için [{data}] formu kullanılmalıdır. Yani vue de veya angularda data alımı için {{data}} yerine [{data}] kullanmalısınız. Tabi ki ilgili javascript kütüphanesinin delimiter ayarını değiştirmemişseniz bu durum geçerlidir.

<div id="app">[{message}]</div>

Javascript içerisinde peşpeşe {{ karakterini kullanmanız gerekirse önlerine / sembolü ekleyin.

/{/{message/}/}

# Döngüler ve Karar Yapılarının Kullanımları 

Template yapısında oldukça basit kullanımlı döngüler ve karar yapıları kullanabilirsiniz.

@foreach( $data as $key => $val )
    {{ $key }} - {{ $val }}
@endforeach

Kullanım olarak foreach ile aynıdır. Tek fark döngüye giren parametrenin boş veya tanımsız olması durumunda ne yapılacağına karar verilebilmesidir.

@forelse( $datas as $key => $value )
    {{ $key }} - {{ $value }}
@empty
    No Data
@endforelse

Kullanım olarak foreach gibidir. Tek farkı $key => $value deyimi belirtilmez. Bu kullanım ön tanımlıdır. Yani $key ve $value doğrudan kullanılabilir.

@loop($data)
    {{ $key }} - {{ $value }}
@endloop

@for($i = 0; $i < 10; $i++ )
    {{ $i }}
@endfor

{[ $i = 0; ]}
@while( $i < 10 )
    {{ $i++ }}
@endwhile

@if( 2 > 1 )
    True
@elseif( 1 > 2 )
    False
@else
    Other
@endif

User::isLogin() kontrolünün kısa formudur.

Deyimler

Kullanımlar

@login()  # if( User::isLogin() ):
<b>Welcome User</b>
@not      # else:
<b>Sign Up Please</b>
@endlogin # endif

Yukarıda yer alan @not yerine @else de kullanılabilir.

Validation::check() kontrolünün kısa formudur.

Deyimler

@valid(string $input = 'all')

Kullanımlar

@valid()         # if( Validation::check() )
    @Html::alertSuccess('Kaydınız başarı ile gerçekleştirildi!')
@invalid($error) # elseif( $error = Validation::error('string') )
    @Html::alertDanger($error)
@endvalid        # endif

# Görünüm ve İçerik Yerleştirme

ZN Framework'te görünüm ve içerikler Import:: kütüphanesi ile dahil edilir. İçerik dahil etmek için şablon sihirbazında Import:: kullanımlarının yanında @importMethod() kullanımı da mümkündür.

@style('bootstrap') 

@view('header')  

@view

@view('content')

@script('jquery')

Böylece Import:: sınıf yöntemlerini artık daha kısa formda kullanabileceksiniz.

# Geriçağrım İşlevine Standart Kod Yazımı

PHP'nin geri çağrım işlevi uygulanabilir parametrelerine standart kod yazabilmenin önünü açan kullanım sunar. Bu kullanımın devre dışı bırakılması için yapılandırma dosyasında yer alan callableJS anahtarının değerini false olarak ayarlayın. Bu kullanım geri çağrım işlevi uygulanabilir parametrelerde ve anonim işlevlerde geçerlidir.

@php
$callback = {< <script> alert('Hi!'); </script> >};
echo $callback();
@endphp

Geri çağrım işlevi içerisine standart kod yazılabilir olması nedeni ile içerisinde wizard yapıları da kullanılabilmektedir

@Html::div
({<
    @Html::italic('ZN'): @Html::strong('Framework')
>})

Anonim fonksiyonlara dışarıdan değişken gönderebilmek için use($var) deyimi kullanılır. Bunun wizard ile kullanımı aşağıdaki gibidir.

@Html::div([< $var1, $var2 >]
{<
    @Html::italic($var1): @Html::strong($var2)
>})

Ayrıca zaten aşağıdaki gibi kullanım da mümkündür.

@Html::div(function() use($var1, $var2)
{<
    @Html::italic($var1): @Html::strong($var2)
>})

# Bootstrap Gridsistem ve Sayfa Düzeni

ZN Framework'te Bootstrap'ın grid sistemini kullanabilirsiniz. Kullanılabilir etiketler ve karşılıkları aşağıda listede verilmiştir. 

<div class="container">

<div class="container-fluid">

<div class="row">

<div class="col-{xs|sm|md|lg}-{1-12}">

@style('bootstrap')

@container
  @row
    @colsm4
      <b>Column Size 4</b>
    @endcol

    @colsm4
      <u>Column Size 4</u>
    @endcol

    @colsm4
      <i>Column Size 4</i>
    @endcol
  @endrow
@endcontainer

@script('jquery', 'bootstrap')

Yukarıda yer alan stil ve script kaynaklarını masterpage üzerinden dahil ediyorsanız kullanmanıza gerek yok.

# JQuery Birleştiricisi

JQuery'nin ajax ve seçici kullanımlarının PHP ile yazılabilmesini sağlayan kullanımlar sunar.

@Form::onclick('ajax()')->button('ajax', 'SEND')

@script('jquery')

@selector('input[name="ajax"]')->tag(true)->click({<
    @ajax('home/test')->success({<
        alert(10);
    >})
>})

JQuery'de olduğu gibi seçiciye birden fazla yöntem bağlanabilir. 

@selector('input[name="ajax"]')->tag(true)->hide(100)->show(1000)->hide(5000)

tag(true) yöntemi [script] etiketlerinin otomatik olarak açılıp kapatılmasını sağlar. Kodun bir başka javascript içerisine yazılması gereken durumlarda bu yöntemin kullanılmadığından emin olun.

@selector() yönteminin 1. parametresini standart kod yazmak için de kullanabilirsiniz.

@selector({< 'input=["' + parameter + '"]' >})->click({<
   alert(10);
>})

# Hypertext Nesnelerinin Kullanımı

Bu güncelleme ile aşağıda listesi verilen Html:: ve Form:: sınıflarının nesnelerini daha kısa bir şekilde kullanabilirsiniz.

@form()
@text('example', '', ['placeholder' => 'Example text...'])
<br>
@submit('send', 'Send')
@endform

Form nesneleri satır sonu (\n|\r\n) ile bitmiyorsa iki nokta (:) ile bitirilmelidir.

@form()
<table>
<tr><td>@text('example', '', ['placeholder' => 'Example text...']):</td></tr>
<tr><td>@submit('send', 'Send'):</td></tr>
</table>
@endform

Yukarıdaki kullanımda @text() nesnesinin sonunda <br> sembolü olduğu için iki nokta (:) konulduğuna dikkat ediniz.

# HTML Kullanımı

Şablon görünüm sayfasında aşağıdaki şekilde html tagları kullanılabilir. Bu kullanımlar için yukarıda belirtilen yapılandırma dosyasından html kullanım değerinin true olarak ayarlanması gerekmektedir.

Kapatılan etiketler için bir kaç alternatifli kullanım söz konusudur.

#b ZN Framework ##b

Kapatılmayan etiketlerin kullanımı aşağıdaki gibidir.

#input[type="text" value="Value"]

#br

# Kütüphaneler ile Kullanım

Şablon sihirbazını görünümler dışında kullanmak isterseniz. Aşağıdaki yöntemden yararlanabilirsiniz.

echo ZN\Wizard::data('{{ $data }}', ['data' => 'Hello']);

Yukarıdaki kullanım yerine wizard() yönteminden de istifade edebilirsiniz.

echo wizard('{{ $data }}', ['data' => 'Hello']);