Temel kavramlar24 dk okuma
Page'ler ve layout'lar
Page nedir: layout'ları ve içeriği, kimin görebileceği, ona ulaşan path'ler, nasıl cache'lendiği, başarısız olunca ne gösterdiği ve register etmenin etkisi.
Bir page, adı olan bir render yapılandırmasıdır. Page'i hangi fragment'lerin oluşturduğunu belirler: bir layout ve onun içindeki içerik. Ayrıca page'e hangi URL'lerin ulaştığını, çıktısının nasıl cache'lendiğini ve render edilemediğinde yerine hangi page'in gösterileceğini de belirler. Page'in kendine ait bir template'i ya da verisi yoktur. Bunlar fragment'lerine aittir.
page := collage.NewPage("blog-post").
WithLayouts(layout).
WithContent(post).
WithPath("en", "/blog/{slug}").
Incremental(10 * time.Minute).
Build()
if err := app.RegisterPage(page); err != nil {
log.Fatal(err)
}
Page oluşturmak
collage.NewPage(name) bir builder başlatır. Her WithX çağrısı tek bir şeyi ayarlar, Build() da *collage.Page'i döner.
Ad, page'in kimliğidir. Link'ler bu addan üretilir ({{pageURL "blog-post" "slug" .Slug}}), testler ve plugin'ler page'leri bu adla bulur ve iki page aynı adı taşıyamaz. Adı page'in nerede durduğuna göre değil, ne olduğuna göre seçin. Böylece URL değişse de ad geçerliliğini korur.
Builder'lar hata dönmek için zinciri hiçbir zaman kesmez. İstenen şeyi yapamayan bir çağrı hatayı kaydeder ve devam eder. BuildErr() kaydedilen bütün hataları döner:
builder := collage.NewPage("blog-post").WithLayouts(layout).WithPath("en", "/blog/{slug}")
page := builder.Build()
if err := builder.BuildErr(); err != nil {
return err // collage.ErrMissingContent: there is no WithContent
}
BuildErr'ü görmezden gelmek bir hatanın gözden kaçmasına yol açmaz. Builder'ın kaydettiği hatalar, ürettiği değerin üzerinde kalır. RegisterPage bu hatalardan birini taşıyan bir page'i reddeder ve page'in adını içeren bir hata döner. Hatanın page'in kendisine ya da ağacındaki herhangi bir fragment'e ait olması fark etmez; örneğin iki kez tanımlanmış bir slot da buna dahildir. Birinin BuildErr'ü çağırıp çağırmamış olması da sonucu değiştirmez. BuildErr'ü, kontrolünüzde olmayan bir girdiden oluşturulan page'lerde kontrol edin. Orada hatayı kaynağına daha yakın bir yerde görmek istersiniz.
Layout ve içerik
Bir sitedeki page'lerin çoğu dış kısmı ortak kullanır: <head>, header ve footer. Farklı olan iç kısımdır. Dış kısım layout'tur. Layout, template'i content adında bir slot'u çağıran bir fragment'tir. İç kısım ise content fragment'tir. Page, bu fragment'i göstermek için vardır.
layout := collage.NewFragment("layout", "layouts/master.html").
WithTitle("My site").
Build()
<!-- templates/layouts/master.html -->
<!doctype html>
<html lang="en">
<head>{{hoist "head"}}</head>
<body>
<header>…</header>
{{slot "content"}}
<footer>…</footer>
</body>
</html>
Layout hiçbir slot tanımlamaz. Template'indeki {{slot "content"}} çağrısı tanımın kendisidir. Çağırdığı diğer slot'lar için de durum aynıdır; bkz. Fragment'ler ve slot'lar. WithTitle, layout'u kullanan her page'e, içerideki bir şey daha iyisini belirtene kadar bir <title> verir.
WithLayouts(layout) ve WithContent(post) bu ikisini belirtir. İçeriği layout'un content slot'una (collage.DefaultContentSlot) register işlemi yerleştirir. Bu bağlamayı kendiniz yapmazsınız. Template'i hiç {{slot "content"}} çağırmayan bir layout ise register sırasında ErrUnknownSlot ile reddedilir, çünkü içeriğin render edileceği bir yer yoktur. Layout'ta WithSlot(collage.DefaultContentSlot, collage.SlotRequired, collage.SlotSingle) hâlâ kabul edilir. Bu, content'e page'in kendi içeriği dışında bağlanan her fragment'i reddetmesi gereken bir layout içindir (ErrSlotOccupied).
Her page'in bir içeriği olmalıdır, yoksa ErrMissingContent alırsınız. Layout ise isteğe bağlıdır. Layout'u olmayan bir page, content fragment'ini response'un tamamı olarak render eder. Template'i baştan sona eksiksiz bir HTML belgesi olan bir page'in istediği de tam olarak budur.
Tek layout, birçok page
Layout, bir sitede en çok tekrar kullanılan şeydir. Bu yüzden tek bir *collage.Fragment değerini error page'ler dahil bütün page'ler arasında paylaşmak güvenlidir. Register işlemi, içeriği bağlamadan önce her page'e layout'un slot tablosunun kendine ait bir kopyasını verir. Böylece A page'inin içeriği hiçbir zaman B page'inde görünmez.
Yalnızca slot tablosu kopyalanır. Layout'un template'i, data handler'ı, fallback'i ve diğer slot'larına önceden bağlanmış fragment'ler ortak kalır. Bu da register işleminin o bağlamaların bir anlık görüntüsünü aldığı anlamına gelir. Bir page register edildikten sonra ortak layout'a bağlanan bir fragment o page'de görünmez. Önce layout'u eksiksiz oluşturun, sonra page'leri onunla register edin.
Scaffold, layout'unu her çağrıda yeni bir fragment dönen bir fonksiyon olarak yazar: layouts.Master(). Bu yöntem de aynı şekilde çalışır. Tek bir değeri paylaşmak yalnızca izin verilen bir seçenektir.
Layout içinde layout
Bir page birden fazla layout'un içinde durabilir: dışta <head>'iyle HTML iskeleti, onun içinde de giriş page'lerinin paylaştığı daha dar bir çerçeve. WithLayouts zincirin tamamını en dıştakinden başlayarak alır; tek bir layout WithLayouts(layout) olarak yazılır:
func Master() *collage.Fragment {
return collage.NewFragment("layout", "layouts/master.html").
WithTitle("My site").
Build()
}
func Auth() *collage.Fragment {
return collage.NewFragment("auth-layout", "layouts/auth.html").Build()
}
page := collage.NewPage("login").
WithLayouts(layouts.Master(), layouts.Auth()).
WithContent(login).
WithPath("en", "/login").
Build()
WithLayouts(layouts.Master(), layouts.Auth()) zinciri en dıştakinden başlayarak sıralar. İç içe yerleştirmeyi register işlemi yapar: login içeriği en içteki layout olan Auth()'un content slot'una, Auth() da Master()'ın content slot'una girer. Bu yerleştirmelerin her biri, layout'un slot tablosunun page'e ait kopyası üzerinde yapılır.Tek bir layout içeriği nasıl render ediyorsa, zincirdeki her layout da içindekini {{slot "content"}} ile öyle render eder. Sarmalamanın tamamını register işlemi yapar. İçerik en içteki layout'un content slot'una, her layout da kendisini saran layout'un content slot'una girer.
Bu yüzden içinde boşluk bırakan bir layout da bitmiş bir *collage.Fragment'tir. Onu oluşturan bir yardımcı fonksiyon, page'in tamamlaması gereken bir builder değil, build edilmiş fragment'i döner.
Tek bir layout'ta olduğu gibi her page, zincirdeki her layout'un slot tablosunun kendine ait bir kopyasını alır. Bu yüzden zincirin layout'ları site genelinde paylaşılabilir. Zincirdeki bir layout'un content slot'u boş gelmelidir, çünkü onu register işlemi doldurur. Dolu gelen bir layout ErrSlotOccupied ile reddedilir.
WithLayouts şu durumlarda, register işleminin reddettiği bir hata kaydeder:
| Çağrı | Hata |
|---|---|
| hiç layout verilmeden | ErrMissingLayout |
| nil bir layout ile | ErrNilFragment |
| aynı layout iki kez verilerek | ErrFragmentCycle |
| aynı builder'da ikinci kez | ErrConflictingLayout |
Kendi verisi olan bir layout
Layout bir fragment'tir. Bu yüzden onun bir CMS'ten gelen kısımları, yani sitenin adı, bir menü ya da footer'ın link'leri, bir page'in içeriği gibi WithData ile yüklenir. Her kısma, layout'un bir slot'una bağlanan kendi fragment'ini verin. Böylece her biri yalnızca gösterdiğini yükler ve tek başına başarısız olur:
var menuKey = collage.NewKey[[]backend.MenuItem]("menu")
func Master(api *backend.API) *collage.Fragment {
return collage.NewFragment("layout", "layouts/master.html").
WithData(collage.Load(headData(api))). // title, meta tags: hoisted into the head
WithSlotFragment("header", Header(api)).
WithSlotFragment("footer", Footer(api)).
Build()
}
func Footer(api *backend.API) *collage.Fragment {
return collage.NewFragment("footer", "layouts/footer.html").
WithData(collage.Load(func(ctx context.Context, rc *collage.RenderContext) (footerView, error) {
menu, err := collage.Cached(rc, menuKey, time.Hour, []string{"menu"}, api.Menu)
return footerView{Menu: menu}, err
})).
Build()
}
<!-- templates/layouts/master.html -->
<body>
{{slot "header"}}
{{slot "content"}}
{{slot "footer"}}
</body>
Verinin geldiği client, herhangi bir page'in constructor'ına olduğu gibi layout'un constructor'ına da routes.go'nun onları kurduğu yerden verilir. Layout'un her page'in parçası olması üç sonuç doğurur:
- Her page için ayrı ayrı değil, bir kez çekin. Her page menüyü render eder. Bu yüzden onu
collage.Cachedüzerinden okuyun. Böylece otuz page onu bir kez çeker, static export da öyle. - Tag'ler bir değişikliği her page'e ulaştırır.
Cached'e verilen tag'ler, layout'u render eden her page'e eklenir. Bu yüzden CMS'in webhook'undan gelenapp.InvalidateTags(ctx, "menu")menüyü yeniler ve onu göstermiş her cache'lenmiş page'i atar. - Yavaş bir CMS her page'i yavaşlatır. Kısma bir
WithTimeoutve birWithFallbackverin. Böylece gelmeyen bir menü, gelmeyen bir page değil, menüsü olmayan bir page olur. Bkz. Bir fragment başarısız olduğunda.
Private page'ler: guard'lar
Sitenin yalnızca giriş yapmış okuyucuların görebileceği bir bölümü, bunu söyleyen bir layout'tur. WithGuard bir fragment'e bir fonksiyon verir. Page sunulmadan önce bu fonksiyona, bu request'in page'i alıp alamayacağı sorulur:
func requireUser(ctx context.Context, r *http.Request) (*collage.GuardDecision, error) {
if session.FromContext(ctx).Get("user") != "" {
return nil, nil // allowed
}
login, err := collage.URL(ctx, "login", nil)
if err != nil {
return nil, err
}
return &collage.GuardDecision{
Status: http.StatusSeeOther,
Location: login + "?next=" + url.QueryEscape(r.URL.RequestURI()),
}, nil
}
func Private() *collage.Fragment {
return collage.NewFragment("private", "layouts/private.html").
WithGuard(requireUser).
Build()
}
page := collage.NewPage("dashboard").
WithLayouts(layouts.Master(), layouts.Private()).
WithContent(dashboard).
WithPath("en", "/dashboard").
Build()
Guard, okuyucuyu kendisine yazılmış bir path'e değil, adıyla belirtilen bir page'e gönderir. collage.URL(ctx, name, params), render'ı olmayan kod için rc.URL'dir: request hangi locale'deyse adresi o locale'de kurar. Böylece /tr/dashboard üzerindeki bir guard okuyucuyu Türkçe login'e gönderir. Page'in o locale'de path'i yoksa {{pageURL}} gibi varsayılan locale'e düşer. Eklenecek bir query yoksa collage.GuardSeeOtherPage(ctx, "login", nil) kararın tamamını döner. Bu, guard'ların SeeOtherPage'idir; SeeOtherPage ise action'lar için *ActionResult döner. Bilinmeyen bir ad hatadır ve request'i başarısız kılar; kimseyi içeri almaz.
collage add guard private, siz kontrolünü yazana kadar herkesi reddeden guard'ı yazar. collage add layout private --guard private onu taşıyan bir layout yazar, collage add page dashboard --guard private ise guard'ı yeni bir page'in içeriğine koyar (collage add'e bakın).
Private() ile sarılan her page private'tır; bir page'i public yapmak için Private()'ı zincirine eklememek yeterlidir. Route'larla senkron tutulacak bir korumalı path listesi yoktur. Guard, page'e hangi URL ulaşırsa ulaşsın, her locale'de ve her parametreyle çalışır.
Parametreler request'in üzerindedir: r.PathValue("slug"), request hangi locale'in path'inden gelirse gelsin page'in pattern'indeki {slug}'dır. Bir yazıyı yalnızca yazarının düzenlemesine izin veren bir guard slug'ı okur ve başka herkese 404 döner; böylece bir slug, okuyucuya ait olmayan yazılar hakkında hiçbir şey söylemez:
func Author(posts *blog.Posts) collage.GuardFunc {
return func(ctx context.Context, r *http.Request) (*collage.GuardDecision, error) {
post, ok := posts.BySlug(r.PathValue("slug"))
if !ok || post.AuthorID != session.FromContext(ctx).Get(session.UserKey) {
return &collage.GuardDecision{Status: http.StatusNotFound}, nil
}
return nil, nil
}
}
Bir guard, page'in omurgasında olduğunda o page için sorulur: page'in zincirindeki bir layout ya da page'in content fragment'i. Guard'lar en dıştakinden başlayarak çalışır, content fragment'inki en son sorulur ve ilk cevap veren karar verir.
Başka bir fragment'teki guard yok sayılır: bir slot'a bağlanan, bir resolver'ın döndüğü ya da fallback olan fragment'lerdekiler. Bir page'i kimin görebileceği, onu oluşturan fragment'lerin değil, page'in kendi özelliğidir.
Guard üç şekilde cevap verir:
| Dönüş | Okuyucunun aldığı |
|---|---|
nil, nil | Page |
bir 3xx status ve bir Location | Oraya body'siz bir redirect. Location verilip status sıfır bırakılırsa 303 See Other olur. Collage-Fetch ile işaretlenmiş bir request, bir action'ın redirect'inde olduğu gibi 204 alır; hedef Collage-Location içinde gelir. |
bir 4xx ya da 5xx status, location yok | O status, body'siz |
Bunların dışındaki her şey (gidecek yeri olmayan bir redirect, bir 200) ErrInvalidGuardDecision'dır. Guard'ın bir hata dönmesinde olduğu gibi request 500 ile başarısız olur. Ne demek istediğini söyleyemeyen bir guard'ın niyeti tahmin edilmez: location'ı olmayan bir redirect, aksi hâlde tam da saklaması gereken page'e düşerdi.
Guard'ın kapsadıkları:
- Page'in render'ları,
GETveHEAD. Guard routing'den sonra ve page'in cache'i okunmadan önce çalışır. Böylece engellenen bir okuyucu cache'lenmiş bir render'a hiç ulaşmaz ve private bir pageStatic()olabilir. Guard her render hook'undan da önce çalışır: engellenen request page'e hiç ulaşmamıştır, bu yüzden render'ları izleyen plugin'lere haber verilmez. - Page'in kendi URL'sindeki action'lar. Bir form bulunduğu page'e post eder. Okuyucunun göremediği bir page, form'unu da gönderemeyeceği bir page'dir. Guard, body okunmadan ve forgery kontrolünden önce çalışır.
- Page'in fragment path'leri.
WithFragmentPathile kendi URL'sinde açılan bir fragment page'in bir kısmıdır ve fragment'in kendi guard'ından önce page'in guard'larından geçer. Böylece private bir page'deki fragment path de private'tır. - Kendi URL'sinde register edilen bir action ve page'in not-found ile error page'leri kapsanmaz. Aksi hâlde private bir error page, hatayla karşılaşan okuyucuyu redirect ederdi.
Guard'ın izin verdiği okuyucular page'in cache'ini paylaşır; bu cache sunucunun kendi cache'idir. Bir şey onlar için cache'i atlamadıkça böyledir: elagoht/session session'ı olan her okuyucu için cache'i atlar. Sunucunun önündeki bir CDN ya da proxy guard çalıştırmaz. Bu yüzden guard'lı bir page, stratejisi ne derse desin Cache-Control: private, no-cache ile gönderilir.
Guard'ın kendi cevabı (giriş yapmaya yönlendiren bir redirect, bir ret) no-store ile gönderilir. Böylece varsayılan olarak bir 404'ü ya da 308'i saklayan bir CDN, bir okuyucuya verilen cevabı sonrakine vermez.
İçeriği okuyucudan okuyucuya değişen bir page ise guard değil kişiselleştirme konusudur; bkz. Caching. Static export guard'lı page'leri hiç yazmaz.
Guard'ın neyi kontrol ettiği framework'ün bilebileceği bir şey değildir. Yukarıdaki requireUser session'ı okur; bir guard aynı şekilde bir header'ı, bir rolü, bir feature flag'i, kısacası request'in taşıdığı her şeyi okuyabilir. Session plugin'i bu guard'ı hazır olarak, session.RequireUserPage("login") şeklinde sunar; path'i elle yazmak için session.RequireUser("/login") da vardır. collage inspect her page için guard taşıyan fragment'leri listeler.
Path'ler
WithPath(locale, pattern), bir locale'de page'e ulaşan URL'yi register eder. Tek dilli bir site tek bir locale kullanır. Bir page'in her locale'de farklı bir path'i olabilir:
collage.NewPage("about").
WithContent(about).
WithPath("en", "/about").
WithPath("tr", "/hakkinda")
Bir pattern segment'lerden oluşur:
| Segment | Neyle eşleşir |
|---|---|
blog | Tam olarak bu metinle |
{slug} | Tam olarak bir segment'le, slug adıyla yakalanır |
{slug}.md, post-{id}, v{version}.json | Önünde ve arkasında bu metni taşıyan, arada en az bir karakter olan bir segment'le. Yakalanan, aradaki kısımdır: /blog/hello.md için slug = hello |
{rest...} | Geriye kalan her şeyle, rest adıyla yakalanır. Yalnızca son segment olabilir ve etrafında metin olamaz |
Bir data handler yakalanan değeri rc.Param("slug") ya da rc.PathParams["slug"] ile okur. Değerler percent-decode edilmiş olarak ve segment segment gelir.
Encode edilmiş bir slash (%2F) içeren bir segment 404 döner. URL standardına göre %2F bir ayırıcı değildir: /public%2Fsecret, değeri public/secret olan tek bir segment'tir.
Ama Go, path'i hiçbir middleware okumadan önce decode edip r.URL.Path'e yazar. Orada /public%2Fsecret artık /public/secret olmuştur ve encode edilmiş slash gerçek bir slash'ten ayırt edilemez. Yani router'ın tek segment gördüğü yerde middleware iki segment görür. Tek segment'i eşleyen bir router, middleware'in başka bir şey olarak değerlendirdiği bir request'i sunmuş olurdu. Bu yüzden collage iki okumadan hiçbirini sunmaz.
UTF-8 olmayan byte'lara decode edilen bir segment, örneğin %c3%28, de 404 döner: {{pageURL}} ve App.URL Go string'lerini UTF-8 olarak escape eder, dolayısıyla sitenin hiçbir link'i böyle bir segment içermez.
Kendisi bir path olan bir değer, örneğin guide/intro, bir catch-all'da yer almalıdır: {rest...}. {{pageURL}} ve BuildPath, tek bir segment'in değerindeki /'ı reddeder.
Her seviyede önce static bir segment denenir. Ardından etrafında metin olan placeholder'lar gelir, en özelinden başlayarak. Sonra düz bir {param}, en son da {rest...} denenir. Eşleştirme backtracking ile yapılır. Böylece iki route da eşleşebilecek olsa bile /blog/archive, /blog/{slug}'a karşı kazanır.
/blog ve /blog/ aynı route'tur ve tek bir adresleri vardır: bir page'in diğer yazımı, query korunarak o adrese 301 ile yönlendirilir. Adres, slash'siz olanıdır; Config.TrailingSlash açıksa slash'li olanıdır. Bir document ve bir action, link'leri nasıl kuruluyorsa öyle, iki modda da slash'siz yazılır: /sitemap.xml//sitemap.xml'e 301, /login/'e yapılan bir POST ise /login'e 308 olur; böylece form yeniden post edilir. Middleware path'i router redirect etmeden önce, geldiği hâliyle görür. Bu yüzden tam bir path'i koruyan bir middleware onu sondaki slash olmadan karşılaştırmalıdır.
Placeholder'ın etrafında metin
Bir yazı ile onun Markdown'ı ya da kategori başına bir feed yan yana durabilir:
collage.NewPage("post").WithPath("en", "/blog/{slug}") // /blog/hello
collage.NewDocument("post-md", "text/markdown; charset=utf-8").
WithPath("en", "/blog/{slug}.md") // /blog/hello.md
collage.NewDocument("feed", "application/rss+xml").
WithPath("en", "/feeds/{category}.xml") // /feeds/go.xml
Bir segment'in hangi route'a gittiği, route'ların kayıt sırasına hiçbir zaman bağlı değildir. Aynı konumdaki iki placeholder üç durumdan birindedir:
| Örnek | Sonuç | |
|---|---|---|
| Ayrık: hiçbir segment ikisine birden uymaz | {slug}.md ve {slug}.json | İkisi de kaydedilir, metin karar verir |
| İç içe: biri diğerinin daha özel hâlidir | {slug}.min.md, {slug}.md'nin içinde; ikisi de {slug}'ın içinde | İkisi de kaydedilir, daha özel olan kazanır |
| Kesişen: bir segment ikisine de uyar ama hiçbiri daha özel değildir | a{x} ve {x}b, ikisi de aXb'ye uyar | ErrOverlappingPattern, böyle bir segment'i örnek vererek |
Yani yukarıdaki route'larla /blog/hello.md document'e, /blog/hello sayfaya gider. Static bir /blog/index.md ikisini de geçer. Metnin arasında hiçbir şey olmayan /blog/.md ise sayfanındır ve slug = .md olur. Etrafında metin olan bir placeholder . ya da .. yakalamaz: /blog/...md de sayfaya gider, document'e .. slug'ını vermez. Link kurulurken yalnızca değer escape edilir: {{pageURL "post-md" "slug" "çay"}}, /blog/%C3%A7ay.md olur. Export de blog/hello.md dosyasını blog/hello/index.html'in yanına yazar.
Bir segment tek bir placeholder taşır. {name}.{ext} için a.b.c'nin tek bir cevabı yoktur, bu yüzden {name}.md ve {name}.json'u iki ayrı route olarak kaydedin. Regex de yoktur. Bir değeri handler'ı kontrol eder ve tanımadığı bir değer için collage.ErrNotFound döner. Bu sayede her çakışma route kaydedilirken kesin olarak belirlenebilir.
Pattern'lerdeki hatalar request anında sürpriz olarak çıkmaz. Register sırasında hata verirler:
- Bir pattern
/ile başlamalıdır. Boş segment ve boş placeholder adı içeremez, catch-all'u da yalnızca en sona koyabilir. Aksi hâldeErrInvalidPathya daErrInvalidPatternalırsınız. - Bir segment en fazla bir placeholder taşır, catch-all'un etrafında da metin olamaz:
/{name}.{ext}ve/files/{path...}.mdErrInvalidPatternverir. - Bir pattern her placeholder adını bir kez kullanır:
/a/{id}/b/{id}'de bir link'in hangiid'yi dolduracağını söylemenin yolu yoktur, bu yüzdenErrInvalidPatternverir. - İlk segment'i, büyük-küçük harf fark etmeksizin bir locale kodu olan bir path, örneğin
/tr/guideya da/EN/about, locale prefix'i sanılır ve ona hiçbir zaman ulaşılmaz:ErrLocaleUnreachable. Path'i prefix'siz register edin; prefix sizin için eklenir. İlk segment olarak bir placeholder sorun değildir. Aynısı bir document'ın, bir action'ın ve bir redirect'in kaynağı için de geçerlidir. - Etrafında metin olan iki placeholder kesişirse, örneğin
/a{x}ve/{x}b,ErrOverlappingPatternalırsınız. - Bir locale'de aynı path'te iki route olursa
ErrDuplicateRoutealırsınız. Bir page ile bir document'ın çakışması da buna dahildir, çünkü ikisi aynı ağacı kullanır. - Aynı konumda iki farklı parametre adı, örneğin
/blog/{slug}ve/blog/{id}/editya da{slug}.mdve{id}.md,ErrAmbiguousParameterNameverir.
Bir page GET ve HEAD request'lerine cevap verir. OPTIONS request'ine de 204 ile cevap verir. Bu response'un Allow header'ı, URL'nin kabul ettiği metotları listeler. Diğer bütün metotlar aynı Allow header'ıyla 405 alır. Tek istisna, page'in o metot için bir action'ı olmasıdır. Bir form, üzerinde bulunduğu page'e bu sayede post eder.
Locale'ler, /tr/hakkinda gibi locale prefix'leri, /en/about'u /about'a gönderen redirect ve page adlarından link üretmek Link'ler ve locale'ler sayfasında anlatılıyor.
Bir page ayrıca eski URL'lerden redirect'ler de taşıyabilir. Bunun için WithRedirect(from, to, status) ve WithPermanentRedirect(from, to) kullanılır:
- bir redirect, request'in query string'ini hedefine taşır;
- yakaladığı bir değer, düştüğü yere göre escape edilir: bir path segment'i ya da
?işaretinden sonraki bir query değeri. Böylece/login?next={slug}'a ikinci birnextverilemez; - siteden çıkacak bir hedef (
//hostya da/\host) register sırasındaErrInvalidPatholur; - iki path'ten birinde satır sonu gibi bir control karakteri olması
ErrInvalidRedirectolur; - kaynağının kendisinin eşleştiği bir hedef bir döngüdür,
ErrRedirectLoop:/docs'tan/docs/'a (bir kaynak slash'li de slash'siz de eşleşir) ya da/blog/{slug}'dan/blog/{slug}'a; - bir page'in ya da document'ın path'iyle eşleşen bir kaynak, register sırası ne olursa olsun
ErrRedirectShadowsPageolur, çünkü redirect'ler önce eşleştirilir ve route hiçbir zaman cevap vermezdi. Path'le yalnızca eşleşen bir kaynak da buna dahildir:WithRedirect("/{slug}", "/blog/{slug}", 301)/about.txt'yi de alır, bu yüzden oradaki bir document reddedilir. Redirect'in kaynağını daraltın. İkisi de placeholder taşıyan iki pattern karşılaştırılmaz, çünkü örtüşüp örtüşmedikleri request'e bağlıdır; orada redirect kazanır.
Static export, yazdığı bir page'in üstüne düşen bir redirect'te başarısız olur; bkz. Static export.
Render stratejileri
Her page'in üç stratejiden biri vardır. Strateji, page'in çıktısının cache'lenip cache'lenmeyeceğini belirler:
| Metot | Strateji | Davranış |
|---|---|---|
Dynamic() | StrategyDynamic | Her request'te render edilir, hiçbir zaman cache'lenmez |
Static() | StrategyStatic | Bir kez render edilir, tag'leri invalidate edilene kadar cache'ten sunulur |
Incremental(ttl) | StrategyIncremental | Cache'ten sunulur, ttl dolduktan sonra yeniden render edilir |
Bu üç çağrıdan hiçbirini yapmayan bir page, register edilene kadar StrategyAuto'dur. Register işlemi stratejiyi belirler: render ettiği herhangi bir şeyin data handler'ı ya da slot resolver'ı varsa dynamic, yoksa static olur. Template'lerden ve sabit değerlerden (collage.Value, WithTitle) oluşan bir page herkes için aynı render edilir, bu yüzden söylemeye gerek kalmadan cache'lenir. Handler ise request'i, bir cookie'yi ya da saati okuyabilir ve dışarıdan bu anlaşılamaz. Bu yüzden handler'ı olan bir page, Static() ya da Incremental(ttl) diyene kadar her request'te render edilir. Kuralın tamamı Caching sayfasındadır.
Incremental pozitif bir TTL ister (ErrInvalidTTL). collage export'un dosyaya yazabildiği page'ler de static ve incremental page'lerdir. Dynamic bir page her request'te render edilmek için vardır, bu yüzden atlanır.
Cache yalnızca uygulama onu açtığında devreye girer (Config.Cache.Enabled, scaffold'da açıktır). Development'ta ise hiçbir zaman devreye girmez. Orada cache'lenmiş bir page, az önce düzenlediğiniz template'i gizlerdi.
Cache'lenen bir page, response'ta yalnızca bir okuyucuya ait hiçbir şey yoksa Cache-Control: public ile gönderilir. Bir middleware'in daha önce Set-Cookie eklediği bir response private, no-store ile gider; böylece bir CDN o cookie'yi sonraki okuyucuya veremez. Page sunucuda yine cache'lenir. Aynı URL için TLS üzerinden gelen bir request ile düz bir request, cache key'inde ayrı entry'lerdir.
Cache'lenen bir page'i iki builder metodu daha etkiler. WithDependencyTags(tags...), data handler'ların bildirdiği dependency tag'lerine page'in kendi tag'lerini ekler. WithCacheParams(names...) ise cache key'ine hangi query parametrelerinin katılacağını belirler. Bunların hepsinin nasıl bir araya geldiği Caching sayfasında anlatılıyor: tag'ler, invalidation, query parametreleri ve page'ler yerine veriyi cache'lemek.
Not-found ve error page'leri
Bir page gösterilemediğinde yerine başka bir page gösterilir. Bunun iki durumu ve iki seviyesi vardır.
- Not found, 404. Ya hiçbir route URL ile eşleşmemiştir ya da
Required()bir fragment'in data handler'ıcollage.ErrNotFound'u wrap eden bir hata dönmüştür. Yani URL'nin işaret ettiği içerik yoktur. - Error, 500. Ya
Required()bir fragment başka bir sebeple başarısız olmuştur ya da framework'ün kendi akışında bir şey başarısız olmuştur.
Bir page kendi yerine geçecek page'leri belirleyebilir. Uygulama da site genelinde geçerli olanları belirleyebilir:
post := collage.NewPage("blog-post").
WithLayouts(layout).
WithContent(postContent).
WithPath("en", "/blog/{slug}").
WithNotFoundPage(postNotFound). // "no such post", with a search box
WithErrorPage(postError).
Build()
app.RegisterNotFoundPage(siteNotFound)
app.RegisterErrorPage(siteError)
Bir hata olduğunda önce page'in kendi NotFoundPage'i ya da ErrorPage'i kullanılır. Sonra site genelindeki page, en son da framework'ün built-in page'i devreye girer. Hiçbir route ile eşleşmeyen bir URL'nin sorabileceği bir page yoktur. Bu yüzden doğrudan site genelindeki not-found page'ine gider.
Bir error page de diğerleri gibi bir page'dir. Bir layout'u, bir content fragment'i ve isterse data handler'ları olur, ama path'i yoktur. Path'e ihtiyacı da yoktur, çünkü ona bir şeyin başarısız olmasıyla ulaşılır.
func NotFoundPage() *collage.Page {
content := collage.NewFragment("not-found-content", "pages/404.html").Build()
return collage.NewPage("not-found").
WithLayouts(layouts.Master()).
WithContent(content).
Dynamic().
Build()
}
Birkaç kural, error page'lerin en kötü anda başarısız olmasını önler:
WithNotFoundPageya daWithErrorPageile belirtilen her page register edilmiş olmalıdır. Bunun içinRegisterPage,RegisterNotFoundPageya daRegisterErrorPagekullanılır. Aksi hâlde uygulamaErrUnregisteredErrorPageile başlamayı reddeder. Nedenini aşağıda bulabilirsiniz.- Bu page'lerin template'leri, onları belirten page register edilirken kontrol edilir. Böylece bir 500 page'indeki yazım hatası, site zaten hata verirken fark edilmez. Uygulama başlarken hata olarak karşınıza çıkar.
- Bir page kendi error page'i olamaz (
ErrSelfErrorPage). - Bir error page'in render çıktısı hiçbir zaman cache'lenmez. Render başarısız olursa ya da hiçbir şey üretmezse yerine built-in page sunulur. Hata da log'lanır ve plugin'lere bildirilir. Kendi kendine 500 verebilen bir 500 page'i, sitenin tamamen çökmesi demektir.
Built-in page, hiçbir harici dosyaya ihtiyaç duymayan, kendi içinde tamamlanmış bir HTML'dir. Bu yüzden bozulan şey asset'ler olsa bile render edilir. Development'ta hatanın başladığı fragment'in adını verir ve hata zincirini gösterir. Production'da ise tek bir genel cümle gösterir, çünkü hata metinleri host adlarını, dosya yollarını ve credential'ları sızdırır. Hatalar sayfası, framework'ün bildirdiği bütün hataları listeler.
collage export, RegisterNotFoundPage ile register edilen page'i 404.html olarak yazar. Static host'lar, bulunamayan bir URL için bu dosyayı sunar.
Register etmek
if err := app.RegisterPage(page); err != nil {
log.Fatal(err)
}
Bir page RegisterPage'te kontrol edilir ve bir araya getirilir. Böylece render sırasında başarısız olacak bir şey burada, uygulama başlarken başarısız olur ve hata mesajında page'in adı yer alır. Bu, page'in içerdiği bütün fragment'ler için geçerlidir. Page'in kendi URL'sinde açtığı bir fragment de buna dahildir. Bir request çalışırken slot resolver'ın döndüğü bir fragment ise buradan görülemez. O fragment ilk render edildiğinde kontrol edilir. RegisterPage sırasıyla şunları yapar:
- nil bir page'i, boş bir adı, başka bir page'in kullandığı bir adı (
ErrDuplicatePage) ve uygulama başladıktan sonra yapılan her register işlemini (ErrAppStarted) reddeder; - builder'ı bir hata kaydetmiş olan page'i reddeder. Page'den ulaşılabilen ya da
WithFragmentPathile açılan herhangi bir fragment'in builder'ı için de aynısı geçerlidir. Bu hatalar,BuildErr()'ün döneceği hatalardır; - zincirdeki her layout'un slot tablosunu kopyalar, content fragment'i en içteki kopyanın
contentslot'una, her layout'u da kendisini saranınkine bağlar; - page'i ve fragment path'leri dahil bütün fragment ağacını doğrular: path'ler, strateji ve TTL, redirect'ler, içi boş kalmış required slot'lar ve kendisinden yine kendisine ulaşılabilen bir fragment;
- her fragment'in template'inin yüklendiğini kontrol eder (
ErrTemplateNotFound).WithFragmentPathile açılan fragment'ler ve page'in kendi not-found ve error page'leri de buna dahildir. Template'ihtml/template'in escape edebildiğini ve bir şey bağlanan her slot'un, template'in çağırdığı bir slot olduğunu da kontrol eder (ErrUnknownSlot; hata slot'u ve template'in yaptığı çağrıları belirtir). Escaper'ın reddettiği bir template (hiç kapanmayan bir<script>string'i, bir attribute'u farklı durumlarda bırakan{{if}}dalları) aksi hâlde başlangıçtan geçer ve ilk request'te başarısız olurdu; bu yüzden burada fragment'i adıyla anan bir hatadır; - strateji tanımlamamış bir page'in stratejisini bütün ağaca bakarak belirler;
- page'in path'lerini, redirect'lerini, action'larını ve fragment path'lerini router'a ekler. Router orada zaten olanla çakışan birini reddeder: aynı route, belirsiz bir parametre adı, bir route'un üstüne düşen bir redirect.
Her hatayı fatal kabul edin. Yarıda başarısız olan bir register işlemi geri alınmaz. Örneğin bir locale'de kabul edilen path, bir sonraki locale reddedildiğinde router'da kalır. Bunun sebebi, başarısız bir register işleminin toparlanılacak bir durum olmamasıdır. Bu, hiç başlamaması gereken bir programdır.
Birkaçını birden register etmek
app.Register page'leri, document'ları ve action'ları tek bir çağrıda alır ve her birini sırayla RegisterPage, RegisterDocument ya da RegisterAction üzerinden register eder. Scaffold'un oluşturduğu routes.go, ona yapılan tek bir çağrıdan ibarettir:
func register(app *collage.App) error {
if err := app.Register(
pages.Home(),
blogpages.Post(),
documents.Health(),
authactions.Logout(),
); err != nil {
return err
}
return app.RegisterNotFoundPage(errorspages.NotFound())
}
Reddedilen ilk değerde durur ve onun hatasını türü ve adıyla sarmalayarak döner (register page "post": collage: duplicate page ...). Böylece errors.Is asıl nedeni yine bulur. Ondan önce register edilenler, tekil metotlarda olduğu gibi register edilmiş olarak kalır. Bir nil, ErrNilRegistrable olur. Not-found ve error page'lerine bir path üzerinden değil, eşleşmenin başarısız olmasıyla ulaşılır. Bu yüzden onlar RegisterNotFoundPage ve RegisterErrorPage'i kullanmaya devam eder. Register bir collage.Registrable alır ve bunu yalnızca *Page, *Document ve *Action karşılar. collage add yazdığı şeyi bu çağrıya ekler.
Register edilen değer neden önemli
Register işlemi kendisine verilen page'i değiştirir. 3. adım page'in en dıştaki layout'unu, onun bu page'e ait ve bağlanmış bir kopyasıyla değiştirir. Render edilen şey, içinde zincirin geri kalanı ve içerik bulunan bu kopyadır. Aynı constructor tekrar çağrılarak oluşturulan bir page ise farklı bir değerdir. Onun layout'larının content slot'ları boştur. Aynı builder'da ikinci bir Build() da öyledir: her çağrı bağımsız bir kopya döner ve sonradan builder'a yapılan WithPath ikisine de ulaşmaz. Bir kez build edin ve *Page'i saklayın.
Bu yüzden o andan itibaren page, RegisterPage'e verdiğiniz değerin ta kendisidir. Bir page'e değer üzerinden başvuran her şey o değeri kullanmalıdır:
Error page'ler.
WithNotFoundPage(p), register edilmiş olan*collage.Pagedeğerinin ta kendisini göstermelidir. Aynı adla ayrıca oluşturulmuş bir pageErrUnregisteredErrorPageile reddedilir, çünkü o page layout'unu boş bir içeriğin etrafında render ederdi.Page ile cevap veren action'lar. Bir action'da
collage.RenderPage(p)'ye register edilmiş değer verilmelidir. Register edilmemiş bir değer boş render edilmez,ErrUnregisteredPageile reddedilir. Page'in kendi URL'sindeki bir action o değerirc.Pageolarak alır:return collage.NewPage("hello"). WithLayouts(layouts.Master()). WithContent(content). WithPath("en", "/hello"). WithAction("POST", func(_ context.Context, rc *collage.RenderContext) (*collage.ActionResult, error) { return collage.RenderPage(rc.Page), nil }). Build()rc.Pagede aynı değerdir. Bu değeri, page'i render eden bütün request'ler ve onlara hizmet eden bütün goroutine'ler ortak kullanır. Onu dilediğiniz gibi okuyun, ama hiçbir zaman ona yazmayın. Request'ten request'e değişen her şey, bir handler'ın döndüğü veride ya da bircollage.Keyaltında yer almalıdır. Ayrıntılar için Data handler'lar sayfasına bakın.
app.Page(name) ve app.Pages(), register edilmiş page'lerin kopyalarını döner. Bu kopyalar incelemek içindir: örneğin her page'in path'lerini listeleyen bir sitemap ya da bir stratejiyi kontrol eden bir test. Kopya, register edilmiş değer değildir. Bu yüzden register edilmiş bir page beklenen yere kopya vermeyin.
Örnek: private bir bölümü olan bir blog
Çok kullanıcılı bir blogda üç tür page vardır. Yazılar public'tir. Giriş yapmış her yazarın taslaklarını listeleyen bir hesap page'i vardır. Admin'lerin ayrıca kullanıcıları listeleyen bir page'i vardır. Üçü aynı iskeleti paylaşır; private olanlar, kimin girebileceğini söyleyen layout'ların içinde durur:
| Page | Path | Layout'lar, en dıştakinden başlayarak | Strateji |
|---|---|---|---|
post | /blog/{slug} | Master | Incremental(10 * time.Minute) |
account | /account | Master, Account | tanımlanmamış: data handler'ı olduğu için dynamic |
admin-users | /admin/users | Master, Account, Admin | tanımlanmamış: data handler'ı olduğu için dynamic |
not-found, error | path yok | Master | Dynamic() |
Guard'ları layout'lar taşır. Account, session plugin'ininRequireUserPage'ini kullanır. Bu guard, giriş yapmamış bir okuyucuyu gitmek istediği yeri next içinde taşıyarak login adlı page'e gönderir. Admin bir rolü kontrol eder. Rol, bu uygulamanın kendi login action'ının yazdığı "role" session key'inde durur; plugin yalnızca kullanıcı key'ini tanımlar.
// Master is the site's shell: <head>, header, footer.
func Master() *collage.Fragment {
return collage.NewFragment("layout", "layouts/master.html").
WithTitle("My blog").
Build()
}
// Account is the signed-in area. Its guard sends everyone else to log in.
func Account() *collage.Fragment {
return collage.NewFragment("account-layout", "layouts/account.html").
WithGuard(session.RequireUserPage("login")).
Build()
}
// Admin sits inside Account and lets only admins through.
func Admin() *collage.Fragment {
menu := collage.NewFragment("admin-menu", "fragments/admin-menu.html").Build()
return collage.NewFragment("admin-layout", "layouts/admin.html").
WithGuard(requireRole("admin")).
WithSlotFragment("menu", menu).
Build()
}
// requireRole lets through a reader whose session holds role under "role",
// which the login action sets. Anyone else gets a bare 403.
func requireRole(role string) collage.GuardFunc {
return func(ctx context.Context, _ *http.Request) (*collage.GuardDecision, error) {
if session.FromContext(ctx).Get("role") == role {
return nil, nil
}
return &collage.GuardDecision{Status: http.StatusForbidden}, nil
}
}
Admin layout'u iki slot'unu da çağırır: yukarıda bağlanan menu'yü ve register işleminin doldurduğu content'i. layouts/account.html de aynıdır, yalnızca content'i çağırır.
<!-- templates/layouts/admin.html -->
<div class="admin">
<nav>{{slot "menu"}}</nav>
<main>{{slot "content"}}</main>
</div>
Bir page'in public ya da private olması yalnızca listelediği layout'lara bağlıdır:
// Post is public and cached; an unknown slug is a 404.
func Post() *collage.Page {
content := collage.NewFragment("post", "pages/post.html").
WithData(collage.LoadTagged(func(ctx context.Context, rc *collage.RenderContext) (store.Post, []string, error) {
slug := rc.Param("slug")
// PostBySlug wraps collage.ErrNotFound for a slug it does not know.
post, err := store.PostBySlug(ctx, slug)
return post, []string{"post:" + slug}, err
})).
Required().
Build()
return collage.NewPage("post").
WithLayouts(layouts.Master()).
WithContent(content).
WithPath("en", "/blog/{slug}").
Incremental(10 * time.Minute).
Build()
}
// Account lists the signed-in reader's drafts.
func Account() *collage.Page {
content := collage.NewFragment("account", "pages/account.html").
WithData(collage.Load(func(ctx context.Context, rc *collage.RenderContext) ([]store.Draft, error) {
return store.Drafts(ctx, session.Get(rc).Get(session.UserKey))
})).
Build()
return collage.NewPage("account").
WithLayouts(layouts.Master(), layouts.Account()).
WithContent(content).
WithPath("en", "/account").
Build()
}
// AdminUsers is for admins only: it sits in both guarded layouts.
func AdminUsers() *collage.Page {
content := collage.NewFragment("admin-users", "pages/admin-users.html").
WithData(collage.Load(func(ctx context.Context, _ *collage.RenderContext) ([]store.User, error) {
return store.Users(ctx)
})).
Build()
return collage.NewPage("admin-users").
WithLayouts(layouts.Master(), layouts.Account(), layouts.Admin()).
WithContent(content).
WithPath("en", "/admin/users").
Build()
}
// NotFound and Error wrap the shell alone, so they look like the public site.
func NotFound() *collage.Page {
content := collage.NewFragment("not-found-content", "pages/404.html").Build()
return collage.NewPage("not-found").
WithLayouts(layouts.Master()).
WithContent(content).
Dynamic().
Build()
}
func Error() *collage.Page {
content := collage.NewFragment("error-content", "pages/500.html").Build()
return collage.NewPage("error").
WithLayouts(layouts.Master()).
WithContent(content).
Dynamic().
Build()
}
func register(app *collage.App) error {
if err := app.Register(
pages.Post(),
pages.Account(),
pages.AdminUsers(),
); err != nil {
return err
}
if err := app.RegisterNotFoundPage(pages.NotFound()); err != nil {
return err
}
return app.RegisterErrorPage(pages.Error())
}
Her okuyucunun aldığı cevap:
| Request | Okuyucu | Cevap |
|---|---|---|
/blog/hello | giriş yapmamış | Yazı; cache açıksa on dakika geçene kadar cache'ten |
/blog/hello | giriş yapmış | Yazı, yeniden render edilir: session plugin'i session'ı olan okuyucu için cache'i atlar |
/blog/no-such-post | herkes | 404 ve sitenin not-found page'i, iskeletin içinde |
/account | giriş yapmamış | /login?next=%2Faccount'a 303 |
/admin/users | giriş yapmamış | /login?next=%2Fadmin%2Fusers'a 303: önce account guard'ı cevap verir, rol hiç kontrol edilmez |
/admin/users | giriş yapmış, admin değil | Body'siz bir 403 |
/admin/users | bir admin | Page |
Yukarıdaki kurallardan birkaç sonuç çıkar:
- Private path listesi yoktur.
/adminaltındaki yeni bir page, path'inin nasıl başladığı yüzünden değil,layouts.Admin()'i listelediği için private'tır. Bunu unutan bir page public'tir. Bu yüzdencollage inspect'e bakmaya değer: her page için guard taşıyan fragment'leri listeler. - Admin menüsünün guard'ı sorulmazdı. Menü bir slot'a bağlıdır, omurgada değildir. Bölümü korumak admin layout'unun işidir.
- Private page'ler ortak cache'lere girmez. Account ve admin page'leri
Cache-Control: private, no-cacheile,303ve403iseno-storeile gönderilir. Static export da iki page'i de yazmaz. - Error page'ler herkes için render edilir. Yalnızca
Master()'ı sararlar ve başarısız olan page'in guard'ları onlar için sorulmaz. Böylece hatayla karşılaşan bir okuyucu, hatayı görmek yerine giriş yapmaya yönlendirilmez.