Boş Gezenin Boş Kalfası: Docpad İle Statik Web Sayfası Hazırlamak

Web sitesi hazırlarken çoğu zaman statik bir web sitesi işimizi görecektir, hem server daha ucuz temin edilebilir. Ancak statik web sitesi hazırlarken en büyük sıkıntı, her sayfada yinelemek zorunda kalınılan menüler yerleşimler vs.

Bu konuda kısa bir araştırma yaptım, Docpad uygulamasını erb yapılara benzerliği yüzünden tercih ettim. Hadi beraber tutorial üzerinden gidelim.

Docpad node.js ile çalıştırılıyor , bu yüzden öncelikle sisteminizde node.js yüklü olmalıdır. Tavsiye en son sürüme yükseltip kullanmanız, bende 0.10.35 var.

Docpad Kurulumu

# npm install -g docpad@6.69

Linux kullanıyorsanız sudo yetki gerekir.

Standart Proje Yapısını Oluşturmak

Web sitemizin içeriğine dalmadan önce proje klasörümüzü Docpad'in standart yapısına uygun olarak üretmemiz gerekiyor. Bunu yapmak için konsolda şunları yazın:

mkdir websitem cd websitem docpad run

ilk kez "docpad run" komutu girildiğinde lisans sözleşmesi çıkar ve "yes" için "y" girmenizi ister. Bu arada "docpad run" komutu sudo olarak çalıştırılmalı. Sonra sizden bir skeleton (iskelet yapı) kalıp seçmenizi ister. Biz "No Skeleton" seçeneği seçeceğiz. Birsürü yazılar geçtikten sonra sorun yoksa tüm klasör ve dosyaları hazırlayıp bir de server otomatik olarak çalışacaktır. Server yayınını http://localhost:9778 portundan yapmaya başlayacaktır. Tarayıcıyı çalıştırırsanız şimdilik sayfa olmadığı için "not found" dönecektir. Server'ı ne zaman durdurmak isterseniz Ctrl+C tuşlamanız yeterli.

Anasayfa Eklenmesi

Hadi ilk sayfamızı oluşturalım. src/render/index.html dosyasını üretin ve içine şunları yazın:

<html>
<head>
    <title>Hoşgeldiniz! | Websitem</title>
</head>
<body>
    <h1>Hoşgeldiniz!</h1>
    <p>Websiteme hoşgeldiniz!</p>
</body>
</html>

Şimdi tarayıcıda http://localhost:9778 sayfasını yenilerseniz, kodunu yazdığınız sayfa görünür.

"Eee, ne oldu şimdi?, biz zaten html ile sayfa yazıyorduk" diyenler acık sabretsin.

Hakkında Sayfası ve bir Yerleşim Eklenmesi

Şimdi bir de "hakkımızda" sayfası koyalım ki , sitemizi ziyaret edenler kim olduğumuz konusunda bilgileri bizden alsın. Bu amaçla src/render/about.html adında yeni bir html döküman üretiyoruz.

<html>

<head>
    <title>Hakkımda | Websitem</title>
</head>
<body>
    <h1>Ben Kimim?</h1>
    <p>Her türlü program yazmayı severim. <strong>Ha bir de DocPad 
Kullanırım!</strong></p>
</body>
</html>

Yaşasııın, ikinci html sayfayı da yazdık. Tarayıcıda http://localhost:9778/about.html açınca bu sayfayı da görüntüleyebiliriz.

Fakat gördüğümüz gibi bir alt yapı var ve onu tekrarlayıp duruyoruz. 100 tane sayfa olsa biz de bu altyapıyı değiştirmeye kalksak 100 sayfada da değişiklik yapmak zorunda kalacağız. Mesela <head> kısmının içeriğini değiştirmek istiyoruz, bu durumda bütün dosyalarda değişiklik yapmamız gerekecek.

Layout'lar (yerleşimler) tüm dökümanı kapsarlar. Yerleşim değişince tüm dökümanlarda değişim olur. Uygulamamıza bir yerleşim tanımlamak için src/layouts/default.html.eco dosyasını üretip içine şunları yazalım:

<html>
<head>
    <title><%= @document.title %> | Websitem</title>
</head>
<body>
    <h1><%= @document.title %></h1>
    <%- @content %>
</body>
</html>

src/render/index.html

---
title: "Hoşgeldiniz!"
layout: "default"
isPage: true
---

<p>Websiteme hoşgeldiniz!</p>

src/render/about.html

---
title: "Hakkımda"
layout: "default"
isPage: true
---

<p>Her türlü program yazmayı severim. <strong>Ha bir de DocPad Kullanırım!</strong></p>

Ancaaak, server'ı kapatıp açıp sayfalarımıza tekrar baktığımızda yerleşime yazdığımız şeyleri görürüz, beklenen gibi kod çalışmaz. Çünkü daha "eco" yerleşim dosyalarını işleyecek eklentiyi yüklemedik.

Bunun dışında sayfalara "isPage" adında bir özellik ekledik. Şimdilik bu özellik DocPad için birşey ifade etmiyor, ilerde menüler vs. için kullanacağız.

Şablon Motorunun Kurulması

Bu klavuzda şablon motoru olarak eco kullanıyoruz. Şimdi bu plugin için konsolda şunları yazın:

docpad install eco

Plugin'i kurup server'ı tekrar çalıştırınca yerleşim şablon kodumuz çalışmaya başlayacaktır.

Peki neden döküman etiketinde (title) <%= kullandık da içeriği ifade ederken <%- kullandık? Sebebi şu, <%=
ile yazı içersindeki kod olabilecek özel karakterleri ayıklama yaparak yayınlar, <%- ise yazıyı olduğu gibi html koda ekler. Ne demeye çalıştığımı en iyi anlama yolu <%- yerine <%= yazarak "about.html" sayfasına bir bakın.

Live Reload (Anında Yükleme) plugin Yüklemek ve Bloklar

Her yaptığımız değişiklik için server'ı durdurup çalıştırmak gerekmesin diye "LiveReload" adında bir plugin var. Bunun sayesinde değişiklik yaptıkça tarayıcıda sayfayı tazelemek değişikliklerin işlenmesi için yeterli olacaktır.

docpad install livereload

Gelelim bloklara, bloklar sayesinde script'leri , stilleri ve metadata'ları sayfalarımıza yükleyebiliriz. Haydi default.html.eco yerleşimine 3 standart bloğu ekleyelim:

<html>
<head>
    <title><%= @document.title %> | Websitem</title>
    <%- @getBlock("meta").toHTML() %>
    <%- @getBlock("styles").toHTML() %>
</head>
<body>
    <h1><%= @document.title %></h1>
    <%- @content %>
    <%- @getBlock("scripts").toHTML() %>
</body>
</html>

Bu satırları ekledikten sonra bloklarda yapacağımız tüm değişiklikler otomatik olarak Live Reload sayesinde yüklenecektir.

Asset Eklemek

Resimler

Sayfamızın başına bir logomuzu ekleyelim. DocPad Logosunu indirin ve src/static/images/logo.gif dosyası olarak kaydedin.

src/layouts/default.html.eco

<html>
<head>
    <title><%= @document.title %> | Websitem</title>
    <%- @getBlock("meta").toHTML() %>
    <%- @getBlock("styles").toHTML() %>
</head>
<body>
    <img src="/images/logo.gif" />
    <h1><%= @document.title %></h1>
    <%- @content %>
    <%- @getBlock("scripts").toHTML() %>
</body>
</html>

Sayfayı tazeleyince logonun her iki sayfada da en üste geldiğini görürsünüz.

Stiller

Şimdi de h1 başlıklarımızı kırmızı yapalım. Stillerimizi render klasöründe src/render/styles/style.css dosyasına koyacağız.

h1 {
  color: red;
}

Sonra da bu stili sayfalarımızda aktif etmek için default.html.eco yerleşim dosyasında şu değişikliği yapalım:

<%- @getBlock("styles").add(["/styles/style.css"]).toHTML() %>

Sayfalarımıza tekrar baktığımızda yeni stilimizin etkili olduğunu görürüz.

Scriptler

Şimdi sıra efektler için biraz JavaScript kullanmakta. Bu amaçla JQuery JavaScript kütüphanesini kullanacağız.

İlk önce jQuery.js dosyasını indirin ve src/static/vendor/jquery.js olarak kaydedin. Şimdi bu faydalı kütüphaneyi websitemizde scriptlerde kullanacağız.

Sayfa yüklenirken yakışıklı bir efekt ekleyelim. src/render/scripts/script.js dosyasını oluşturup içine :

(function(){
    $("body").hide().fadeIn(2000);
})();

Şimdi koyduğumuz script dosyalarını websitemiz içersin diye default.html.eco yerleşim dosyasında şu satırı değiştirelim:


    <%- @getBlock("scripts").add(["/vendor/jquery.js", "/scripts/script.js"]).toHTML() %>

Ön İşleyicilerin Faydaları

Ön işleyiciler harika şeyler. Dökümanları birtek dilde yazıp birçok değişik şekillere dönüştürmeye yararlar. En büyük faydası zorunlu olduğunuz bir dili değil hoşunuza giden dili kullanmanıza imkan verirler.

HTML Önişleyicisi Olarak Markdown Kullanmak

Html kodlayarak bir web sayfası hazırlamak oldukça zor , okunması da zor bir iş. Çok şükür ki Markdown en önemli html önişleyici plugin olarak hizmetimizde.

Marked Markdown Plugin yükleyerek başlayalım.

docpad install marked

Şimdi daha önce yazdığımız render/about.html dosyasının adını render/about.html.md olarak değiştirelim. Böylece dosya içeriğinin Markdown için yazıldığını belirtiyoruz. Dosya içeriğini de şöyle düzenleyelim:

Her türlü program yazmayı severim. **Ha bir de DocPad Kullanırım!**

Gördünüz mü bir sürü html tag yerine daha anlaşılabilir sayfa içeriklerini Markdown formatında yazabiliriz. İşte statik web sitesi ile DocPad arasında en önemli farklardan ve avantajlardan biri.

Artık gazı aldık, sırada CSS stilleri kolaylaştırmak var.

CSS Önişleyici Olarak Stylus

Stylus başta gelen CSS önişleyicilerdendir.İşe Stylus Plugin yükleyerek başlayalım:

docpad install stylus

Sonra da src/render/styles/style.css dosyasının adını src/render/styles/style.css.styl olarak değiştirelim. Neden bunları render klasörüne koyduk ta static klasörüne koymadık demişseniz, cevap burada. Static klasörü içine konan dosyalar önişleyicilerde işlenmeden aynen "out" klasörüne aktarılırlar. Şimdi stil dosyamızın içeriğini şöyle değiştirelim:

h1
  color: red

Sonuç aynı ama stil dosyamızda da işçiliklerden kurtulmaya başladık.

JavaScript Önişleyici Olarak CoffeeScript

Biliyorsunuz bu JavaScript yazımı çok karmaşık. Bir tane noktalı virgül unutursan arada , yandın. Bu karmaşıklığı önlemek için CoffeeScript icat edildi.

CoffeeScript Plugin yükleyerek başlayalım:

docpad install coffeescript

Ardından render/scripts/script.js dosyasının adını render/scripts/script.js.coffee olarak değiştirelim.

İçeriğini de şöyle değiştirelim:

$("body").hide().fadeIn(2000)

Sonuç aynı ama artık CoffeeScript'in avantajları ve ferahlığıyla bir fincan kahve içebiliriz.

Bir Konfigürasyon Dosyası Yardımıyla Şablon Verisi ve Şablon Yardımcıları Eklemek

Konfigürasyon Dosyasının Amacı

DocPad konfigürasyon dosyası , bizim DocPad oluşumu websitemizin konfigüre etmemize yarar. Olayları takip eder ve yararlı faaliyetlerde bulunur.

Örneğin diyelim dökümana title tanımlamadık , bu durumda etiketimiz | Websitem şeklinde olacaktır. Böyle yarım yamalak olacağına etiketin "Benim Websitem" olmasını tercih ederiz. Bu amaçla "default.html.eco" yerleşim dosyamızda etiket satırını şöyle değiştirelim:

    <title><%= if @document.title then "#{@document.title} | Websitem" else "Benim Websitem" %> </title>

Bu kod değişikliği işimizi kısa yoldan halleder. Ama benzer olayların sayısı arttıkça hangisi hangi dosya içindeydi karmaşası başlayacaktır. Bunu önlemek için buna benzer işlemleri tek bir konfigürasyon dosyasına toplayıp sitemize bu dosyadan işlem yapmasını bildirmeliyiz.

DocPad'in tüm uygulama genelinde kullandığı konfigürasyon dosyası projemizin kök klasörü içindeki /docpad.coffee dosyasıdır. Bu dosya DocPad ilk çalıştığında üretilmiş olmalıdır, eğer yoksa da bu isimde bir dosya üretip içine şunları yazın:

# DocPad Configuration File
# http://docpad.org/docs/config

# Define the DocPad Configuration
docpadConfig = {
 # ...
}

# Export the DocPad Configuration
module.exports = docpadConfig

Dikkat ederseniz bu dosya CoffeeScript ile yazılmış.

Şablon Verilerinin Kullanımı

Şablonlarımızda kullanılan tüm veriler konfigürasyon içinde templateData adıyla tanımlanır. Örneğin @document bizim şablon verimizin bir parçası. Şimdi etiket için bir şablon veri tanımlıyalım. Konfigürasyon dosyası içine şunları yazalım:

# Define the DocPad Configuration
docpadConfig = {
  templateData:
    site:
      title: "Benim Websitem"
}

Şimdi default.html.eco dosyamızı şu hale getirebiliriz:

    <title><%= if @document.title then "#{@document.title} | Websitem" else @site.title %> </title>

Ancak tabii ki biz bu lojiği de konfigürasyon içine kaydırmak isteyebiliriz.

Şablon Yardımcıları ile Lojiği Tanımlamak

Konfigürasyonu CoffeeScript dosyası ile tanımladığımızdan fonksiyon tanımlamalarını da burada yapabiliriz. Bunlara Şablon Yardımcıları (Template Helpers) denir. Bunlar sayesinde lojiği de ayrı olarak konfigürasyona kaydırabiliriz. Şimdi yerleşim dosyasındaki lojiği konfigürasyona taşıyalım. /docpad.coffee dosyasına şunu ekleyelim:

# Define the DocPad Configuration
docpadConfig = {
  templateData:
    site:
      title: "Benim Websitem"
   
    getPreparedTitle: -> if @document.title then "#{@document.title} | Websitem" else @site.title
}

Ardından da default.html.eco yerleşim dosyamızda:

    <title><%= @getPreparedTitle() %> </title>

değişikliğini yaptıkmı ilk şablon yardımcımızı yazmış ve de kullanmış oluruz.

Sayfalarımıza Menü Listeleri Eklemek

Bir menümüz olsa eklediğimiz sayfalar otomatikman menüye eklense ne güzel olur dimi? Tabiiki olur, hadi yapalım.

Yerleşimi Değiştirelim

src/layouts/default.html.eco yerleşim dosyamızı değiştireceğiz. h1 tag'i öncesine şunları ekleyelim:

    <img src="/images/logo.gif" />
    <ul>
        <% for page in @getCollection("html").findAll({isPage:true}).toJSON(): %>
            <li class="<%= if page.id is @document.id then 'active' else 'inactive' %>">
                <a href="<%= page.url %>">
                    <%= page.title %>
                </a>
            </li>
        <% end %>
    </ul>
    <h1><%= @document.title %></h1>

Menü listesi geldi. Tabii liste olarak , biraz CSS ister. Şimdi "isPage" şablon verisinin ne işe yaradığını gördük, o değer "true" olmazsa sayfa menülere çıkmaz.

Burada her sayfa için yerleşim içindeki bu koddan dolayı ayrı ayrı sayfa listesi sorgulanıp menü oluşturulacaktır. Halbuki sayfadan sayfaya geçerken değişen bir bilgi yok, o zaman bu sorgulamayı bir kere yapıp sonuçları sayfa kodunda değerlendirelim.

Sorgunun Konfigürasyon Dosyasında yapılması

DocPad konfigürasyon dosyamıza geri dönelim:

docpadConfig = {

    templateData:
        site:
            title: "Benim Websitem"        

    getPreparedTitle: -> if @document.title then "#{@document.title} | Websitem" else @site.title

    collections:
        pages: ->
            @getCollection("html").findAllLive({isPage:true})
}

Sonra da yerleşim dosyamıza gidip "getCollection" satırını düzenliyoruz:

        <% for page in @getCollection("pages").toJSON(): %>

Arada farka dikkat ettiniz mi? Önce "finfAll" şimdi "findAllLive" kullandık. Böyle yapınca sorgumuz bir kere yapılıp sonrasında hep aynı bilgi kullanılıyor.

Sayfalarımız için Default Metadata oluşturmak

Şimdi her sayfaya yerleşim için "layout: default" yazmak istemezsek bunu da konfigürasyon dosyası içinde şöyle yaparız:

docpadConfig = {
    collections:
        pages: ->
            @getCollection("html").findAllLive({isPage:true}).on "add", (model) ->
                model.setMetaDefaults({layout:"default"})

}

Evet, her sayfaya "layout: default" yazmaktan da kurtulduk, başımız tavana erdi.

Benden bu kadar, "out" klasörü içindeki oluşturulan dosyaları herhangi bir web server'a yükledinizmi kullanıma hazır.

Boş Gezenin Boş Kalfası

Hakkımda

28 Ocak 2015 Çarşamba

Docpad İle Statik Web Sayfası Hazırlamak