Referans19 dk okuma

Template fonksiyonları

Built-in template fonksiyonlarının tamamı (slot, hoist, asset, URL fonksiyonları, json, aritmetik, string'ler ve listeler), imzaları ve örnekleri.

Template'ler Go'nun html/template paketiyle yazılır. Bu yüzden onun sunduğu her şey kullanılabilir: if, range, with, define, block ve standart fonksiyonlar olan and, or, not, len, index, slice, print, printf, println, eq, ne, lt, le, gt, ge, call, html, js ve urlquery. collage bunlara bu sayfadaki fonksiyonları ekler.

FonksiyonİmzaDöndürdüğü
slotslot namebir slot'taki fragment'lerin markup'ı
hoisthoist areahoist edilen içeriğin yerleşeceği yer
assetasset pathmount edilmiş bir dosyanın content-addressed URL'si
stylesheetstylesheet pathhiçbir şey; head için bir stylesheet tanımlar
csrfTokencsrfTokenform'un token'ını taşıyan hidden input
pageURLpageURL name [param value]...bir route'un bu render'ın locale'indeki URL'si
pageURLInpageURLIn locale name [param value]...bir route'un tam olarak o locale'deki URL'si
localeURLlocaleURL localebu page'in başka bir locale'deki URL'si
actionURLactionURL name [param value]...bir action'ın bu render'ın locale'indeki URL'si
fragmentURLfragmentURL page fragment [param value]...bir fragment path'inin bu render'ın locale'indeki URL'si
fragmentURLInfragmentURLIn locale page fragment [param value]...bir fragment path'inin tam olarak o locale'deki URL'si
withQuerywithQuery name value [name value]...query parametreleri set edilmiş ya da kaldırılmış hâliyle bu page'in URL'si
safeHTMLsafeHTML stringHTML olarak güvenilir sayılan string
safeURLsafeURL stringURL olarak güvenilir sayılan string
dictdict key value [key value]...çiftlerden oluşturulan bir map
defaultdefault fallback valuevalue, boşsa fallback
upperupper stringstring'in büyük harfli hâli
lowerlower stringstring'in küçük harfli hâli
titletitle stringher kelimenin ilk harfi büyük
joinjoin sep itemssep ile birleştirilmiş item'lar
formatTimeformatTime time layoutformatlanmış zaman
pathEscapepathEscape stringtek bir path segment'i için escape edilmiş string
jsonjson value [spaces] [pretty]değerin JSON hâli
prepre value [spaces] [pretty]escape edilmiş bir <pre> bloğu içinde değer
add, sub, mul, div, mod, min, maxadd a btam sayı aritmetiği
addf, subf, mulf, divfaddf a baynısı, float64 için
trim, replace, contains, hasPrefix, hasSuffix, splitreplace old new stringstring en sonda olacak şekilde strings fonksiyonları
truncatetruncate n stringilk n karakter; bir şey kesildiyse ardından …
first, lastfirst listbir listenin ilk ya da son elemanı
seqseq nüzerinde range yapılacak 1'den n'e sayılar
keys, hasKeykeys map, hasKey map keybir map'in sıralı key'leri; bir key'i içerip içermediği
digdig value key...map'ler ve struct'lar içinden bir path'teki değer, ya da hiçbir şey

Her fonksiyonun tipi bellidir. Bu yüzden template checker, hem registration'da hem collage check'te, string bir Title ile yazılmış {{add .Title 1}} çağrısını daha hiçbir request gelmeden bildirir. Registration ayrıca her fragment'in template'i üzerinde html/template'in escaper'ını çalıştırır. Escape edemediği bir template (hiç kapanmayan bir <script> string'i, bir attribute'u farklı durumlarda bırakan {{if}} dalları), ilk request'inde başarısız olan bir fragment değil, page'i ve fragment'i adıyla anan bir hatadır.

Hata dönen bir fonksiyon template'i başarısız kılar, fragment da onunla birlikte başarısız olur. Bu durumda fragment'in kendi failure policy'si uygulanır:

  • required bir fragment page'i başarısız kılar;
  • optional bir fragment fallback'ini render eder;
  • fallback'i yoksa hiçbir şey render etmez.

Development modunda bu "hiçbir şey", fragment'in adını ve hatasını içeren bir HTML yorumudur. Page'in üstündeki development paneli de fallback'i olsun olmasın, başarısız olan her fragment'i adıyla listeler. Hata her modda ayrıca bir uyarı olarak log'lanır. Ayrıntılar için Fragment'ler ve slot'lar sayfasına bakın.

Her render'da bağlananlar

İlk on iki fonksiyon, içinde çalıştıkları render'a ihtiyaç duyar: fragment'e, request'e, locale'e, uygulamanın route'larına ve mount'larına. Her biri farklı bir şey okur:

FonksiyonOkuduğu
slotbu fragment ve onun slot'larına bağlanmış fragment'ler
hoistrender'ın area'ları; page'in tamamı render edildikten sonra doldurulur
assetuygulamanın mount'ları
stylesheetbu render'ın tanım yaptığı head
csrfTokenresponse yazılırken her okuyucunun kendi token'ıyla değiştirilen bir placeholder
pageURL, actionURL, fragmentURLrender'ın locale'i ve uygulamanın route'ları
pageURLIn, fragmentURLInuygulamanın route'ları; locale bir argümandır
localeURLrender edilen page ve onun path parametreleri
withQueryrender edilen page, onun path parametreleri ve request'in query'si

Template'ler parse edilirken bu fonksiyonlar placeholder olarak register edilir, böylece template'ler onları çağırabilir. Gerçek implementasyonu ise render engine her render'da bağlar. Bir placeholder bir şekilde render dışında çalışırsa tahmin yürütmez, hata döner.

Bunun bir sonucu var: Config.Template.Funcs içinde bu adlardan birini taşıyan bir entry parse edilir, ama hiçbir zaman çağrılmaz; New bu entry'yi adıyla anan bir uyarı log'lar. Geri kalan otuz altı fonksiyonu Config.Template.Funcs ile değiştirebilirsiniz. Bir plugin ise kırk sekizinden hiçbirini değiştiremez; Kendi fonksiyonlarınızı eklemek bölümüne bakın.

Bir template'in fonksiyonları nereden gelir. collage.New template'leri tek bir function map ile parse eder: collage'ın kırk sekiz built-in'i (on ikisi placeholder), sonra plugin'lerin AddTemplateFunc ile kendi adları altında eklediği fonksiyonlar, sonra Config.Template.Funcs; her biri bir öncekinin üzerine merge edilir. Her render'da, her fragment için on iki per-render ad o render'dan yeniden bağlanır; plugin'lerin AddRenderFunc ile eklediği fonksiyonlar da öyle. Bu yüzden pageURL adlı bir Template.Funcs entry'si parse edilir ama hiç çalışmaz, upper adlı bir entry ise built-in'in yerini alır.collage.New: template parsetek bir function map48 built-in (12 placeholder)plugin'ler: AddTemplateFuncConfig.Template.Funcssonrakikazanırher render, her fragment12 per-renderbu render'dan bağlanırAddRenderFuncplugin'lerin, per-renderbir Template.Funcs entry'si…"pageURL"parse edilir, çalışmaz"upper"built-in'in yerini alır
Her template, collage.New içinde tek bir function map ile parse edilir: collage'ın kırk sekiz built-in'i, sonra plugin'lerin AddTemplateFunc ile kendi adları altında eklediği fonksiyonlar, sonra Config.Template.Funcs; her biri bir öncekinin üzerine gelir. Built-in'lerin on ikisi placeholder'dır. Her render'da, her fragment için bu on iki fonksiyon o render'dan yeniden bağlanır; plugin'lerin AddRenderFunc ile eklediği fonksiyonlar da öyle. Geri kalan otuz altı addan birini taşıyan bir entry'niz, örneğin upper, built-in'in yerini alır; per-render bir adı taşıyan, örneğin pageURL, parse edilir ama hiç çalışmaz.

slot

{{slot "name"}}

Bu fragment'in name adlı slot'una bağlanmış bütün fragment'leri bağlanma sırasıyla render eder ve markup'larını escape etmeden yerleştirir. slot her zaman bu fragment'in slot'unu ifade eder. Bu yüzden iki fragment'in her biri "sidebar" adlı bir slot'a sahip olabilir ve bu slot'lar birbirine karışmaz.

<article>
  {{slot "content"}}
  <aside>{{slot "related"}}</aside>
</article>
  • Slot'u tanımlayan, slot'un çağrılmasıdır. Fragment'in Go kodunda bunun için WithSlot gerekmez. Template'in çağırdığı ama hiçbir şey bağlanmamış bir slot hiçbir şey render etmez.
  • Kontrol ters yöndedir: bu template'in hiç çağırmadığı bir slot'a bağlanmış bir fragment, register sırasında ErrUnknownSlot ile başarısız olur. Hata, slot'u ve template'in gerçekten çağırdığı slot'ları söyler. Aksi hâlde bağlamanın iki tarafından birindeki bir yazım hatası, sessizce eksik kalan bir bölüm olurdu. Literal dışında bir şeyle adlandırılan bir slot ({{slot .Which}}), o fragment için kontrolü kapatır.
  • Boş bir slot hiçbir şey render etmez. WithSlot onu required yaptıysa durum farklıdır:
    • Hiçbir şey bağlanmamış ve resolver'ı olmayan required bir slot, page register edilirken ErrRequiredSlotUnfilled ile reddedilir. Böylece hiçbir zaman bir render'a ulaşmaz.
    • Resolver'ın doldurduğu required bir slot ise render sırasında kontrol edilir: hiç fragment dönmeyen bir resolver render'ı ErrRequiredSlotEmpty ile başarısız kılar.
  • Bir layout'un içeriği {{slot "content"}} içine gelir. Bu ad collage.DefaultContentSlot içinde tutulur.

slot çalıştığında child fragment'lerin data handler'ları çoktan başlamıştır. Hepsi parent render edilmeden önce aynı anda başlar. Ayrıntılar için Fragment'ler ve slot'lar sayfasına bakın.

hoist

{{hoist "head"}}

area'ya hoist edilen içeriğin nereye yerleşeceğini işaretler. Fragment'ler bu içeriği ağacın herhangi bir yerinden tanımlar: genellikle bir data handler'dan, program başlarken belli olan bir title için ise WithTitle ile. İçeriğin nereye gideceğine ise hoist karar verir:

<head>
  <meta charset="utf-8">
  {{hoist "head"}}
</head>
rc.HoistTitle(post.Title)
rc.HoistMeta("description", post.Summary)
rc.HoistLink("canonical", canonicalURL)

hoist içerik değil, bir marker yazar, çünkü altındaki hiçbir şey henüz render edilmemiştir. Ağacın tamamı render edildikten sonra her marker, kendi area'sı için tanımlanan içerikle değiştirilir. Böylece page'in derinlerinde yapılan bir tanım da head'e ulaşır. Hiçbir şey tanımlanmamış bir area'nın marker'ı ise iz bırakmadan kaldırılır.

  • Bir area'nın adı harf, rakam, _ ve -'den oluşur. Başka her şey template'i başarısız kılar: marker bir HTML yorumudur ve request'ten beslenen {{hoist .Area}} gibi bir ad aksi hâlde onu kapatabilirdi.
  • Aynı key altındaki iki tanımdan biri kalır. En içteki fragment'inki kazanır; aynı derinlikte page'de daha sonra gelen kazanır: bir slot içinde daha sonra bağlanan fragment, slot'lar arasında template'in daha sonra render ettiği.
  • Yalnızca render edilen bir fragment bir şey tanımlar. Template'in hiç çağırmadığı bir slot'un arkasındaki fragment'in title'ı, Hoist* çağrıları ve Cached çağrılarının tag'leri page'e hiç ulaşmaz. Başarısız olan bir fragment hoist'larını da beraberinde götürür; böylece optional bir fragment'in fallback'i başarısız olanın title'ıyla render edilmez.

HoistTitle, HoistMeta, HoistProperty, HoistLink, HoistAlternate ve HoistStylesheet"head" area'sına yazar. rc.Hoist(area, key, html) ise adını verdiğiniz herhangi bir area'ya yazar. Head'e içerik ekleyen bir plugin bu marker'a ihtiyaç duyar: marker yoksa plugin'in içeriğinin gidecek yeri yoktur. Ayrıntılar için Head ve SEO sayfasına bakın.

asset

<link rel="stylesheet" href="{{asset "/static/app.css"}}">
<img src="{{asset "/static/logo.svg"}}" alt="">

Bir mount'taki dosyanın content-addressed URL'sini döner. Bu URL, dosyanın path'ine uzantıdan hemen önce içeriğinin hash'i eklenerek elde edilir.

/static/app.css  →  /static/app.41014ebb6c2d9f07.css

Byte'lardan türetilen bir ad yalnızca o byte'ları ifade edebilir. Dosyayı bir yıllık, immutable bir ömürle serve etmeyi güvenli kılan da budur: dosya değişirse adı da değişir ve eski ad bir daha hiç istenmez.

  • Path, mount'un dosyayı serve ettiği URL'dir ve mount'un prefix'ini de içerir.
  • Var olmayan bir dosya bir URL değil, hata üretir: ErrUnknownAsset. Aksi hâlde page sorunsuz render edilir, ama 404 veren bir stylesheet'e link verirdi.
  • Hiçbir mount'un serve etmediği bir path ya da hiç mount'u olmayan bir uygulama da ErrUnknownAsset üretir. Hiçbir mount'un prefix'i path'i kapsamıyorsa mesaj bunu söyler.
  • Mount'un 404 ile cevaplayacağı bir ad da öyledir: /static/.env gibi bir dotfile ya da mount içinde geçerli bir path olmayan bir ad.
  • Dosya adının her segment'i escape edilir; böylece içindeki bir #, ? ya da % path'in parçası olarak kalır: /static/100%.css, /static/100%25.<hash>.css olarak link'lenir.
  • Static export, orijinallerin yanına yalnızca page'lerin istediği fingerprint'li kopyaları yazar.

Go tarafında rc.Asset(path) aynı URL'yi döner. Ayrıntılar için Static asset'ler sayfasına bakın.

stylesheet

{{stylesheet "/static/gallery.css"}}

Bu fragment'in bir stylesheet'e ihtiyaç duyduğunu tanımlar ve çağrıldığı yerde hiçbir şey render etmez. Layout'un {{hoist "head"}} çağırdığı yerde, page'in head'ine dosyanın asset URL'siyle bir <link rel="stylesheet" href="…"> eklenir.

Böylece bir fragment, nerede kullanılırsa kullanılsın kendi stillerini yanında taşıyabilir:

{{stylesheet "/static/gallery.css"}}
<div class="gallery">…</div>

Tanım path'e göre key'lenir. Bu yüzden birkaç fragment'in istediği bir stylesheet head'de yalnızca bir kez yer alır. stylesheet, asset ile aynı durumlarda başarısız olur. Go tarafındaki karşılığı rc.HoistStylesheet(path)'tir.

csrfToken

<form method="post">
  {{csrfToken}}
  <input name="email" type="email">
  <button>Subscribe</button>
</form>

Form'un request forgery token'ını taşıyan hidden input'u render eder:

<input type="hidden" name="_csrf" value="…">

Yalnızca değeri değil de input'un tamamını render etmesinin bir nedeni var. Değerin tam olarak doğru ada sahip bir field'a konması gerekir. Field adını yanlış yazan bir form ise nedenini açıklayan hiçbir şey olmadan reddedilir.

Render sırasında yazılan değer bir placeholder'dır. Response yazılırken bu placeholder her okuyucunun kendi token'ıyla değiştirilir.

Cache'lenmiş bir page'in form taşıyabilmesinin nedeni budur: cache'teki byte'larda placeholder durur ve her okuyucu kendi token'ını alır.

  • Security.DisableCSRF set edildiğinde csrfToken, render'ı ErrCSRFDisabled ile başarısız kılar. Aksi hâlde token bekleyen bir form token'sız render edilirdi.
  • Security.CSRFFieldName farklı bir ad belirtmedikçe field'ın adı _csrf'tir. Verifier da her iki durumda bu adı okur. Bu yüzden field'ın adını değiştirdiğinizde template'te bir şey değiştirmeniz gerekmez.
  • Static export'ta token'ı yerleştirecek bir sunucu yoktur. Bu yüzden token taşıyan bir page export edilmez ve rapor bunun nedenini belirtir.

Ayrıntılar için Form'lar ve action'lar sayfasına bakın.

pageURL

<a href="{{pageURL "about"}}">About</a>
<a href="{{pageURL "blog-post" "slug" .Slug}}">{{.Title}}</a>
<link rel="alternate" type="application/rss+xml" href="{{pageURL "feed"}}">

name altında register edilmiş page'in ya da document'ın URL'sini döner. Path pattern'ini param value çiftleriyle doldurur. Ada göre link vermek, bir page'in path'i değiştiğinde link'in de onu takip etmesini sağlar.

  • Bu render'ın locale'inde çalışır. Türkçe bir page'de pageURL "blog-post" Türkçe path'i döner. Geçerli locale'de path'i olmayan bir route için bunun yerine varsayılan locale'deki path'e link verilir. Böylece yalnızca İngilizce olan bir page'e link veren Türkçe bir page yine de render edilir.
  • Katıdır. Bilinmeyen bir ad (ErrUnknownRoute) render'ı başarısız kılar. Tek sayıda parametre argümanı, eksik ya da boş bir parametre ve pattern'de placeholder'ı olmayan bir parametre de (ErrRouteParams) aynı sonucu verir. Oluşturulamayan bir link, okuyucunun karşısına çıkan bir 404 değil, development'ta bulunması gereken bir bug'dır.
  • Değerler string, tam sayı ya da fmt.Stringer olabilir ve escape edilir.
  • Bazı değerler reddedilir. Tarayıcının bir path adımı olarak yorumlayacağı . ya da .. değeri reddedilir. Float, bool ya da nil de reddedilir, çünkü hiçbirinin URL'de tek bir bariz yazımı yoktur. ErrRouteParams hatası değerin tipini söyler:
<a href="{{pageURL "user" "id" .ID}}">{{.Name}}</a>
  • Hem page hem document olarak register edilmiş bir ad için tahmin yürütülmez, ad reddedilir.

Go tarafındaki karşılığı app.URL(name, locale, params)'tır. Ayrıntılar için Link'ler ve locale'ler sayfasına bakın.

pageURLIn

<a href="{{pageURLIn "tr" "about"}}">Hakkımızda</a>
<a href="{{pageURLIn "en" "blog-post" "slug" .Slug}}">Read in English</a>

pageURL ile aynı işi tam olarak verilen locale'de yapar ve fallback uygulamaz. O locale'de path'i olmayan bir route ErrNoPathInLocale üretir. Hiçbir URL'nin ulaşamadığı bir locale ise ErrLocaleUnreachable üretir. Böyle bir locale ne varsayılan locale'dir ne de Locale.Supported içinde yer alır.

localeURL

{{with localeURL "en"}}<a hreflang="en" href="{{.}}">English</a>{{end}}
{{with localeURL "tr"}}<a hreflang="tr" href="{{.}}">Türkçe</a>{{end}}

Render edilen page'in aynı path parametreleriyle başka bir locale'deki URL'sini döner. Bir dil seçici bununla yapılır.

  • O locale'de path'i olmayan bir page hata değil, boş string döner. Böylece {{with}}, page'in çevrilmediği bir dili atlar.
  • Hiçbir URL'nin ulaşamadığı bir locale yine de hatadır (ErrLocaleUnreachable). Çünkü bu eksik bir çeviri değil, template'teki bir hatadır.
  • Bir page'e ait olmayan bir render'da başarısız olur: bir document'ın ya da kendi URL'sindeki bir action'ın render'ında. Page'inin onun için açtığı bir URL'den sunulan fragment ise o page ile render edilir. Bu yüzden orada page'e link verir.
  • Arama motorlarının okuduğu <link rel="alternate" hreflang> etiketlerini Go tarafında rc.HoistAlternate ile tanımlayın. Ayrıntılar için Head ve SEO sayfasına bakın.

actionURL

<form method="post" action="{{actionURL "logout"}}">{{csrfToken}}…</form>
<form method="post" action="{{actionURL "vote" "id" .ID}}">{{csrfToken}}…</form>

name adıyla register edilmiş action'ın URL'sini döner. URL, pageURL'in bir page'inkini oluşturduğu gibi oluşturulur: path bir kez, Go tarafında yazılır ve ona post eden her form onu takip eder.

  • Bu render'ın locale'inde çalışır.pageURL gibi varsayılan locale'e fallback yapar.
  • pageURL kadar katıdır. Bilinmeyen bir ad ErrUnknownRoute, pattern'i tam doldurmayan parametreler ErrRouteParams üretir.
  • Action'ların kendi adları vardır.actionURL "login" action'ı, pageURL "login" ise page'i verir, çünkü bir login page'i ile bir login action'ı olağan bir ikilidir. Bir page'in kendi action'ı register edildiği adla bulunur: contact adlı bir page'de WithAction("POST", …) için bu ad "contact:POST"'tur.

Go tarafındaki karşılığı app.ActionURL(name, locale, params)'tır.

fragmentURL

<div data-live="{{fragmentURL "home" "cpu-usage"}}">{{slot "cpu-usage"}}</div>
<div data-live="{{fragmentURL "post" "comments" "slug" .Slug}}">…</div>

Bir page'in fragment'lerinden biri için WithFragmentPath ile açtığı path'i döner. Path page'in adından ve fragment'in adından oluşturulur. Path bir kez, Go tarafında yazılır ve ona giden her link onu takip eder.

  • Bu render'ın locale'inde çalışır.pageURL gibi varsayılan locale'e fallback yapar.
  • pageURL kadar katıdır. Bilinmeyen bir page ErrUnknownRoute, page'in açmadığı bir fragment ErrUnknownFragmentPath, bir locale'de iki path'te açılmış bir fragment ErrAmbiguousFragmentPath, pattern'i doldurmayan parametreler ise ErrRouteParams olur. Her biri render'ı başarısız kılar.

Go tarafındaki karşılığı app.FragmentURL(page, fragment, locale, params)'tır. Ayrıntılar için Link'ler ve locale'ler sayfasına bakın.

fragmentURLIn

<div data-live="{{fragmentURLIn "tr" "home" "cpu-usage"}}">…</div>

Tam olarak verilen locale'de, fallback olmadan çalışan fragmentURL'dir. O locale'de path'i olmayan bir fragment ErrNoPathInLocale, hiçbir URL'nin ulaşamadığı bir locale ise ErrLocaleUnreachable olur.

withQuery

<a href="{{withQuery "page" (add .Page 1)}}">Older posts</a>
<a href="{{withQuery "tag" ""}}">Every tag</a>
<a href="{{withQuery "page" 1 "sort" "new"}}">Newest first</a>

Render edilen page'i, request'in query'si ve verilen parametreler set edilmiş olarak döner. "" değeri bir parametreyi kaldırır, diğerleri olduğu gibi kalır. /blog?tag=go&page=2 üzerinde yukarıdaki üç link /blog?page=3&tag=go, /blog?page=2 ve /blog?page=1&sort=new&tag=go olur: query, parametre adlarına göre sıralanarak yazılır.

  • Path, page'in kendi URL'sidir. Render'ın locale'inde ve path parametreleriyle kurulur; pageURL'deki gibi varsayılan locale'e fallback yapar. Kendi URL'sinden yenilenen bir fragment'te de link çıplak fragment'e değil, page'e gider. Page'i olmayan, kendi URL'sindeki bir action'da ise action'ın URL'sidir.
  • Query, render'ın gördüğü query'dir. Cache'lenmiş bir page'de bu, yalnızca cache key'indeki parametrelerdir; okuyucunun diğer parametreleri asla değildir. Böylece paylaşılan kopyaya yazılan bir link, bir okuyucunun utm_source'unu bir sonrakine taşıyamaz.
  • Adlar string'dir; değerler ise pageURL'dekiler gibi string, tam sayı ya da fmt.Stringer olur. Başka bir tip ya da değeri olmayan bir ad render'ı başarısız kılar.

safeHTML

{{safeHTML .RenderedMarkdown}}

Bir string'i güvenilir HTML olarak işaretler. Böylece html/template onu escape etmeden yerleştirir. Bu bir kaçış yoludur: yalnızca kendi ürettiğiniz ya da kendiniz sanitize ettiğiniz markup için kullanın. Kullanıcının yazdığı hiçbir şey için kullanmayın.

safeURL

<a href="{{safeURL .ExternalLink}}">Visit</a>

Bir string'i güvenilir URL olarak işaretler ve html/template'in URL sanitization'ını devre dışı bırakır. Bu sanitization normalde güvenmediği bir scheme'i, örneğin javascript:'i, #ZgotmplZ ile değiştirir. Yalnızca validate ettiğiniz URL'ler için kullanın.

dict

{{template "card" dict "Title" .Title "URL" (pageURL "post" "slug" .Slug)}}

Sırayla gelen key ve value'lardan bir map oluşturur. Bir sub-template'e birden fazla değer geçirmek için kullanılır. Key'ler string olmalıdır ve argümanlar çiftler hâlinde gelmelidir. Bu hatalardan herhangi biri template'i başarısız kılar; mesaj hangisi olduğunu söyler.

default

<h2>{{default "Untitled" .Subtitle}}</h2>
<h2>{{.Subtitle | default "Untitled"}}</h2>

value'yu döner. value boş string ise fallback'i döner. İki argüman da string'dir. Fallback'in önce gelmesinin nedeni, pipe'lı kullanımın doğal okunmasıdır. Çünkü bir pipeline, değerini son argüman olarak geçirir.

upper ve lower

<span class="badge">{{upper .Status}}</span>
<code>{{lower .Code}}</code>

strings.ToUpper ve strings.ToLower ile aynıdır.

title

<h1>{{title .Name}}</h1>

Her kelimenin ilk harfini büyük, geri kalan harflerini küçük yapar. Bir kelime, art arda gelen harflerden oluşur. Bu yüzden harf olmayan her karakter, yani boşluk, tire ya da kesme işareti, yeni bir kelime başlatır:

GirdiÇıktı
hello worldHello World
iPHONE caseIphone Case
o'neil-smithO'Neil-Smith

join

<p>Tags: {{join ", " .Tags}}</p>

strings.Join(items, sep) ile aynıdır, yalnızca separator önce gelir. items bir []string olmalıdır.

formatTime

<time datetime="{{formatTime .Published "2006-01-02"}}">
  {{formatTime .Published "2 January 2006"}}
</time>

Reference time layout'u ile t.Format(layout) çağırır. t bir time.Time'dır. Zaman, taşıdığı location'a göre formatlanır. Başka bir location istiyorsanız zamanı data handler'da dönüştürün.

pathEscape

<a href="https://example.com/wiki/{{pathEscape .Term}}">{{.Term}}</a>

url.PathEscape'tir: string'i bir path'in tek bir segment'ine sığacak şekilde escape eder. Böylece içindeki bir /, bir alt dizine inmek yerine %2F olur. Kendi page'lerinize verdiğiniz bir link'in buna ihtiyacı yoktur: pageURL parametrelerini kendisi escape eder.

json

<script type="application/json" id="chart-data">{{json .Series 2 false}}</script>

Değerin JSON hâlidir. Aksi söylenmedikçe iki boşlukla girintili yazılır: {{json v 4}} dört boşlukla girintiler, {{json v 2 false}} ise tek satır yazar. Boşluk sayısı 0 ile 16 arasındadır.

template.JS döner. Bir <script> içinde, yani application/json verisinde ya da onu okuyan bir script'te, olduğu gibi yazılır. <, > ve & ise \u003c biçiminde escape edilmiş kalır, böylece bir değer script'i kapatamaz. Başka her yerde diğer metinler gibi escape edilir. encoding/json'un encode edemediği bir değer, örneğin bir channel, render'ı başarısız kılar.

pre

{{pre .}}

Değeri bir <pre> bloğu içinde gösterir; bir template'e ne verildiğine bakmak içindir. Bir string ya da []byte olduğu gibi gösterilir; başka her şey, aynı isteğe bağlı boşluk sayısı ve pretty ile, json'un yazdığı gibi. İçerik her zaman escape edilir.

Aritmetik

<p>Page {{.Page}} of {{.Pages}}, posts {{add (mul (sub .Page 1) .PerPage) 1}} onwards</p>
<p>{{printf "%.1f" (divf .Rating 2.0)}} / 5</p>

add, sub, mul, div, mod, min ve max iki int alır; addf, subf, mulf ve divf ise iki float64. div, mod ve divf ile sıfıra bölmek render'ı başarısız kılar.

String'ler

<h2>{{.Slug | replace "-" " " | title}}</h2>
{{if hasPrefix "https://" .Link}}<a href="{{.Link}}" rel="external">{{.Link}}</a>{{end}}
<p>{{truncate 140 .Summary}}</p>

trim, strings.TrimSpace'tir. replace old new s, contains sub s, hasPrefix prefix s, hasSuffix suffix s ve split sep s ise string'i en sonda alan strings fonksiyonlarıdır; böylece her biri bir pipeline içinde doğal okunur. replace her old'u değiştirir, split bir []string döner.

truncate n s, s'yi ilk n karakterine kadar keser ve bir şey kesildiyse ardına … koyar. Byte değil karakter sayar, bu yüzden bir Türkçe harf asla ikiye bölünmez. Negatif bir n render'ı başarısız kılar.

Listeler ve map'ler

{{with first .Posts}}<a href="{{pageURL "post" "slug" .Slug}}">Latest: {{.Title}}</a>{{end}}
{{range seq 5}}<span class="star">{{.}}</span>{{end}}
{{range keys .Counts}}<li>{{.}}: {{index $.Counts .}}</li>{{end}}
{{if hasKey .Flags "beta"}}<span class="badge">beta</span>{{end}}
  • first list ve last list, bir slice'ın ya da array'in ilk ve son elemanıdır. Boş bir listede hiçbir şey dönerler, böylece {{with}} onu atlar.
  • seq n, sayan bir döngü için 1'den n'e kadar olan sayılardır. n 1'den küçükse boştur; 100000'den büyükse render'ı başarısız kılar.
  • keys map, string key'li bir map'in sıralanmış key'leridir. Böylece onların üzerinden dönen bir döngü her seferinde aynı şekilde render edilir. hasKey map "k", altında sıfır değer olsa bile map'in k'yı içerip içermediğini söyler.
  • Her biri başka bir şey verildiğinde render'ı başarısız kılar: first'e bir map, keys'e bir liste gibi.

dig

{{with dig .Settings "theme" "accent"}}<meta name="theme-color" content="{{.}}">{{end}}

String key'li map'lerin ve struct'ların export edilmiş alanlarının içinden, pointer'ları izleyerek o path'teki değeri döner. Hiçbir yere varmayan bir path, yani eksik bir key, export edilmemiş bir alan ya da yoldaki nil bir pointer, hata değil hiçbir şeydir. Böylece {{with dig …}} isteğe bağlı bir değeri karşılar.

Kendi fonksiyonlarınızı eklemek

Fonksiyonlarınızı New'dan önce Config.Template.Funcs ile ekleyin:

app, err := collage.New(&collage.Config{
	Template: collage.TemplateConfig{
		Root: "templates",
		Funcs: template.FuncMap{
			"money": func(cents int64) string {
				return fmt.Sprintf("$%d.%02d", cents/100, cents%100)
			},
		},
	},
})

Bu fonksiyonlar built-in'lerin üzerine merge edilir. Bu yüzden built-in bir adı taşıyan entry, o built-in'in yerini alır. Her render'da bağlanan fonksiyonlar bunun dışındadır: onlardan birinin adını taşıyan entry kabul edilir ama hiç çalışmaz ve New bu entry'yi adıyla anan bir uyarı log'lar.

Fonksiyonların New'dan önce tanımlı olması gerekir, çünkü html/template yalnızca template parse edilirken function map'te bulunan bir adı çağırabilir. Kimsenin register etmediği bir adı çağıran template, ilk request'te değil, New'da hata verir.

Bir plugin de fonksiyonları aynı şekilde, Configure aşamasında ekler. Aynı adı taşıyan bir entry uygulamada da varsa uygulamanınki geçerli olur. Bir plugin built-in bir adı alamaz: AddTemplateFunc bunu ErrDuplicateTemplateFunc ile reddeder. Ayrıntılar için Plugin yazmak sayfasına bakın.

Bir plugin'in AddRenderFunc ile eklediği fonksiyon, yukarıdaki on iki fonksiyon gibi her render'da bağlanır, ama aynı iki kurala uyar:

  • Uygulamanın aynı adı taşıyan entry'si, AddTemplateFunc'ta olduğu gibi kazanır ve New bunu bir kez log'lar.
  • AddTemplateFunc gibi, kırk sekiz built-in addan hiçbirini alamaz. AddRenderFunc bunları ErrDuplicateTemplateFunc ile reddeder.

İkisi de template dilinin kendi adlarından birini alamaz: eq, len, index, print, html, js, urlquery ve Go'nun diğer builtin ve escaper'ları. Bu da ErrDuplicateTemplateFunc'tır.

Request'e ihtiyaç duyan her şey bir fonksiyona değil, bir data handler'a aittir. Page'in verisi de zaten oradan gelir.

Örnek: iki dilde bir ürün page'i

Link'ler ve locale'ler sayfasındaki dükkân İngilizce ve Türkçe satış yapar. Ürün page'i, etrafındaki layout ile birlikte, on iki per-render fonksiyonun dokuzunu çağırır:

FonksiyonÖrnekteki işi
assetdükkânın stylesheet'i ve path'i veriden gelen ürün resmi
hoisttitle'ın ve product.css'in head'de yerleşeceği yer
localeURLdil seçici
slotlayout'un içeriği ve ürünün stok kutusu
stylesheetyalnızca bu page'in ihtiyaç duyduğu product.css
pageURLkataloğa geri dönen link
fragmentURLstok kutusunu yenileyen bir script için kutunun kendi URL'si
actionURL"sepete ekle" form'unun hedefi
csrfTokeno form'un token'ı

catalog paketi sizin veri katmanınızın yerini tutar ve her ürünün adını iki dilde saklar. Handler, render'ın locale'ine göre etiketleri seçer ve ürünün adını title olarak hoist eder:

type labels struct {
	Back string
	Add  string
}

var labelsIn = map[string]labels{
	"en": {Back: "All products", Add: "Add to basket"},
	"tr": {Back: "Tüm ürünler", Add: "Sepete ekle"},
}

type productView struct {
	catalog.Product // ID, Name, Image
	Labels          labels
}

func loadProduct(ctx context.Context, rc *collage.RenderContext) (productView, []string, error) {
	id := rc.Param("id")
	p, err := catalog.Find(ctx, id, rc.Locale)
	if errors.Is(err, catalog.ErrNoProduct) {
		return productView{}, nil, fmt.Errorf("catalog: no product %q: %w", id, collage.ErrNotFound)
	}
	if err != nil {
		return productView{}, nil, err
	}
	rc.HoistTitle(p.Name)
	return productView{Product: p, Labels: labelsIn[rc.Locale]}, []string{"product:" + id}, nil
}

func loadStock(ctx context.Context, rc *collage.RenderContext) (int, error) {
	return catalog.Stock(ctx, rc.Param("id"))
}

Page'in, stok kutusunun ve sepet action'ının her locale'de bir path'i vardır:

  • Katalog page'i, Link'ler ve locale'ler sayfasının register ettiği page'dir.
  • addToBasket, Form'lar ve action'lar sayfasındaki gibi action'ın handler'ıdır.
  • static/, Static asset'ler sayfasındaki gibi /static/ altına mount edilir.
  • Ürün Required'dır: o olmadan page'in gösterecek bir şeyi yoktur.
layout := collage.NewFragment("layout", "layouts/master.html").Build()

stock := collage.NewFragment("product-stock", "fragments/stock.html").
	WithData(collage.Load(loadStock)).
	Build()

product := collage.NewPage("product").
	WithLayouts(layout).
	WithContent(collage.NewFragment("product", "pages/product.html").
		WithData(collage.LoadTagged(loadProduct)).
		WithSlotFragment("stock", stock).
		Required().
		Build()).
	WithPath("en", "/products/{id}").
	WithPath("tr", "/urunler/{id}").
	WithFragmentPath("en", "/products/{id}/stock", stock).
	WithFragmentPath("tr", "/urunler/{id}/stok", stock).
	Build()

if err := app.Register(catalogue, product); err != nil {
	return err
}
return app.RegisterAction(collage.NewAction("basket-add").
	WithPath("en", "/basket/{id}").
	WithPath("tr", "/sepet/{id}").
	WithMethods(http.MethodPost).
	WithHandler(addToBasket).
	Build())

Layout dükkânın stylesheet'ine link verir, head'in area'sını işaretler ve dil seçiciyi taşır:

<!-- templates/layouts/master.html -->
<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <link rel="stylesheet" href="{{asset "/static/app.css"}}">
  {{hoist "head"}}
</head>
<body>
  <nav>
    {{with localeURL "en"}}<a hreflang="en" href="{{.}}">English</a>{{end}}
    {{with localeURL "tr"}}<a hreflang="tr" href="{{.}}">Türkçe</a>{{end}}
  </nav>
  {{slot "content"}}
</body>
</html>

Ürünün template'i link verdiği her page'i, fragment'i ve action'ı adıyla anar, hiçbir zaman path yazmaz:

<!-- templates/pages/product.html -->
{{stylesheet "/static/product.css"}}
<article class="product">
  <a href="{{pageURL "catalogue"}}">{{.Labels.Back}}</a>
  <h1>{{.Name}}</h1>
  <img src="{{asset .Image}}" alt="">
  <div data-live="{{fragmentURL "product" "product-stock" "id" .ID}}">{{slot "stock"}}</div>
  <form method="post" action="{{actionURL "basket-add" "id" .ID}}">
    {{csrfToken}}
    <button>{{.Labels.Add}}</button>
  </form>
</article>
<!-- templates/fragments/stock.html -->
<p class="stock">{{.}}</p>

Okuyucuya ulaşan

/tr/urunler/42 için gelen request 200 ile cevaplanır. Boş satırlar çıkarılmış ve token kısaltılmış hâliyle page şöyledir:

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <link rel="stylesheet" href="/static/app.6d6068180a5c710c.css">
  <title>Pirinç güverte lambası</title><link rel="stylesheet" href="/static/product.e38a7cd1dac68eec.css">
</head>
<body>
  <nav>
    <a hreflang="en" href="/products/42">English</a>
    <a hreflang="tr" href="/tr/urunler/42">Türkçe</a>
  </nav>
<article class="product">
  <a href="/tr/urunler">Tüm ürünler</a>
  <h1>Pirinç güverte lambası</h1>
  <img src="/static/products/42.04115f7d8dde41ce.svg" alt="">
  <div data-live="/tr/urunler/42/stok"><p class="stock">12</p>
</div>
  <form method="post" action="/tr/sepet/42">
    <input type="hidden" name="_csrf" value="…">
    <button>Sepete ekle</button>
  </form>
</article>
</body>
</html>

Aynı template'ler /products/42'yi İngilizce render eder. Ad ve etiketler veriden gelir; URL'ler render'ın locale'ine göre değişir:

Template'te/products/42'de/tr/urunler/42'de
pageURL "catalogue"/products/tr/urunler
fragmentURL "product" "product-stock" "id" .ID/products/42/stock/tr/urunler/42/stok
actionURL "basket-add" "id" .ID/basket/42/tr/sepet/42
localeURL "en", localeURL "tr"/products/42, /tr/urunler/42aynı
asset .Image/static/products/42.04115f7d8dde41ce.svgaynı
  • Title ve product.css marker'a yerleşir. İkisi de layout'un marker'ın üstüne yazdığı app.css'ten sonra gelir. Önce title gelir: handler onu template çalışmadan önce tanımlamıştır.
  • asset, veriden gelen bir path'i de literal bir path kadar kolay alır. Mount'ta olmayan bir resim ErrUnknownAsset'tir. Ürün required olduğu için page, kırık bir resim göstermek yerine 500 döner.
  • Token her okuyucunun kendisinindir. Bu page cache'lenseydi cache'teki byte'lar placeholder'ı taşırdı ve her okuyucu onun yerine kendi token'ını alırdı.