tpl2x

package module
v0.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 1, 2019 License: MIT Imports: 7 Imported by: 0

README

tpl2x

golang template engine which renders templates by executing them 2 times, one for content and another one for layout

GoDoc codecov Build Status GoCard GitHub Release GitHub code size in bytes GitHub license

  • Project status: MVP is ready
  • Future plans: tests & docs

This package offers 2-step template processing, where page content template called first, so it can

  1. change page layout (among them previous markup) and content type
  2. abort processing and return error page (this will render layout with error and without content)
  3. abort processing and return redirect

If page content template returns HTML, at step 2, layout template will be called for result page markup build.

Why do we need another template engine?

  1. Adding template file without source recompiling
  2. Support plain HTML body as template (adding layout without additional markup in content)
  3. Attach all (pages,layouts,includes) templates at start (see lookupfs)
  4. Auto create routes for all page templates allowing them get required data via api (see gin-tpl2x)

Request processing flow

Request processing flow

Template structure

As shown in testdata, site templates tree might looks like:

tmpl
├── includes
│   ├── inc.html
│   └── subdir1
│       └── inc.html
├── layouts
│   ├── default.html
│   └── subdir2
│       └── lay.html
└── pages
    ├── page.html
    └── subdir3
        └── page.html

Usage

Template parsing

All templates from the Root directory tree are parsed in Parse() call and program should be aborted on error. Routes for all page URI should be set in Route() call after that.

You can enable per request templates parsing for debugging purposes via ParseAlways(true) but you still have to restart your program for adding or removing any template file.

See also
Template methods

Get http.Request data

{{ request.Host }}{{ request.URL.String | HTML }}

Get query params

{{ $param := .Request.URL.Query.Get "param" -}}

Set page title

{{ .SetTitle "admin:index" -}}

Choose layout

{{ .SetLayout "wide" -}}

Stop template processing and raise error

{{ .Raise 403 true "Error description" }}

Stop template processing and return redirect

{{ .RedirectFound "/page" }}
Custom methods

in code

reqFuncs["data"] = func() interface{} {
    return data
}
p, err := mlt.RenderPage(uri, reqFuncs, r)

in templates

{{range data.Todos -}}
    <li>{{- .Title }}
{{end -}}

See also

License

The MIT License (MIT), see LICENSE.

Copyright (c) 2018 Aleksei Kovrizhkin lekovr+apisite@gmail.com

Documentation

Overview

Package tpl2x implements template engine which renders templates by executing them 2 times, one for content and another one for layout.

Example (Execute)

Render template with layout 

package main

import (
	"bytes"
	"html/template"
	"log"
	"os"

	"github.com/apisite/tpl2x"
	"github.com/apisite/tpl2x/lookupfs"

	"github.com/apisite/tpl2x/samplefs"
	"github.com/apisite/tpl2x/samplemeta"
)

func main() {

	// BufferPool size for rendered templates
	const bufferSize int = 64

	cfg := lookupfs.Config{
		Includes:  "inc_minimal",
		Layouts:   "layouts",
		Pages:     "pages",
		Ext:       ".html",
		DefLayout: "default",
	}

	tfs, err := tpl2x.New(bufferSize).
		LookupFS(lookupfs.New(cfg).
			FileSystem(samplefs.FS())).
		Parse()
	if err != nil {
		log.Fatal(err)
	}
	var b bytes.Buffer
	page := &samplemeta.Meta{}
	page.SetLayout("default")
	err = tfs.Execute(&b, "subdir3/page", template.FuncMap{}, page)
	if err != nil {
		log.Fatal(err)
	}
	_, err = b.WriteTo(os.Stdout)
	if err != nil {
		log.Fatal(err)
	}

}

Output:

<title>Template title</title>
==
page2 here (inc2 here)==inc1
Example (Http)

Handle set of templates via http 

package main

import (
	"fmt"
	"html/template"
	"log"
	"net/http"
	"net/http/httptest"

	"github.com/apisite/tpl2x"
	"github.com/apisite/tpl2x/lookupfs"

	"github.com/apisite/tpl2x/samplefs"
	"github.com/apisite/tpl2x/samplemeta"
)

// Handle set of templates via http
func main() {

	// BufferPool size for rendered templates
	const bufferSize int = 64

	cfg := lookupfs.Config{
		Includes:  "includes",
		Layouts:   "layouts",
		Pages:     "pages",
		Ext:       ".html",
		DefLayout: "default",
	}

	funcs := template.FuncMap{
		"request": func() http.Request {
			return http.Request{}
		},
		"content": func() template.HTML { return template.HTML("") },
	}

	tfs, err := tpl2x.New(bufferSize).
		Funcs(funcs).
		LookupFS(
			lookupfs.New(cfg).
				FileSystem(samplefs.FS())).
		ParseAlways(true).
		Parse()
	if err != nil {
		log.Fatal(err)
	}

	router := http.NewServeMux()
	for _, uri := range tfs.PageNames(false) {
		router.HandleFunc("/"+uri, handleHTML(tfs, uri))
	}

	resp := httptest.NewRecorder()
	req, err := http.NewRequest("GET", "/subdir3/page", nil)
	if err != nil {
		log.Fatal(err)
	}
	router.ServeHTTP(resp, req)

	fmt.Println(resp.Code)
	fmt.Println(resp.Header().Get("Content-Type"))
	fmt.Println(resp.Body.String())

}

// handleHTML returns page handler
func handleHTML(tfs *tpl2x.TemplateService, uri string) func(w http.ResponseWriter, r *http.Request) {
	return func(w http.ResponseWriter, r *http.Request) {
		//		log.Debugf("Handling page (%s)", uri)

		page := samplemeta.NewMeta(http.StatusOK, "text/html; charset=utf-8")
		funcs := template.FuncMap{
			"request": func() http.Request {
				return *r
			},
		}
		content := tfs.RenderContent(uri, funcs, page)
		if page.Status() == http.StatusMovedPermanently || page.Status() == http.StatusFound {
			http.Redirect(w, r, page.Title, page.Status())
			return
		}
		header := w.Header()
		header["Content-Type"] = []string{page.ContentType()}
		w.WriteHeader(page.Status())
		funcs["content"] = func() template.HTML { return template.HTML(content.Bytes()) }

		err := tfs.Render(w, funcs, page, content)
		if err != nil {
			log.Fatal(err)
		}

	}
}

Output:

200
text/html; charset=utf-8
<title>Template title</title>
==
page2 here (inc2 here)==inc1 (URI: /subdir3/page)

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type MetaData 

type MetaData interface {
	Error() error   // Template exec error
	SetError(error) // Store unhandler template error
	Layout() string // Return layout name
}

MetaData holds template metadata access methods

type TemplateService 

type TemplateService struct {
	// contains filtered or unexported fields
}

TemplateService holds templates data & methods

func New 

func New(size int) (tfs *TemplateService)

New creates TemplateService with BufferPool of given size

func (TemplateService) Execute 

func (tfs TemplateService) Execute(wr io.Writer, name string, funcs template.FuncMap, data MetaData) error

Execute renders page content and layout

func (*TemplateService) Funcs 

func (tfs *TemplateService) Funcs(funcMap template.FuncMap) *TemplateService

Funcs loads initial funcmap

func (*TemplateService) LookupFS 

func (tfs *TemplateService) LookupFS(fs *lookupfs.LookupFileSystem) *TemplateService

LookupFS sets lookup filesystem

func (TemplateService) PageNames 

func (tfs TemplateService) PageNames(hide bool) []string

PageNames returns page names for router setup

func (*TemplateService) Parse 

func (tfs *TemplateService) Parse() (*TemplateService, error)

Parse parses all of service templates

func (*TemplateService) ParseAlways 

func (tfs *TemplateService) ParseAlways(flag bool) *TemplateService

ParseAlways disables template caching

func (TemplateService) Render 

func (tfs TemplateService) Render(w io.Writer, funcs template.FuncMap, data MetaData, content *bytes.Buffer) (err error)

Render renders layout with prepared content

func (TemplateService) RenderContent 

func (tfs TemplateService) RenderContent(name string, funcs template.FuncMap, data MetaData) *bytes.Buffer

RenderContent renders page content

Source Files

View all Source files

Directories

Path Synopsis
gin-tpl2x module
Package lookupfs implements a filesystem backend for tpl2x.
 Package lookupfs implements a filesystem backend for tpl2x.
Package samplefs contains embedded resources Package samplefs implements a sample embedded template filesystem for tests and examples for tpl2x.
 Package samplefs contains embedded resources Package samplefs implements a sample embedded template filesystem for tests and examples for tpl2x.
Package samplemeta implements sample type Meta which holds template metadata
 Package samplemeta implements sample type Meta which holds template metadata

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.