diff --git a/template_versioned_docs/version-django_v3.x.x/README.md b/template_versioned_docs/version-django_v3.x.x/README.md new file mode 100644 index 00000000000..f7bbaffc78a --- /dev/null +++ b/template_versioned_docs/version-django_v3.x.x/README.md @@ -0,0 +1,243 @@ +--- +title: 👋 Welcome +description: 🧬 Template engine middlewares for Fiber. +sidebar_position: 1 +--- + + +

+ Fiber + Fiber +
+ + + + + + + + + + +

+ +This package provides universal methods to use multiple template engines with the [Fiber web framework](https://github.com/gofiber/fiber) using the new [Views](https://godoc.org/github.com/gofiber/fiber#Views) interface that is available from `> v1.11.1`. Special thanks to @bdtomlin & @arsmn for helping! + +9 template engines are supported: +- [ace](./ace/README.md) +- [amber](./amber/README.md) +- [django](./django/README.md) +- [handlebars](./handlebars/README.md) +- [html](./html/README.md) +- [jet](./jet/README.md) +- [mustache](./mustache/README.md) +- [pug](./pug/README.md) +- [slim](./slim/README.md) + +### Installation +> Go version `1.17` or higher is required. + +``` +go get -u github.com/gofiber/fiber/v2 +go get -u github.com/gofiber/template/any_template_engine/vX +``` + +### Example +```go +package main + +import ( + "log" + + "github.com/gofiber/fiber/v2" + + // To use a specific template engine, import as shown below: + // "github.com/gofiber/template/pug" + // "github.com/gofiber/template/mustache" + // etc.. + + // In this example we use the html template engine + "github.com/gofiber/template/html/v2" +) + +func main() { + // Create a new engine by passing the template folder + // and template extension using .New(dir, ext string) + engine := html.New("./views", ".html") + + // We also support the http.FileSystem interface + // See examples below to load templates from embedded files + engine := html.NewFileSystem(http.Dir("./views"), ".html") + + // Reload the templates on each render, good for development + engine.Reload(true) // Optional. Default: false + + // Debug will print each template that is parsed, good for debugging + engine.Debug(true) // Optional. Default: false + + // Layout defines the variable name that is used to yield templates within layouts + engine.Layout("embed") // Optional. Default: "embed" + + // Delims sets the action delimiters to the specified strings + engine.Delims("{{", "}}") // Optional. Default: engine delimiters + + // AddFunc adds a function to the template's global function map. + engine.AddFunc("greet", func(name string) string { + return "Hello, " + name + "!" + }) + + // After you created your engine, you can pass it to Fiber's Views Engine + app := fiber.New(fiber.Config{ + Views: engine, + }) + + // To render a template, you can call the ctx.Render function + // Render(tmpl string, values interface{}, layout ...string) + app.Get("/", func(c *fiber.Ctx) error { + return c.Render("index", fiber.Map{ + "Title": "Hello, World!", + }) + }) + + // Render with layout example + app.Get("/layout", func(c *fiber.Ctx) error { + return c.Render("index", fiber.Map{ + "Title": "Hello, World!", + }, "layouts/main") + }) + + log.Fatal(app.Listen(":3000")) +} + +``` + +### More Examples + +To view more specific examples, you could visit each engine folder to learn more +- [ace](./ace/README.md) +- [amber](./amber/README.md) +- [django](./django/README.md) +- [handlebars](./handlebars/README.md) +- [html](./html/README.md) +- [jet](./jet/README.md) +- [mustache](./mustache/README.md) +- [pug](./pug/README.md) +- [slim](./slim/README.md) + + +### embedded Systems + +We support the `http.FileSystem` interface, so you can use different libraries to load the templates from embedded binaries. + +#### pkger +Read documentation: https://github.com/markbates/pkger + +```go +package main + +import ( + "log" + + "github.com/gofiber/fiber/v2" + "github.com/gofiber/template/html" + + "github.com/markbates/pkger" +) + +func main() { + engine := html.NewFileSystem(pkger.Dir("/views"), ".html") + + app := fiber.New(fiber.Config{ + Views: engine, + }) + + // run pkger && go build +} +``` +#### packr +Read documentation: https://github.com/gobuffalo/packr + +```go +package main + +import ( + "log" + + "github.com/gofiber/fiber/v2" + "github.com/gofiber/template/html" + + "github.com/gobuffalo/packr/v2" +) + +func main() { + engine := html.NewFileSystem(packr.New("Templates", "/views"), ".html") + + app := fiber.New(fiber.Config{ + Views: engine, + }) + + // run packr && go build +} +``` +#### go.rice +Read documentation: https://github.com/GeertJohan/go.rice + +```go +package main + +import ( + "log" + + "github.com/gofiber/fiber/v2" + "github.com/gofiber/template/html" + + "github.com/GeertJohan/go.rice" +) + +func main() { + engine := html.NewFileSystem(rice.MustFindBox("views").HTTPBox(), ".html") + + app := fiber.New(fiber.Config{ + Views: engine, + }) + + // run rice embed-go && go build +} + +``` +#### fileb0x +Read documentation: https://github.com/UnnoTed/fileb0x + +```go +package main + +import ( + "log" + + "github.com/gofiber/fiber/v2" + "github.com/gofiber/template/html" + // your generated package + "github.com///static" +) + +func main() { + engine := html.NewFileSystem(static.HTTP, ".html") + + app := fiber.New(fiber.Config{ + Views: engine, + }) + + // Read the documentation on how to use fileb0x +} +``` + + +### Benchmarks + +#### Simple +![](https://raw.githubusercontent.com/gofiber/template/master/.github/data/Simple-TimeperOperation.png) + +#### Extended +![](https://raw.githubusercontent.com/gofiber/template/master/.github/data/Extended-TimeperOperation.png) + +Benchmarks were ran on Apple Macbook M1. Each engine was benchmarked 20 times and the results averaged into a single xlsx file. Mustache was excluded from the extended benchmark diff --git a/template_versioned_docs/version-django_v3.x.x/ace/README.md b/template_versioned_docs/version-django_v3.x.x/ace/README.md new file mode 100644 index 00000000000..84e2eaa5d91 --- /dev/null +++ b/template_versioned_docs/version-django_v3.x.x/ace/README.md @@ -0,0 +1,82 @@ +--- +id: ace +title: Ace +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/template?filter=ace*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://github.com/gofiber/template/workflows/Tests/badge.svg) +![Security](https://github.com/gofiber/template/workflows/Security/badge.svg) +![Linter](https://github.com/gofiber/template/workflows/Linter/badge.svg) + +Ace is a template engine create by [yossi](https://github.com/yosssi/ace), to see the original syntax documentation please [click here](https://github.com/yosssi/ace/blob/master/documentation/syntax.md) + +### Basic Example + +_**./views/index.ace**_ +```html += include ./views/partials/header . + +h1 {{.Title}} + += include ./views/partials/footer . +``` +_**./views/partials/header.ace**_ +```html +h1 Header +``` +_**./views/partials/footer.ace**_ +```html +h1 Footer +``` +_**./views/layouts/main.ace**_ +```html += doctype html +html + head + title Main + body + {{embed}} +``` + +```go +package main + +import ( + "log" + + "github.com/gofiber/fiber/v2" + "github.com/gofiber/template/ace/v2" +) + +func main() { + // Create a new engine + engine := ace.New("./views", ".ace") + + // Or from an embedded system + // See github.com/gofiber/embed for examples + // engine := html.NewFileSystem(http.Dir("./views", ".ace")) + + // Pass the engine to the Views + app := fiber.New(fiber.Config{ + Views: engine, + }) + + app.Get("/", func(c *fiber.Ctx) error { + // Render index + return c.Render("index", fiber.Map{ + "Title": "Hello, World!", + }) + }) + + app.Get("/layout", func(c *fiber.Ctx) error { + // Render index within layouts/main + return c.Render("index", fiber.Map{ + "Title": "Hello, World!", + }, "layouts/main") + }) + + log.Fatal(app.Listen(":3000")) +} + +``` diff --git a/template_versioned_docs/version-django_v3.x.x/amber/README.md b/template_versioned_docs/version-django_v3.x.x/amber/README.md new file mode 100644 index 00000000000..e3035984822 --- /dev/null +++ b/template_versioned_docs/version-django_v3.x.x/amber/README.md @@ -0,0 +1,82 @@ +--- +id: amber +title: Amber +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/template?filter=amber*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://github.com/gofiber/template/workflows/Tests/badge.svg) +![Security](https://github.com/gofiber/template/workflows/Security/badge.svg) +![Linter](https://github.com/gofiber/template/workflows/Linter/badge.svg) + +Amber is a template engine create by [eknkc](https://github.com/eknkc/amber), to see the original syntax documentation please [click here](https://github.com/eknkc/amber#tags) + +### Basic Example + +_**./views/index.amber**_ +```html +import ./views/partials/header + +h1 #{Title} + +import ./views/partials/footer +``` +_**./views/partials/header.amber**_ +```html +h1 Header +``` +_**./views/partials/footer.amber**_ +```html +h1 Footer +``` +_**./views/layouts/main.amber**_ +```html +doctype html +html + head + title Main + body + #{embed()} +``` + +```go +package main + +import ( + "log" + + "github.com/gofiber/fiber/v2" + "github.com/gofiber/template/amber/v2" +) + +func main() { + // Create a new engine + engine := amber.New("./views", ".amber") + + // Or from an embedded system + // See github.com/gofiber/embed for examples + // engine := html.NewFileSystem(http.Dir("./views", ".amber")) + + // Pass the engine to the Views + app := fiber.New(fiber.Config{ + Views: engine, + }) + + app.Get("/", func(c *fiber.Ctx) error { + // Render index + return c.Render("index", fiber.Map{ + "Title": "Hello, World!", + }) + }) + + app.Get("/layout", func(c *fiber.Ctx) error { + // Render index within layouts/main + return c.Render("index", fiber.Map{ + "Title": "Hello, World!", + }, "layouts/main") + }) + + log.Fatal(app.Listen(":3000")) +} + +``` diff --git a/template_versioned_docs/version-django_v3.x.x/django/README.md b/template_versioned_docs/version-django_v3.x.x/django/README.md new file mode 100644 index 00000000000..c8f33e726cf --- /dev/null +++ b/template_versioned_docs/version-django_v3.x.x/django/README.md @@ -0,0 +1,183 @@ +--- +id: django +title: Django +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/template?filter=django*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://github.com/gofiber/template/workflows/Tests/badge.svg) +![Security](https://github.com/gofiber/template/workflows/Security/badge.svg) +![Linter](https://github.com/gofiber/template/workflows/Linter/badge.svg) + +Django is a template engine create by [flosch](https://github.com/flosch/pongo2), to see the original syntax documentation please [click here](https://docs.djangoproject.com/en/dev/topics/templates/) + +### Basic Example + +_**./views/index.django**_ +```html +{% include "partials/header.django" %} + +

{{ Title }}

+ +{% include "partials/footer.django" %} +``` +_**./views/partials/header.django**_ +```html +

Header

+``` +_**./views/partials/footer.django**_ +```html +

Footer

+``` +_**./views/layouts/main.django**_ +```html + + + + + Main + + + + {{embed}} + + + +``` + +```go +package main + +import ( + "log" + + "github.com/gofiber/fiber/v2" + "github.com/gofiber/template/django/v3" +) + +func main() { + // Create a new engine + engine := django.New("./views", ".django") + + // Or from an embedded system + // See github.com/gofiber/embed for examples + // engine := html.NewFileSystem(http.Dir("./views", ".django")) + + // Pass the engine to the Views + app := fiber.New(fiber.Config{ + Views: engine, + }) + + app.Get("/", func(c *fiber.Ctx) error { + // Render index + return c.Render("index", fiber.Map{ + "Title": "Hello, World!", + }) + }) + + app.Get("/layout", func(c *fiber.Ctx) error { + // Render index within layouts/main + return c.Render("index", fiber.Map{ + "Title": "Hello, World!", + }, "layouts/main") + }) + + log.Fatal(app.Listen(":3000")) +} + +``` +### Using embedded file system (1.16+ only) + +When using the `// go:embed` directive, resolution of inherited templates using django's `{% extend '' %}` keyword fails when instantiating the template engine with `django.NewFileSystem()`. In that case, use the `django.NewPathForwardingFileSystem()` function to instantiate the template engine. + +This function provides the proper configuration for resolving inherited templates. + +Assume you have the following files: + +- [views/ancenstor.django](https://github.com/gofiber/template/blob/master/django/views/ancestor.django) +- [views/descendant.djando](https://github.com/gofiber/template/blob/master/django/views/descendant.django) + +then + +```go +package main + +import ( + "log" + "embed" + "net/http" + + "github.com/gofiber/fiber/v2" + "github.com/gofiber/template/django/v3" +) + +//go:embed views +var viewsAsssets embed.FS + +func main() { + // Create a new engine + engine := NewPathForwardingFileSystem(http.FS(viewsAsssets), "/views", ".django") + + // Pass the engine to the Views + app := fiber.New(fiber.Config{ + Views: engine, + }) + + app.Get("/", func(c *fiber.Ctx) error { + // Render descendant + return c.Render("descendant", fiber.Map{ + "greeting": "World", + }) + }) + + log.Fatal(app.Listen(":3000")) +} + +``` + +### Register and use custom functions +```go +// My custom function +func Nl2brHtml(value interface{}) string { + if str, ok := value.(string); ok { + return strings.Replace(str, "\n", "
", -1) + } + return "" +} + +// Create a new engine +engine := django.New("./views", ".django") + +// register functions +engine.AddFunc("nl2br", Nl2brHtml) + +// Pass the engine to the Views +app := fiber.New(fiber.Config{Views: engine}) +``` +_**in the handler**_ +```go +c.Render("index", fiber.Map{ + "Fiber": "Hello, World!\n\nGreetings from Fiber Team", +}) +``` + +_**./views/index.django**_ +```html + + + + +{{ nl2br(Fiber) }} + + +``` +**Output:** +```html + + + + +Hello, World!

Greetings from Fiber Team + + +``` diff --git a/template_versioned_docs/version-django_v3.x.x/handlebars/README.md b/template_versioned_docs/version-django_v3.x.x/handlebars/README.md new file mode 100644 index 00000000000..c2b3ee8ae9d --- /dev/null +++ b/template_versioned_docs/version-django_v3.x.x/handlebars/README.md @@ -0,0 +1,88 @@ +--- +id: handlebars +title: Handlebars +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/template?filter=django*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://github.com/gofiber/template/workflows/Tests/badge.svg) +![Security](https://github.com/gofiber/template/workflows/Security/badge.svg) +![Linter](https://github.com/gofiber/template/workflows/Linter/badge.svg) + +Handlebars is a template engine create by [aymerick](https://github.com/aymerick/raymond), to see the original syntax documentation please [click here](https://github.com/aymerick/raymond#table-of-contents) + +### Basic Example + +_**./views/index.hbs**_ +```html +{{> 'partials/header' }} + +

{{Title}}

+ +{{> 'partials/footer' }} +``` +_**./views/partials/header.hbs**_ +```html +

Header

+``` +_**./views/partials/footer.hbs**_ +```html +

Footer

+``` +_**./views/layouts/main.hbs**_ +```html + + + + + Main + + + + {{embed}} + + + +``` + +```go +package main + +import ( + "log" + + "github.com/gofiber/fiber/v2" + "github.com/gofiber/template/handlebars/v2" +) + +func main() { + // Create a new engine + engine := handlebars.New("./views", ".hbs") + + // Or from an embedded system + // See github.com/gofiber/embed for examples + // engine := html.NewFileSystem(http.Dir("./views", ".hbs")) + + // Pass the engine to the Views + app := fiber.New(fiber.Config{ + Views: engine, + }) + + app.Get("/", func(c *fiber.Ctx) error { + // Render index + return c.Render("index", fiber.Map{ + "Title": "Hello, World!", + }) + }) + + app.Get("/layout", func(c *fiber.Ctx) error { + // Render index within layouts/main + return c.Render("index", fiber.Map{ + "Title": "Hello, World!", + }, "layouts/main") + }) + + log.Fatal(app.Listen(":3000")) +} + +``` diff --git a/template_versioned_docs/version-django_v3.x.x/html/README.md b/template_versioned_docs/version-django_v3.x.x/html/README.md new file mode 100644 index 00000000000..e4e65d5f61b --- /dev/null +++ b/template_versioned_docs/version-django_v3.x.x/html/README.md @@ -0,0 +1,203 @@ +--- +id: html +title: HTML +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/template?filter=django*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://github.com/gofiber/template/workflows/Tests/badge.svg) +![Security](https://github.com/gofiber/template/workflows/Security/badge.svg) +![Linter](https://github.com/gofiber/template/workflows/Linter/badge.svg) + +HTML is the official Go template engine [html/template](https://golang.org/pkg/html/template/), to see the original syntax documentation please [click here](TEMPLATES_CHEATSHEET.md) + +**Info:** + +All templates within the specified view directory are analyzed and compiled at the beginning to increase the performance when using them. +Thus it should be noted that no `definition` with the same name should exist, otherwise they will overwrite each other. +For templating the `{{embed}}` tag should be used + +### Basic Example + +_**./views/index.html**_ + +```html +{{template "partials/header" .}} + +

{{.Title}}

+ +{{template "partials/footer" .}} +``` + +_**./views/partials/header.html**_ + +```html +

Header

+``` + +_**./views/partials/footer.html**_ + +```html +

Footer

+``` + +_**./views/layouts/main.html**_ + +```html + + + + Main + + + + {{embed}} + + +``` + +```go +package main + +import ( + "log" + + "github.com/gofiber/fiber/v2" + "github.com/gofiber/template/html/v2" +) + +func main() { + // Create a new engine + engine := html.New("./views", ".html") + + // Or from an embedded system + // See github.com/gofiber/embed for examples + // engine := html.NewFileSystem(http.Dir("./views", ".html")) + + // Pass the engine to the Views + app := fiber.New(fiber.Config{ + Views: engine, + }) + + app.Get("/", func(c *fiber.Ctx) error { + // Render index + return c.Render("index", fiber.Map{ + "Title": "Hello, World!", + }) + }) + + app.Get("/layout", func(c *fiber.Ctx) error { + // Render index within layouts/main + return c.Render("index", fiber.Map{ + "Title": "Hello, World!", + }, "layouts/main") + }) + + log.Fatal(app.Listen(":3000")) +} + +``` + +### Example with embed.FS + +```go +package main + +import ( + "log" + "net/http" + "embed" + + "github.com/gofiber/fiber/v2" + "github.com/gofiber/template/html" +) + +//go:embed views/* +var viewsfs embed.FS + +func main() { + engine := html.NewFileSystem(http.FS(viewsfs), ".html") + + // Pass the engine to the Views + app := fiber.New(fiber.Config{ + Views: engine, + }) + + + app.Get("/", func(c *fiber.Ctx) error { + // Render index - start with views directory + return c.Render("views/index", fiber.Map{ + "Title": "Hello, World!", + }) + }) + + log.Fatal(app.Listen(":3000")) +} +``` + +and change the starting point to the views directory + +_**./views/index.html**_ + +```html +{{template "views/partials/header" .}} + +

{{.Title}}

+ +{{template "views/partials/footer" .}} +``` + +### Example with innerHTML + +```go +package main + +import ( + "embed" + "html/template" + "log" + "net/http" + + "github.com/gofiber/fiber/v2" + "github.com/gofiber/template/html" +) + +//go:embed views/* +var viewsfs embed.FS + +func main() { + engine := html.NewFileSystem(http.FS(viewsfs), ".html") + engine.AddFunc( + // add unescape function + "unescape", func(s string) template.HTML { + return template.HTML(s) + }, + ) + + // Pass the engine to the Views + app := fiber.New(fiber.Config{Views: engine}) + + app.Get("/", func(c *fiber.Ctx) error { + // Render index + return c.Render("views/index", fiber.Map{ + "Title": "Hello, World!", + }) + }) + + log.Fatal(app.Listen(":3000")) +} +``` + +and change the starting point to the views directory + +_**./views/index.html**_ + +```html +

{{ unescape .Title}}

+``` + +**html output** + +```html +

Hello, World!

+``` diff --git a/template_versioned_docs/version-django_v3.x.x/html/TEMPLATES_CHEATSHEET.md b/template_versioned_docs/version-django_v3.x.x/html/TEMPLATES_CHEATSHEET.md new file mode 100644 index 00000000000..f5ec54c7086 --- /dev/null +++ b/template_versioned_docs/version-django_v3.x.x/html/TEMPLATES_CHEATSHEET.md @@ -0,0 +1,582 @@ +# Golang Templates Cheatsheet + +The Go standard library provides a set of packages to generate output. The [text/template](https://archive.is/o/2HksZ/https://golang.org/pkg/text/template/) package implements templates for generating text output, while the [html/template](https://archive.is/o/2HksZ/https://golang.org/pkg/html/template/) package implements templates for generating HTML output that is safe against certain attacks. Both packages use the same interface but the following examples of the core features are directed towards HTML applications. + +--- + +## Table of Contents + +- [Parsing and Creating Templates](#parsing-and-creating-templates) +- [Executing Templates](#executing-templates) +- [Template Encoding and HTML](#template-encoding-and-html) +- [Template Variables](#template-variables) +- [Template Actions](#template-actions) +- [Template Functions](#template-functions) +- [Template Comparison Functions](#template-comparison-functions) +- [Nested Templates and Layouts](#nested-templates-and-layouts) +- [Templates Calling Functions](#templates-calling-functions) + +--- + +## Parsing and Creating Templates + +#### Naming Templates + +There is no defined file extension for Go templates. One of the most popular is `.tmpl` supported by vim-go and [referenced in the text/template godocs](https://archive.is/o/2HksZ/golang.org/pkg/text/template/%23example_Template_helpers). The extension `.gohtml` supports syntax highlighting in both Atom and GoSublime editors. Finally analysis of large Go codebases finds that `.tpl` is often used by developers. While the extension is not important it is still good to be consistent within a project for clarity. + +--- + +#### Creating a Template + +`tpl, err := template.Parse(filename)` will get the template at filename and store it in tpl. tpl can then be executed to show the template. + +--- + +#### Parsing Multiple Templates + +`template.ParseFiles(filenames)` takes a list of filenames and stores all templates. `template.ParseGlob(pattern)` will find all templates matching the pattern and store the templates. + +--- + +## Executing Templates + +#### Execute a Single Template + +Once a template has been parsed there are two options to execute them. A single template `tpl` can be executed using `tpl.Execute(io.Writer, data)`. The content of tpl will be written to the io.Writer. Data is an interface passed to the template that will be useable in the template. + +--- + +#### Executing a Named Template + +`tpl.ExecuteTemplate(io.Writer, name, data)` works the same as execute but allows for a string name of the template the user wants to execute. + +--- + +## Template Encoding and HTML + +#### Contextual Encoding + +Go’s html/template package does encoding based on the context of the code. As a result, html/template encodes any characters that need encoding to be rendered correctly. + +For example the < and > in `"

A header!

"` will be encoded as `<h1>A header!</h1>` . + +Type `template.HTML` can be used to skip encoding by telling Go the string is safe. `template.HTML("

A Safe header

")` will then be `

A Safe header

` . Using this type with user input is dangerous and leaves the application vulnerable. + +The go `html/template` package is aware of attributes within the template and will encode values differently based on the attribute. + +Go templates can also be used with javascript. Structs and maps will be expanded into JSON objects and quotes will be added to strings for use in function parameters and as variable values. + +```go + // Go + type Cat struct { + Name string + Age int + } + + kitten := Cat{"Sam", 12} +``` + +```html +// Template + +``` + +```js + // Javascript + var cat = {"Name":"Sam", "Age" 12} +``` + +--- + +#### Safe Strings and HTML Comments + +The `html/template` package will remove any comments from a template by default. This can cause issues when comments are necessary such as detecting internet explorer. + +```html + +``` + +We can use the Custom Functions method (Globally) to create a function that returns html preserving comments. Define a function `htmlSafe` in the FuncMap of the template. + +```go + testTemplate, err = template.New("hello.gohtml").Funcs(template.FuncMap{ + "htmlSafe": func(html string) template.HTML { + return template.HTML(html) + }, + }).ParseFiles("hello.gohtml") +``` + +This function takes a string and produces the unaltered HTML code. This function can be used in a template like so to preserve the comments `` : + +```go + {{htmlSafe "" }} +``` + +--- + +## Template Variables + +#### The dot character (.) + +A template variable can be a boolean, string, character, integer, floating-point, imaginary, or complex constant in Go syntax. Data passed to the template can be accessed using dot `{{ . }}`. + +If the data is a complex type then it’s fields can be accessed using the dot with the field name `{{ .FieldName }}`. + +Dots can be chained together if the data contains multiple complex structures. `{{ .Struct.StructTwo.Field }}` + +--- + +#### Variables in Templates + +Data passed to the template can be saved in a variable and used throughout the template. `{{$number := .}}` We use the `$number` to create a variable then initialize it with the value passed to the template. To use the variable we call it in the template with `{{$number}}`. + +```go + {{$number := .}} +

It is day number {{$number}} of the month

+``` + +```go + var tpl *template.Template + + tpl = template.Must(template.ParseFiles("templateName")) + + err := tpl.ExecuteTemplate(os.Stdout, "templateName", 23) +``` + +In this example we pass 23 to the template and stored in the `$number` variable which can be used anywhere in the template + +--- + +## Template Actions + +#### If/Else Statements + +Go templates support if/else statements like many programming languages. We can use the if statement to check for values, if it doesn’t exist we can use an else value. The empty values are false, 0, any nil pointer or interface value, and any array, slice, map, or string of length zero. + +```html +

Hello, {{if .Name}} {{.Name}} {{else}} Anonymous {{end}}!

+``` + +If .Name exists then `Hello, Name` will be printed (replaced with the name value) otherwise it will print `Hello, Anonymous`. + +Templates also provide the else if statment `{{else if .Name2 }}` which can be used to evaluate other options after an if. + +--- + +#### Removing Whitespace + +Adding different values to a template can add various amounts of whitespace. We can either change our template to better handle it, by ignoring or minimizing effects, or we can use the minus sign `-` within out template. + +`

Hello, {{if .Name}} {{.Name}} {{- else}} Anonymous {{- end}}!

` + +Here we are telling the template to remove all spaces between the `Name` variable and whatever comes after it. We are doing the same with the end keyword. This allows us to have whitespace within the template for easier reading but remove it in production. + +--- + +#### Range Blocks + +Go templates have a `range` keyword to iterate over all objects in a structure. Suppose we had the Go structures: + +```go + type Item struct { + Name string + Price int + } + + type ViewData struct { + Name string + Items []Item + } +``` + +We have an Item, with a name and price, then a ViewData which is the structure sent to the template. Consider the template containing the following: + +```html +{{range .Items}} +
+

{{.Name}}

+ ${{.Price}} +
+{{end}} +``` + +For each Item in the range of Items (in the ViewData structure) get the Name and Price of that item and create html for each Item automatically. Within a range each Item becomes the `{{.}}` and the item properties therefore become `{{.Name}}` or `{{.Price}}` in this example. + +--- + +## Template Functions + +The template package provides a list of predefined global functions. Below are some of the most used. + +--- + +#### Indexing structures in Templates + +If the data passed to the template is a map, slice, or array it can be indexed from the template. We use `{{index x number}}` where index is the keyword, x is the data and number is a integer for the index value. If we had `{{index names 2}}` it is equivalent to `names[2]`. We can add more integers to index deeper into data. `{{index names 2 3 4}}` is equivalent to `names[2][3][4]`. + +```html + +

{{index .FavNums 2 }}

+ +``` + +```go + type person struct { + Name string + FavNums []int + } + + func main() { + + tpl := template.Must(template.ParseGlob("*.gohtml")) + tpl.Execute(os.Stdout, &person{"Curtis", []int{7, 11, 94}}) + } +``` + +This code example passes a person structure and gets the 3rd favourite number from the FavNums slice. + +--- + +#### The `and` Function + +The and function returns the boolean AND of its arguments by returning the first empty argument or the last argument. `and x y` behaves logically as `if x then y else x` . Consider the following go code + +```go + type User struct { + Admin bool + } + + type ViewData struct { + *User + } +``` + +Pass a ViewData with a User that has Admin set true to the following template + +```go + + {{if and .User .User.Admin}} + You are an admin user! + {{else}} + Access denied! + {{end}} +``` + +The result will be `You are an admin user!`. However if the ViewData did not include a \*User object or Admin was set as false then the result will be `Access denied!`. + +--- + +#### The `or` Function + +The or function operates similarly to the and function however will stop at the first true. `or x y` is equivalent to `if x then x else y` so y will never be evaluated if x is not empty. + +--- + +#### The `not` Function + +The not function returns the boolean negation of the argument. + +```go + {{ if not .Authenticated}} + Access Denied! + {{ end }} +``` + +--- + +## Template Comparison Functions + +#### Comparisons + +The `html/template` package provides a variety of functions to do comparisons between operators. The operators may only be basic types or named basic types such as `type Temp float32` Remember that template functions take the form `{{ function arg1 arg2 }}`. + +- `eq` Returns the result of arg1 == arg2 +- `ne` Returns the result of arg1 != arg2 +- `lt` Returns the result of arg1 < arg2 +- `le` Returns the result of arg1 <= arg2 +- `gt` Returns the result of arg1 > arg2 +- `ge` Returns the result of arg1 >= arg2 + +Of special note `eq` can be used with two or more arguments by comparing all arguments to the first. `{{ eq arg1 arg2 arg3 arg4}}` will result in the following logical expression: + +`arg1==arg2 || arg1==arg3 || arg1==arg4` + +--- + +## Nested Templates and Layouts + +#### Nesting Templates + +Nested templates can be used for parts of code frequently used across templates, a footer or header for example. Rather than updating each template separately we can use a nested template that all other templates can use. You can define a template as follows: + +```go + {{define "footer"}} +
+

Here is the footer

+
+ {{end}} +``` + +A template named “footer” is defined which can be used in other templates like so to add the footer template content into the other template: + +```go + {{template "footer"}} +``` + +--- + +#### Passing Variables between Templates + +The `template` action used to include nested templates also allows a second parameter to pass data to the nested template. + +```html +// Define a nested template called header +{{define "header"}} +

{{.}}

+{{end}} + +// Call template and pass a name parameter +{{range .Items}} +
+ {{template "header" .Name}} + ${{.Price}} +
+{{end}} +``` + +We use the same range to loop through Items as before but we pass the name to the header template each time in this simple example. + +--- + +#### Creating Layouts + +Glob patterns specify sets of filenames with wildcard characters. The `template.ParseGlob(pattern string)` function will parse all templates that match the string pattern. `template.ParseFiles(files...)` can also be used with a list of file names. + +The templates are named by default based on the base names of the argument files. This mean `views/layouts/hello.gohtml` will have the name `hello.gohtml` . If the template has a ``{{define “templateName”}}` within it then that name will be usable. + +A specific template can be executed using `t.ExecuteTemplate(w, "templateName", nil)` . `t` is an object of type Template, `w` is type io.Writer such as an `http.ResponseWriter`, Then there is the name of the template to execute, and finally passing any data to the template, in this case a nil value. + +Example main.go file + +```go + // Omitted imports & package + + var LayoutDir string = "views/layouts" + var bootstrap *template.Template + + func main() { + var err error + bootstrap, err = template.ParseGlob(LayoutDir + "/*.gohtml") + if err != nil { + panic(err) + } + + http.HandleFunc("/", handler) + http.ListenAndServe(":8080", nil) + } + + func handler(w http.ResponseWriter, r *http.Request) { + bootstrap.ExecuteTemplate(w, "bootstrap", nil) + } +``` + +All `.gohtml` files are parsed in main. When route `/` is reached the template defined as `bootstrap` is executed using the handler function. + +Example views/layouts/bootstrap.gohtml file + +```html + {{define "bootstrap"}} + + + + Go Templates + + + +
+

Filler header

+

Filler paragraph

+
+ + + + + {{end}} +``` + +## Templates Calling Functions + +#### Function Variables (calling struct methods) + +We can use templates to call the methods of objects in the template to return data. Consider the User struct with the following method. + +```go + type User struct { + ID int + Email string + } + + func (u User) HasPermission(feature string) bool { + if feature == "feature-a" { + return true + } else { + return false + } + } +``` + +When a type User has been passed to the template we can then call this method from the template. + +```html +{{if .User.HasPermission "feature-a"}} +
+

Feature A

+

Some other stuff here...

+
+{{else}} +
+

Feature A

+

To enable Feature A please upgrade your plan

+
+{{end}} +``` + +The template checks if the User HasPermission for the feature and renders depending on the result. + +--- + +#### Function Variables (call) + +If the Method HasPermission has to change at times then the Function Variables (Methods) implementation may not fit the design. Instead a `HasPermission func(string) bool` attribute can be added on the `User` type. This can then have a function assigned to it at creation. + +```go + // Structs + type ViewData struct { + User User + } + + type User struct { + ID int + Email string + HasPermission func(string) bool + } + + // Example of creating a ViewData + vd := ViewData{ + User: User{ + ID: 1, + Email: "curtis.vermeeren@gmail.com", + // Create the HasPermission function + HasPermission: func(feature string) bool { + if feature == "feature-b" { + return true + } + return false + }, + }, + } + + // Executing the ViewData with the template + err := testTemplate.Execute(w, vd) +``` + +We need to tell the Go template that we want to call this function so we must change the template from the Function Variables (Methods) implementation to do this. We use the `call` keyword supplied by the go `html/template` package. Changing the previous template to use `call` results in: + +```html +{{if (call .User.HasPermission "feature-b")}} +
+

Feature B

+

Some other stuff here...

+
+{{else}} +
+

Feature B

+

To enable Feature B please upgrade your plan

+
+{{end}} +``` + +--- + +#### Custom Functions + +Another way to call functions is to create custom functions with `template.FuncMap` . This method creates global methods that can be used throughout the entire application. FuncMap has type `map[string]interface{}` mapping a string, the function name, to a function. The mapped functions must have either a single return value, or two return values where the second has type error. + +```go + // Creating a template with function hasPermission + testTemplate, err = template.New("hello.gohtml").Funcs(template.FuncMap{ + "hasPermission": func(user User, feature string) bool { + if user.ID == 1 && feature == "feature-a" { + return true + } + return false + }, + }).ParseFiles("hello.gohtml") +``` + +Here the function to check if a user has permission for a feature is mapped to the string `"hasPermission"` and stored in the FuncMap. Note that the custom functions must be created before calling `ParseFiles()` + +The function could be executed in the template as follows: + +```go + {{ if hasPermission .User "feature-a" }} +``` + +The `.User` and string `"feature-a"` are both passed to `hasPermission` as arguments. + +--- + +#### Custom Functions (Globally) + +The previous two methods of custom functions rely on `.User` being passed to the template. This works in many cases but in a large application passing too many objects to a template can become difficult to maintain across many templates. We can change the implementation of the custom function to work without the .User being passed. + +Using a similar feature example as the other 2 sections first you would have to create a default `hasPermission` function and define it in the template’s function map. + +```go + testTemplate, err = template.New("hello.gohtml").Funcs(template.FuncMap{ + "hasPermission": func(feature string) bool { + return false + }, + }).ParseFiles("hello.gohtml") +``` + +This function could be placed in `main()` or somewhere that ensures the default `hasPermission` is created in the `hello.gohtml` function map. The default function just returns false but it defines the function and implementation that doesn’t require `User` . + +Next a closure could be used to redefine the `hasPermission` function. It would use the `User` data available when it is created in a handler rather than having `User` data passed to it. Within the handler for the template you can redefine any functions to use the information available. + +```go + func handler(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "text/html") + + user := User{ + ID: 1, + Email: "Curtis.vermeeren@gmail.com", + } + vd := ViewData{} + err := testTemplate.Funcs(template.FuncMap{ + "hasPermission": func(feature string) bool { + if user.ID == 1 && feature == "feature-a" { + return true + } + return false + }, + }).Execute(w, vd) + if err != nil { + http.Error(w, err.Error(), http.StatusInternalServerError) + } + } +``` + +In this handler a `User` is created with ID and Email, Then a `ViewData` is created without passing the user to it. The `hasPermission` function is redefined using `user.ID` which is available when the function is created. `{{if hasPermission "feature-a"}}` can be used in a template without having to pass a `User` to the template as the User object in the handler is used instead. + +--- diff --git a/template_versioned_docs/version-django_v3.x.x/jet/README.md b/template_versioned_docs/version-django_v3.x.x/jet/README.md new file mode 100644 index 00000000000..bffdd78272b --- /dev/null +++ b/template_versioned_docs/version-django_v3.x.x/jet/README.md @@ -0,0 +1,88 @@ +--- +id: jet +title: Jet +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/template?filter=django*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://github.com/gofiber/template/workflows/Tests/badge.svg) +![Security](https://github.com/gofiber/template/workflows/Security/badge.svg) +![Linter](https://github.com/gofiber/template/workflows/Linter/badge.svg) + +Jet is a template engine create by [cloudykit](https://github.com/CloudyKit/jet), to see the original syntax documentation please [click here](https://github.com/CloudyKit/jet/wiki/3.-Jet-template-syntax) + +### Basic Example + +_**./views/index.jet**_ +```html +{{include "partials/header"}} + +

{{ Title }}

+ +{{include "partials/footer"}} +``` +_**./views/partials/header.jet**_ +```html +

Header

+``` +_**./views/partials/footer.jet**_ +```html +

Footer

+``` +_**./views/layouts/main.jet**_ +```html + + + + + Title + + + + {{ embed() }} + + + +``` + +```go +package main + +import ( + "log" + + "github.com/gofiber/fiber/v2" + "github.com/gofiber/template/jet/v2" +) + +func main() { + // Create a new engine + engine := jet.New("./views", ".jet") + + // Or from an embedded system + // See github.com/gofiber/embed for examples + // engine := jet.NewFileSystem(http.Dir("./views", ".jet")) + + // Pass the engine to the views + app := fiber.New(fiber.Config{ + Views: engine, + }) + + app.Get("/", func(c *fiber.Ctx) error { + // Render index + return c.Render("index", fiber.Map{ + "Title": "Hello, World!", + }) + }) + + app.Get("/layout", func(c *fiber.Ctx) error { + // Render index within layouts/main + return c.Render("index", fiber.Map{ + "Title": "Hello, World!", + }, "layouts/main") + }) + + log.Fatal(app.Listen(":3000")) +} + +``` diff --git a/template_versioned_docs/version-django_v3.x.x/mustache/README.md b/template_versioned_docs/version-django_v3.x.x/mustache/README.md new file mode 100644 index 00000000000..6c02c01ed6a --- /dev/null +++ b/template_versioned_docs/version-django_v3.x.x/mustache/README.md @@ -0,0 +1,89 @@ +--- +id: mustache +title: Mustache +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/template?filter=django*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://github.com/gofiber/template/workflows/Tests/badge.svg) +![Security](https://github.com/gofiber/template/workflows/Security/badge.svg) +![Linter](https://github.com/gofiber/template/workflows/Linter/badge.svg) + +Mustache is a template engine created by [hoisie/cbroglie](https://github.com/cbroglie/mustache), to see the original syntax documentation please [click here](https://mustache.github.io/mustache.5.html) + +### Basic Example + +_**./views/index.mustache**_ +```html +{{> views/partials/header }} + +

{{Title}}

+ +{{> views/partials/footer }} +``` +_**./views/partials/header.mustache**_ +```html +

Header

+``` +_**./views/partials/footer.mustache**_ +```html +

Footer

+``` +_**./views/layouts/main.mustache**_ +```html + + + + + Main + + + + {{{embed}}} + + + +``` + +```go +package main + +import ( + "log" + + "github.com/gofiber/fiber/v2" + "github.com/gofiber/template/mustache/v2" +) + +func main() { + // Create a new engine + engine := mustache.New("./views", ".mustache") + + // Or from an embedded system + // Note that with an embedded system the partials included from template files must be + // specified relative to the filesystem's root, not the current working directory + // engine := mustache.NewFileSystem(http.Dir("./views", ".mustache"), ".mustache") + + // Pass the engine to the Views + app := fiber.New(fiber.Config{ + Views: engine, + }) + + app.Get("/", func(c *fiber.Ctx) error { + // Render index + return c.Render("index", fiber.Map{ + "Title": "Hello, World!", + }) + }) + + app.Get("/layout", func(c *fiber.Ctx) error { + // Render index within layouts/main + return c.Render("index", fiber.Map{ + "Title": "Hello, World!", + }, "layouts/main") + }) + + log.Fatal(app.Listen(":3000")) +} + +``` diff --git a/template_versioned_docs/version-django_v3.x.x/pug/README.md b/template_versioned_docs/version-django_v3.x.x/pug/README.md new file mode 100644 index 00000000000..b4bd57fb6a6 --- /dev/null +++ b/template_versioned_docs/version-django_v3.x.x/pug/README.md @@ -0,0 +1,85 @@ +--- +id: pug +title: Pug +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/template?filter=django*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://github.com/gofiber/template/workflows/Tests/badge.svg) +![Security](https://github.com/gofiber/template/workflows/Security/badge.svg) +![Linter](https://github.com/gofiber/template/workflows/Linter/badge.svg) + +Pug is a template engine create by [joker](https://github.com/Joker/jade), to see the original syntax documentation please [click here](https://pugjs.org/language/tags.html) + +### Basic Example + +_**./views/index.pug**_ +```html +include partials/header.pug + +h1 #{.Title} + +include partials/footer.pug +``` +_**./views/partials/header.pug**_ +```html +h2 Header +``` +_**./views/partials/footer.pug**_ +```html +h2 Footer +``` +_**./views/layouts/main.pug**_ +```html +doctype html +html + head + title Main + include ../partials/meta.pug + body + | {{embed}} +``` + +```go +package main + +import ( + "log" + + "github.com/gofiber/fiber/v2" + "github.com/gofiber/template/pug/v2" + + // "net/http" // embedded system +) + +func main() { + // Create a new engine + engine := pug.New("./views", ".pug") + + // Or from an embedded system + // See github.com/gofiber/embed for examples + // engine := pug.NewFileSystem(http.Dir("./views", ".pug")) + + // Pass the engine to the views + app := fiber.New(fiber.Config{ + Views: engine, + }) + + app.Get("/", func(c *fiber.Ctx) error { + // Render index + return c.Render("index", fiber.Map{ + "Title": "Hello, World!", + }) + }) + + app.Get("/layout", func(c *fiber.Ctx) error { + // Render index within layouts/main + return c.Render("index", fiber.Map{ + "Title": "Hello, World!", + }, "layouts/main") + }) + + log.Fatal(app.Listen(":3000")) +} + +``` diff --git a/template_versioned_docs/version-django_v3.x.x/slim/README.md b/template_versioned_docs/version-django_v3.x.x/slim/README.md new file mode 100644 index 00000000000..5e92de4a4e3 --- /dev/null +++ b/template_versioned_docs/version-django_v3.x.x/slim/README.md @@ -0,0 +1,85 @@ +--- +id: slim +title: Slim +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/template?filter=django*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://github.com/gofiber/template/workflows/Tests/badge.svg) +![Security](https://github.com/gofiber/template/workflows/Security/badge.svg) +![Linter](https://github.com/gofiber/template/workflows/Linter/badge.svg) + +Slim is a template engine created by [mattn](https://github.com/mattn/go-slim), to see the original syntax documentation please [click here](https://rubydoc.info/gems/slim/frames) + +### Basic Example + +_**./views/index.slim**_ +```html +== render("partials/header.slim") + +h1 = Title + +== render("partials/footer.slim") +``` +_**./views/partials/header.slim**_ +```html +h2 = Header +``` +_**./views/partials/footer.slim**_ +```html +h2 = Footer +``` +_**./views/layouts/main.slim**_ +```html +doctype html +html + head + title Main + include ../partials/meta.slim + body + | {{embed}} +``` + +```go +package main + +import ( + "log" + + "github.com/gofiber/fiber/v2" + "github.com/gofiber/template/slim/v2" + + // "net/http" // embedded system +) + +func main() { + // Create a new engine + engine := slim.New("./views", ".slim") + + // Or from an embedded system + // See github.com/gofiber/embed for examples + // engine := slim.NewFileSystem(http.Dir("./views", ".slim")) + + // Pass the engine to the Views + app := fiber.New(fiber.Config{ + Views: engine, + }) + + app.Get("/", func(c *fiber.Ctx) error { + // Render index + return c.Render("index", fiber.Map{ + "Title": "Hello, World!", + }) + }) + + app.Get("/layout", func(c *fiber.Ctx) error { + // Render index within layouts/main + return c.Render("index", fiber.Map{ + "Title": "Hello, World!", + }, "layouts/main") + }) + + log.Fatal(app.Listen(":3000")) +} + +``` diff --git a/template_versioned_sidebars/version-django_v3.x.x-sidebars.json b/template_versioned_sidebars/version-django_v3.x.x-sidebars.json new file mode 100644 index 00000000000..caea0c03ba6 --- /dev/null +++ b/template_versioned_sidebars/version-django_v3.x.x-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/template_versions.json b/template_versions.json index db7d4455c92..e46e694d7cf 100644 --- a/template_versions.json +++ b/template_versions.json @@ -1,4 +1,5 @@ [ + "django_v3.x.x", "jet_v2.x.x", "mustache_v2.x.x", "ace_v2.x.x",