mirror of https://github.com/gofiber/fiber.git
📚 Doc: Add detailed documentation for the templates guide (#3113)
* Organize and reword templates guide * Add full example to templates guide * Add advanced templating section to template guide * Add template repo link and fix typo in Templates guide - Add link to https://github.com/gofiber/template in Templates Guide - Fix typo: missing period in info block about ctx.Render() * Update docs/guide/templates.md * Update docs/guide/templates.md --------- Co-authored-by: RW <rene@gofiber.io>pull/3124/head
Giovanni Rivera
GitHub
parent
87bb93ecf0
commit
ca935c3f8f
|
|
@ -8,47 +8,30 @@ sidebar_position: 3
|
|||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
## Template interfaces
|
||||
Templates are a great tool to render dynamic content without using a separate frontend framework.
|
||||
|
||||
Fiber provides a Views interface to provide your own template engine:
|
||||
## Template Engines
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="views" label="Views">
|
||||
Fiber allows you to provide a custom template engine at app initialization.
|
||||
|
||||
```go
|
||||
type Views interface {
|
||||
Load() error
|
||||
Render(io.Writer, string, interface{}, ...string) error
|
||||
}
|
||||
```
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
`Views` interface contains a `Load` and `Render` method, `Load` is executed by Fiber on app initialization to load/parse the templates.
|
||||
|
||||
```go
|
||||
// Pass engine to Fiber's Views Engine
|
||||
app := fiber.New(fiber.Config{
|
||||
// Pass in Views Template Engine
|
||||
Views: engine,
|
||||
// Views Layout is the global layout for all template render until override on Render function.
|
||||
ViewsLayout: "layouts/main"
|
||||
|
||||
// Default global path to search for views (can be overriden when calling Render())
|
||||
ViewsLayout: "layouts/main",
|
||||
|
||||
// Enables/Disables access to `ctx.Locals()` entries in rendered views
|
||||
// (defaults to false)
|
||||
PassLocalsToViews: false,
|
||||
})
|
||||
```
|
||||
|
||||
The `Render` method is linked to the [**ctx.Render\(\)**](../api/ctx.md#render) function that accepts a template name and binding data. It will use global layout if layout is not being defined in `Render` function.
|
||||
If the Fiber config option `PassLocalsToViews` is enabled, then all locals set using `ctx.Locals(key, value)` will be passed to the template.
|
||||
|
||||
```go
|
||||
app.Get("/", func(c *fiber.Ctx) error {
|
||||
return c.Render("index", fiber.Map{
|
||||
"hello": "world",
|
||||
});
|
||||
})
|
||||
```
|
||||
### Supported Engines
|
||||
|
||||
## Engines
|
||||
|
||||
Fiber team maintains [templates](https://docs.gofiber.io/template) package that provides wrappers for multiple template engines:
|
||||
The Fiber team maintains a [templates](https://docs.gofiber.io/template) package that provides wrappers for multiple template engines:
|
||||
|
||||
* [ace](https://docs.gofiber.io/template/ace/)
|
||||
* [amber](https://docs.gofiber.io/template/amber/)
|
||||
|
|
@ -60,6 +43,178 @@ Fiber team maintains [templates](https://docs.gofiber.io/template) package that
|
|||
* [pug](https://docs.gofiber.io/template/pug)
|
||||
* [slim](https://docs.gofiber.io/template/slim)
|
||||
|
||||
:::info
|
||||
Custom template engines can implement the `Views` interface to be supported in Fiber.
|
||||
:::
|
||||
|
||||
|
||||
```go title="Views interface"
|
||||
type Views interface {
|
||||
// Fiber executes Load() on app initialization to load/parse the templates
|
||||
Load() error
|
||||
|
||||
// Outputs a template to the provided buffer using the provided template,
|
||||
// template name, and binded data
|
||||
Render(io.Writer, string, interface{}, ...string) error
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
The `Render` method is linked to the [**ctx.Render\(\)**](../api/ctx.md#render) function that accepts a template name and binding data.
|
||||
:::
|
||||
|
||||
|
||||
## Rendering Templates
|
||||
|
||||
Once an engine is set up, a route handler can call the [**ctx.Render\(\)**](../api/ctx.md#render) function with a template name and binded data to send the rendered template.
|
||||
|
||||
```go title="Signature"
|
||||
func (c *Ctx) Render(name string, bind Map, layouts ...string) error
|
||||
```
|
||||
|
||||
:::info
|
||||
By default, [**ctx.Render\(\)**](../api/ctx.md#render) searches for the template name in the `ViewsLayout` path. To override this setting, provide the path(s) in the `layouts` argument.
|
||||
:::
|
||||
|
||||
|
||||
<Tabs>
|
||||
|
||||
<TabItem value="example" label="Example">
|
||||
|
||||
```go
|
||||
app.Get("/", func(c *fiber.Ctx) error {
|
||||
return c.Render("index", fiber.Map{
|
||||
"Title": "Hello, World!",
|
||||
})
|
||||
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="index" label="layouts/index.html">
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<body>
|
||||
<h1>{{.Title}}</h1>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
:::caution
|
||||
If the Fiber config option `PassLocalsToViews` is enabled, then all locals set using `ctx.Locals(key, value)` will be passed to the template. It is important to avoid clashing keys when using this setting.
|
||||
:::
|
||||
|
||||
## Advanced Templating
|
||||
|
||||
### Custom Functions
|
||||
|
||||
Fiber supports adding custom functions to templates.
|
||||
|
||||
#### AddFunc
|
||||
|
||||
Adds a global function to all templates.
|
||||
|
||||
```go title="Signature"
|
||||
func (e *Engine) AddFunc(name string, fn interface{}) IEngineCore
|
||||
```
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="add-func-example" label="AddFunc Example">
|
||||
|
||||
```go
|
||||
// Add `ToUpper` to engine
|
||||
engine := html.New("./views", ".html")
|
||||
engine.AddFunc("ToUpper", func(s string) string {
|
||||
return strings.ToUpper(s)
|
||||
}
|
||||
|
||||
// Initialize Fiber App
|
||||
app := fiber.New(fiber.Config{
|
||||
Views: engine,
|
||||
})
|
||||
|
||||
app.Get("/", func (c *fiber.Ctx) error {
|
||||
return c.Render("index", fiber.Map{
|
||||
"Content": "hello, world!"
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="add-func-template" label="views/index.html">
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<body>
|
||||
<p>This will be in {{ToUpper "all caps"}}:</p>
|
||||
<p>{{ToUpper .Content}}</p>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
#### AddFuncMap
|
||||
|
||||
Adds a Map of functions (keyed by name) to all templates.
|
||||
|
||||
```go title="Signature"
|
||||
func (e *Engine) AddFuncMap(m map[string]interface{}) IEngineCore
|
||||
```
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="add-func-map-example" label="AddFuncMap Example">
|
||||
|
||||
```go
|
||||
// Add `ToUpper` to engine
|
||||
engine := html.New("./views", ".html")
|
||||
engine.AddFuncMap(map[string]interface{}{
|
||||
"ToUpper": func(s string) string {
|
||||
return strings.ToUpper(s)
|
||||
},
|
||||
})
|
||||
|
||||
// Initialize Fiber App
|
||||
app := fiber.New(fiber.Config{
|
||||
Views: engine,
|
||||
})
|
||||
|
||||
app.Get("/", func (c *fiber.Ctx) error {
|
||||
return c.Render("index", fiber.Map{
|
||||
"Content": "hello, world!"
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="add-func-map-template" label="views/index.html">
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<body>
|
||||
<p>This will be in {{ToUpper "all caps"}}:</p>
|
||||
<p>{{ToUpper .Content}}</p>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
- For more advanced template documentation, please visit the [gofiber/template GitHub Repository](https://github.com/gofiber/template).
|
||||
|
||||
## Full Example
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="example" label="Example">
|
||||
|
||||
|
|
@ -75,7 +230,8 @@ import (
|
|||
func main() {
|
||||
// Initialize standard Go html template engine
|
||||
engine := html.New("./views", ".html")
|
||||
// If you want other engine, just replace with following
|
||||
// If you want to use another engine,
|
||||
// just replace with following:
|
||||
// Create a new engine with django
|
||||
// engine := django.New("./views", ".django")
|
||||
|
||||
|
|
@ -85,8 +241,10 @@ func main() {
|
|||
app.Get("/", func(c *fiber.Ctx) error {
|
||||
// Render index template
|
||||
return c.Render("index", fiber.Map{
|
||||
"Title": "Hello, World!",
|
||||
})
|
||||
"Title": "Go Fiber Template Example",
|
||||
"Description": "An example template",
|
||||
"Greeting": "Hello, world!",
|
||||
});
|
||||
})
|
||||
|
||||
log.Fatal(app.Listen(":3000"))
|
||||
|
|
@ -95,12 +253,20 @@ func main() {
|
|||
</TabItem>
|
||||
<TabItem value="index" label="views/index.html">
|
||||
|
||||
```markup
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<body>
|
||||
<h1>{{.Title}}</h1>
|
||||
</body>
|
||||
<html>
|
||||
<head>
|
||||
<title>{{.Title}}</title>
|
||||
<meta name="description" content="{{.Description}}">
|
||||
</head>
|
||||
<body>
|
||||
<h1>{{.Title}}</h1>
|
||||
<p>{{.Greeting}}</p>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue