Masterpage Kullanımı


    × Bunları biliyor muydunuz?
"(ZN >= 5.6) Sürümü itibari ile View:: kütüphanesi parametresiz kullanımda tuttuğu değeri döndürmektedir."


Masterpage her projenin olmazsa olmazıdır. Ve her projede mutlaka bir masterpage yapısı olur. Biz sizin için basit bir şekilde entegre edebileceğiniz masterpage yapısı oluşturduk. Kullanımı isteğe bağlıdır. Ancak ZN'nin yapılarını kullandığı için kolay yönetilmesi açısından kullanımını tavsiye ediyoruz. 

 

 

# Bölüm Başlıkları


# Yapılandırma
# Masterpage'yi Belirlemek

Örnek Masterpage Sayfası

# Masterpage'yi Aktif Etmek

Genel Aktiflik

# Görünüm Yerleştirme
# Kaynak Yerleştirme

Data Gönderme
Görünüm Yükleme
Masterpage ile Yapılandırma

# Konteyner Projelerde Ortak Kullanım (5.7.3.1)

Ortak Yapılandırma
Ortak Görünümlerin Dahil Edilmesi (5.7.3.2)

 

 

# Yapılandırma


Masterpage ayarları 2 şekilde yapılandırılabilir;

Dosya: Config/Masterpage.php
Dosya: Controllers/Initialize.php

Özellikle çoklu ayar yapılandırması açısından 2. seçeneğin kullanılmasını tavsiye ediyoruz. Çünkü bazen Frontend ve Backend olmak üzere yapılan çalışmalarda masterpage ayarlarının her proje için ayrı yapılandırılması gerekebilir.

Dosya: Config/Masterpage.php
Mixed $headPage = '' <head></head> etiketleri arasına sayfa yerleştirmek için kullanılır. Birden fazla sayfa yerleştirmek istenirse array kullanılabilir.
String $bodyPage = '' <body></body> etiketleri arasına sayfa yerleştirmek için kullanılır. Masterpage'nin en önemli bölümüdür.
String $docType = 'html5' Üst sayfanın doküman türünü belirtir.
String $title = '' Sayfaların ön tanımlı <title></title> başlık bilgisini belirlemek için kullanılır.
Array $content = [] Üst sayfanın içerik dili ve karakter setini belirtmek için kullanılır.
String $language = 'tr' Sayfanın dili.
Array $charset = ['utf-8'] Sayfanın karakter seti.
String $browserIcon = FILES_DIR . 'favicon.ico' Tarayıcı ikonu.
String $backgroundImage = '' Sayfaya arkaplan resmi eklemek için kullanılır.
Array $attributes = [] <html>, <head> ve <body> elementlerine özellik eklemek için kullanılır.
Array $theme = [] Bir Resources/Themes/ dizininde yer alan dosyaları üst sayfaya dahil etmek için kullanılır.
Mixed $name = '' Bir Resources/Themes/ dizininde yer alan alt dizin adı. Dizine ait alt .css, .js gibi dosyaların tamamını tek seferde dahil etmek için kullanılır.
Bool $recursive = false Eğer iç içe dizin taraması yapılıp tüm alt dizinlerdeki dosyalarında dahil edilmesi istenirse recursive değeri true ayarlanmalıdır.
Array $plugin = [] Bir Resources/Plugins/ dizininde yer alan dosyaları üst sayfaya dahil etmek için kullanılır.
Mixed $name = '' Bir Resources/Plugins/ dizininde yer alan alt dizin adı. Dizine ait alt .css, .js gibi dosyaların tamamını tek seferde dahil etmek için kullanılır.
Bool $recursive = false Eğer iç içe dizin taraması yapılıp tüm alt dizinlerdeki dosyalarında dahil edilmesi istenirse recursive değeri true ayarlanmalıdır.
Array $meta = [] Üst sayfanın ön tanımlı meta bilgilerini ayarlamak için kullanılır.
Head Page

Head page <head> head page </head> etiketleri arasında yer alacak kodların bulunacağı görünümdür. Yani [head] etiketleri arasını düzenlemek için kullanılır. Aşağıda bir sayfanın nasıl üst sayfa olarak ayarlanacağı gösterilmiştir. Aşağıda belirtilen diğer üst başlık ayarlarının tamamı bu sayfa üzerinden yapılabilir. 

Kullanımı: Zorunlu değildir.
Dosya: Views/sections/head.wizard.php
@style('bootstrap')
@script('jquery', 'bootstrap')

Yukarıdaki tanımlamadan sonra yapmanız gereken bu sayfayı headPage ayarına tanımlamaktır.

'headPage' => 'sections/head'

Ya da 

Masterpage::headPage('sections/head');

Tanımlamadan sonra sayfanın kaynak kodu aşağıdakine benzer yapıda olur. 

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<link href="bootstrap.css" rel="stylesheet">
<script src="jquery.js"></script>
<script src="bootstrap.js"></script>
</head>
Body Page

Body page <body> body page </body> etiketleri arasında yer alacak kodların bulunacağı görünümdür.

Kullanımı: Zorunludur.
Dosya: Views/sections/body.wizard.php
@view

Yukarıdaki görünüm dosyasında yer alan @view deyimi o an aktif kontrolcünün otomatik olarak yüklediği görünümü temsil eder. Yani bodyPage olarak belirlenen sayfa içerisine ilgili görünümü konumlandırmak için kullanılır.

Yukarıdaki görünümü bodyPage ayarına tanımlayın.

'bodyPage' => 'sections/body'

Ya da

Masterpage::bodyPage('sections/body');

Diğer Ortak Bölümler

Ortak bölümler header, footer, lefside, rightside gibi sayfalara ayrışmışsa bu sayfalarında nereye yerleştirileceğini belirlemek için bodyPage olarak ayarlardığını görünümü kullanmalısınız.

Muhtemel body sayfanızın içeriği aşağıdaki gibi olmalıdır.

Dosya: Views/sections/body.wizard.php
@view('sections/header')
@view
@view('sections/footer')
Doctype

Sayfanızın kaynak kodunda yer alan <!DOCTYPE> doküman türünü ifade eder. Ön tanımlı olarak html5 ayarlıdır.

Kullanımı: Zorunlu değildir.

Kullanılabilir Doküman Türleri

html5
xhtml1Transitional
xhtml1Frameset
xhtml11
html4Strict
html4Transitional
html4Frameset

Farklı Doküman Türü Eklemek

Farklı bir doküman türü eklemek için aşağıdaki yapılandırma dosyasından istifade edebilirsiniz.

Dosya: Settings/Expressions.php -> doctypes
Title

Sayfanın başlığını yani <title> etiketini ayarlamak için kullanılır.

Kullanımı: Zorunlu değildir.

Bu ayar sayfadan sayfaya değişeceğinden bu ayarın yapılandırma dosyası üzerinden yapılması ön tanımlı başlık olarak düşünülmelidir. Sayfadan sayfaya değişen bağlık değerleri oluşturmak için aşağıdaki kullanımdan yararlanılmalıdır.

Masterpage::title($title);
Content

 Sayfanın dil ve karakter kodlamalarını ayarlamak için kullanılır. 

Language

Kullanımı: Zorunlu değildir.
<meta http-equiv="content-language" content="tr"> 

Html kodunun content özelliğini yapılandırır.

Charset

Kullanımı: Zorunlu değildir.
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">

Html kodunun charset özelliğini yapılandırır. 

Browser Icon

Tarayıcının üst kısmında görünen ikonu ayarlamak için kullanılır. 

Kullanımı: Zorunlu değildir.
<link rel="shortcut icon" href="">

Html kodunun href özelliğini yapılandırır. Parametre olarak URL belirtilmezse mevcut sitenin URL'sini kullanır.

'browserIcon' => FILES_DIR . 'favicon.ico'

Ya da

Masterpage::browserIcon(FILES_DIR . 'favicon.ico');
Background Image

Sayfanın arkaplanına resim eklemek için kullanılır.

Kullanımı: Zorunlu değildir.
'backgroundImage' => FILES_DIR . 'wallpaper.jpg'

Ya da

Masterpage::backgroundImage(FILES_DIR . 'wallpaper.jpg');
Attributes

Sayfanın <html>, <head> ve <body> etiketlerine özellik="değer" çifti ekleme için kullanılır.

Kullanımı: Zorunlu değildir.
'attributes' => 
[ 
    'html' => ['id'   => 'ExampleId'],
    'head' => ['name' => 'ExampleName'], 
    'body' => ['type' => 'BodyType'] 
]

Ya da

Masterpage::attributes(['html' => ['id' => 'ExampleId']]);
Theme

Resources/Themes/ dizini altında yer alan ilgili dizinden dosya çekmek için kullanılır. Kullanım olarak Import::theme() yöntemi gibidir.

Kullanımı: Zorunlu değildir.

Resources/Themes/ dizinini kullanır. 

'theme' => 
[
    'name' => ['awesome.css', 'jquery.css', 'jquery,js']
] 

Ya da

Masterpage::theme
([   
    'name' => ['awesome.css', 'jquery.css', 'jquery,js'] 
]);

Tema Dizinleri

Varlıkları, Themes/ dizini altında bir başka dizin içerisinde toplayıp istenilen dizinden dosyaların çağrılmasını sağlayabilirsiniz. Bu durumunda 'themes' ayar dizisinin her bir elemanı için bu dizin adını belirtmemek için Theme::active('YourThemes/') yönteminden yararlanabilirsiniz.

Resources/Themes/Blue/

bootstrap.js
bootstrap.css
awesome.css
jquery.js

Resources/Themes/Red/

bootstrap.js
bootstrap.css
awesome.css
jquery.js

Yukarıdaki gibi örnek bir tema yapısında masterpage yapılandırmasından her bir yol bilgisi için başına Blue/ ön eki getirmemek için başlangıç kontrolcüsünde ya da üst katmanlardan birinde Theme::active('Blue'); yöntemi çalıştırılır. Ve böylece yol bilgisi olarak direk dosya isimlerini kullanmanız aynı zamanda basit bir parametre değişikliği ile temayı da değiştirebilmeniz mümkün olur.

Dosya: Controllers/initialize.php
<?php namespace Project\Controllers;

class Initialize extends Controller
{
    Theme::active('Blue'); 

    Masterpage::theme 
    ([         
        'name' => ['awesome.css', 'jquery.css', 'jquery,js'] 
    ]);
}
Plugin

Resources/Plugins/ dizini altında yer alan ilgili dizinden dosya çekmek için kullanılır. Kullanım olarak Import::plugin() yöntemi gibidir.

Kullanımı: Zorunlu değildir.

Resources/Plugins/ dizinini kullanır. 

'plugin' => 
[
    'name' => ['bootstrap/bootstrap.js', 'bootstrap/bootstrap.css' 'awesome.css']
] 

Ya da

Masterpage::plugin
([   
    'name' => ['bootstrap/bootstrap.js', 'bootstrap/bootstrap.css' 'awesome.css'] 
]);
Meta

Meta etiketlerini ayalarmak için kullanılır. Yapılandırma listesindeki meta etiketleri dışında kendiniz de farklı bir meta etiketi ekleyebilirsiniz.

Kullanımı: Zorunlu değildir.

Meta türü name içerikli ise 

'name:author' => 'Ozan UYKUN'

Meta türü http-equiv içerikli ise

'http:refresh' => 5

gibi kullanılmalıdır.

Yukarıdaki ayarlamalar dışında aşağıdaki gibi de ayarlama yapabilirsiniz.

Masterpage::meta
([
    'name:description' => 'Description',
    'name:keywords'    => 'Example, key, words'
]);

 

 

# Masterpage'yi Belirlemek


Masterpage'yi belirleme işlemi "Yapılandırma" bölümde anlatılmıştır. Aşağıdaki dosyada bulunan bodyPage ayarına masterpage olarak ayarlanmak istenen sayfanın adı yazılmalıdır.

Dosya: Config/Masterpage.php
Örnek Masterpage Sayfası

Örnek olarak aşağıda bir masterpage'nin iç yapısının nasıl olması gerektiği hakkında fikir verilmeye çalışılmıştır.

Dosya: Views/masterpage.wizard.php
@view('header')
@view('leftside')
@view
@view('footer')

Yukarıda kullanılan @view deyimi aktif kontrolcünün otomatik olarak yüklediği görünümü temsil eder.

 

 

# Masterpage'yi Aktif Etmek


Kontrolcülerde masterpage'yi aktif etmek için en az bir ayarının yapılandırılmış olması yeterlidir. Örnek olarak aşağıda title ayarı yapılandırılmıştır.

Dosya: Controllers/example.php
<?php namespace Project\Controllers;

class Example extends Controller
{
    public function main()
    {
        Masterpage::title('Example Main Page');
        Masterpage::meta(['name:author' => 'ZN Framework']);
        
        View::content('Example Content');
    }

    public function other()
    {
        Masterpage::title('Example Other Page');
    }
}

Yukarıdaki kullanımda hem masterpage olarak belirlenen sayfaya hem de görünüm sayfasının kendisine veri göndermiş olduk.

Genel Aktiflik

Masterpage'nin en az bir ayarını başlangıç kontrolcüsünde tanımlarsanız tüm kontrolcülerde otomatik olarak kullanılmasını sağlayabilirsiniz. Bunun için geçerli bir ayar kullanmanıza gerek yoktur. Önemli olan masterpage çağrımını yapmaktır.

Dosya: Controllers/StartingController.php
<?php namespace Project\Controllers;

class StartingController extends Controller
{
    public function main()
    {
        Masterpage::status(true);
    }
}

 

 

# Görünüm Yerleştirme


Masterpage olarak ayarlanan sayfaya aktif kontrolcünün görünümünü yerleştirmek için $view değişkeni kullanılır.

5.6.2 Güncellemesi

Bu güncelleme ile görünüm yerleştirmesi için .wizard uzantılı görünümlerde $view yerine @view deyimi de kullanılabilir.

Dosya: Views/masterpage.wizard.php
@view('header')
@view # Aktif kontrolcünün otomatik olarak yüklediği görünüm sayfası.
@view('footer')

 

 

# Kaynak Yerleştirme


Bazen sayfalara göre .css veya .js dosyalarının türü ve sayısı değişebilir. Böyle bir durumuda head ve footer dosyalarınıza kendi ekledikleriniz dışında sayfanın ihtiyacına göre .css ve .js dosyaları eklemek isteyebilirsiniz. Bu gibi durumlarda bir kaç izleyebileceğiniz alternatif kullanım vardır;

Data Gönderme
Görünüm Yükleme
Masterpage ile Yapılandırma

Data Gönderme

Aşağıdaki gibi örnek bir iç sayfamız olsun.

Dosya: Views/Home/main.wizard.php
<div>
    // İçerikler
<div>
# Sayfaya özel footer'in altına yükleyeceğiniz .js dosyalarınız
@View::scripts(['js/morris', 'js/calculate'])

Yukarıda morris ve calculate scriptlerini data olarak gönderiyoruz. Data gönderimi için görünüm yerine kontrolcüde kullanılabilir.

Data olarak gönderdiğimiz bu değerleri masterpage içerisinde kullanalım. Siz isterseniz footer içinde de kullanabilirsiniz.

Dosya: Views/Sections/body.wizard.php
@view('Sections/header')
@view
@view('Sections/footer')
# Data olarak gönderdiğimiz script bilgilerini kulanıyoruz.
@script(...$scripts)
Görünüm Yükleme

2. alternatif olarak iç sayfalara göre farklılaşan verileri yine görünümlerle aynı dizinde olan bir başka görünümün içine yazılıp body page içerisinde otomatik olarak yüklettirilebilir.

Dosya: Views/Home/footer.wizard.php
# Sayfaya özel footer'in altına yükleyeceğiniz .js dosyalarınız
@script('js/morris', 'js/calculate')

Yukarıda morris ve calculate scriptlerini dahil ediyoruz.

Dosya: Views/Sections/body.wizard.php
@view('Sections/header')
@view
@view('Sections/footer')
# Aktif kontrolcüye bağlı footer görünümünü yüklüyor.
# / sembolü aktif kontrolcüye ait görünüm dizini ifade eder. 
# Örn: Home/footer.wizard.php
@view('/footer')
Masterpage ile Yapılandırma

Bu kullanım görünüm yerine kontrolcü üzerinden gerçekleştirilmelidir.

Dosya: Controllers/Home.php
public function main()
{
    Masterpage::styles('css/morris')->scripts(['js/morris', 'js/calculate']);
}
Dosya: Views/Sections/head.php
<title>Home</title>
<meta name="author" content="ZN Framework">
<meta name="description" content="ZN PHP Web Framework">
# İç sayfalara özel stiller yükleniyor.
@style(...$styles)
Dosya: Views/Sections/body.wizard.php
@view('Sections/header')
@view
@view('Sections/footer')
# İç sayfalara özel scriptler yükleniyor.
@script(...$scripts)

 

 

# Konteyner Projelerde Ortak Kullanım (5.7.3.1)


Bir birini kapsayan projelerde kapsanan alt projeler için ortak masterpage kullanımına ihtiyaç duyabilirsiniz. Bu düzenleme bu ihtiyaca yönelik yapılmıştır. Bu işlem için aşağıda yer alan kod kullanılmaktadır. Bunun için opsiyonel olarak Masterpage::container() yöntemi kullanılır .

Ortak Yapılandırma

Kontrolcüler projelerde ayrıldığı için ortak masterpage kullanımı için yapılan yapılandırmaların başlangıç kontrolcüsü yerine herhangi bir başlangıç dosyasında yer almalıdır.

Dosya: Starting/Autoload/Initialize.php

Yukarıdaki örnek başlangıç dosyasında aşağıdaki kodların yer alması durumunda masterpage kullanımı ortak hale gelir.

Masterpage::container(true)->headPage('head')->bodyPage('body');
Uyarı: Ortak kullanım kapsamında görünümlerden sadece bodyPage() ve headPage() olarak belirlenen sayfalar yer alır. Bu nedenle bodyPage() içerisine farklı görünümler dahil edilecekse Resources/Templates/ dizini kullanılabilir.
Ortak Görünümlerin Dahil Edilmesi (5.7.3.2)

Bu güncelleme ile konteyner görünüm yerleştirmesi için @cview() deyimi kullanılabilir.

Dosya: Views/body.wizard.php
@cview('header')
@view # Aktif kontrolcünün otomatik olarak yüklediği görünüm sayfası.
@cview('footer')