Şablon Sihirbazı


    × Bunları biliyor muydunuz?
"Settings/CDNLinks.php yapılandırma dosyası altında yer alan 'script' ve 'style' dizilerine tanımlayacağınız linkleri Import::script() ve Import::style() kütüphaneleri ile birlikte kullanabilirsiniz."


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.

File: Config/ViewObjects.php
Wizard
bool $keywords = true Anahtar kelimeler çevirilsin mi? Bu değerin true olması durumudna or, if, while, foreach gibi anahtar kelimelerin parse edilebilmesi sağlanır.
bool $printable = true Yazılabilir fonksiyon ve değişkenler kullanılabilsin mi? Bu değerin true olması durumunda @function:, @$variable: kullanımına izin verir.
bool $functions = true Şablon Fonksiyonları kullanılabilsin mi? Bu değerin true olması durumunda @function: kullanımına izin verir.
bool $comments = true Şablon yorum satırı kullanılabilsin mi? Bu değerin true olması durumunda {-- Comments --} kullanımına izin verir.
bool $tags = true Şablon PHP tagları kullanılabilsin mi? Bu değerin true olması durumunda {[ $code; ]} kullanımına izin verir.
bool $jsdata = true Vue, react gibi harici javascript kütüphaneleri kullanılıyorsa bunların data alımı için kullanılan {{data.item}} ayracın ZN wizard ile çakışmaması için [{data.item}] formunda kullanılmayı sağlar.
bool
$callableJS = true
PHP'nin Geriçağrım işlevi uygulanabilir parametrelerinin ve anonim fonksiyonlarının {< code >} biçiminde de kullanılabilir olmasını sağlar.
bool $html = false Şablon HTML tagları kullanılabilsin mi? Bu değerin true olması durumunda #tag value ##tag gibi özel kulanımılara izin verir.
 

 

# Ö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ığın Öncelenmesi

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.

Hatalı Kullanım
@Form::id('@data:')->text('example'):
<input type="text" name="example" value="" id="<?php data ?>">
Doğru Kullanım
@Form::id('/@data/:')->text('example'):
<input type="text" name="example" value="" id="@data:">

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 echo 'Hi ZERONEED' ?>

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

@php 
# your codes...
@endphp
Gerçek PHP Taglarının İzolasyonu

Ş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 --}
<!-- 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.

İki Küme Parantezli Notasyon

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

{{ $example }}
<?php echo $example ?>
Üç Küme Parantezli Notasyon

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

{{{ $example }}}
<?php echo htmlentities($example); ?>
At ve İki Nokta Notasyonu

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:
<?php echo $example ?>

Yöntemler ve fonksiyonlar için;

@URL::base('example'):
<?php echo URL::base('example') ?>

Sabitler için;

@CURRENT_CONTROLLER:
<?php echo 'Home' ?>

kullanılır.

Satır Sonu

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
Null Coalesce

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.

Örnek Kullanım
<div id="app">[{message}]</div>

 

 

# Döngüler ve Karar Yapılarının Kullanımları (ZN >= 3.1.0)


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

Foreach
@foreach( $data as $key => $val )
    {{ $key }} - {{ $val }}
@endforeach
Forelse (ZN >= 5.4.4)

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
Loop (ZN >= 5.4.7)

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
@for($i = 0; $i < 10; $i++ )
    {{ $i }}
@endfor
While
{[ $i = 0; ]}
@while( $i < 10 )
    {{ $i++ }}
@endwhile
IF - Else IF - Else
@if( 2 > 1 )
    True
@elseif( 1 > 2 )
    False
@else
    Other
@endif
Login - Not

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

Deyimler

@login(void) Kullanıcının giriş yapma durumu.
@not Kullanıcının giriş yapmamış olması durumu.
@endlogin Kontrolü sonlandırır.

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.

Valid - Invalid

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

Deyimler

@valid(string $input = 'all')
Form verilerinin kurallara uygun olması durumu. Parametresinin değiştirilmemesi durumunda Post::all() kabul edilir. İstenirse form nesnelerinden birinin adı verilebilir.
@invalid($var) Form verilerinin kurallara aykırı olması durumu. $var değişkeni Validation::error('string') yönteminin değerini saklar.
@endvalid Kontrolü sonlandırır.

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') 
Import::style('bootstrap')
@view('header')  
Import::view('header')
@view
$view
@view('content')
Import::view('content')
@script('jquery')
Import::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
$callback = function(){ echo '<script> alert("Hi!"); </script>'; };
Wizard Kullanımı

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')
>})
ZN Framework
Referans Değişken Gönderme [6.12.0][2021-05-30]

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. 

Uyarı: Stil ve javascript kaynaklarının dahil edilmesi gerekmektedir.
@container
<div class="container">
@containerFluid
<div class="container-fluid">
@row
<div class="row">
@col{xs|sm|md|lg}{1-12}
<div class="col-{xs|sm|md|lg}-{1-12}">
Kullanımlar
Dosya: Views/Home/main.wizard.php
@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.

Wizard JQuery
@selector(mixed $selector) $($selector)
Kullanımlar
Dosya: Views/Home/main.wizard.php
@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

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.

Geriçağrım İşlevi

@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 Kütüphanesi
@form(...$params) Form::open(...$params)
@endform Form::close()
@hidden(...$params) Form::hidden(...$params)
@text(...$params) Form::text(...$params)
@password(...$params) Form::password(...$params)
@email(...$params) Form::email(...$params)
@textarea(...$params) Form::textarea(...$params)
@button(...$params) Form::button(...$params)
@submit(...$params) Form::submit(...$params)
@radio(...$params) Form::radio(...$params)
@checkbox(...$params) Form::checkbox(...$params)
@select(...$params) Form::select(...$params)
@multiselect(...$params) Form::multiselect(...$params)
@file(...$params) Form::file(...$params)
Html Kütüphanesi
@anchor(...$params) Html::anchor(...$params)
@mailto(...$params) Html::mailto(...$params)
@image(...$params) Html::image(...$params)
Ajax Kütüphanesi
@ajax(string $url) Ajax::url(string $url)
Kullanımlar
Dosya: Home/main.wizard.php
@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

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

#b ZN Framework ##b
<b>ZN Framework</b>
Kapatılmayan Etiketler

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

#input[type="text" value="Value"]
<input type="text" value="Value">
#br
<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']);
Hello
Wizard Fonksiyonu [6.24.0][2021-10-09]

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

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