Skip to content

📚 Doc: Add detailed documentation for the templates guide #3113

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Aug 28, 2024
Merged

📚 Doc: Add detailed documentation for the templates guide #3113

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
27ae932
Organize and reword templates guide
grivera64 Aug 26, 2024
b6c4d69
Add full example to templates guide
grivera64 Aug 26, 2024
00d0490
Add advanced templating section to template guide
grivera64 Aug 28, 2024
5e9930f
Add template repo link and fix typo in Templates guide
grivera64 Aug 28, 2024
890287a
Update docs/guide/templates.md
ReneWerner87 Aug 28, 2024
fc370f3
Update docs/guide/templates.md
ReneWerner87 Aug 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
228 changes: 197 additions & 31 deletions docs/guide/templates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,57 +8,212 @@ 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
app := fiber.New(fiber.Config{
// Pass in Views Template Engine
Views: engine,

// 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,
})
```


### Supported 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/)
* [django](https://docs.gofiber.io/template/django/)
* [handlebars](https://docs.gofiber.io/template/handlebars)
* [html](https://docs.gofiber.io/template/html)
* [jet](https://docs.gofiber.io/template/jet)
* [mustache](https://docs.gofiber.io/template/mustache)
* [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>

`Views` interface contains a `Load` and `Render` method, `Load` is executed by Fiber on app initialization to load/parse the templates.
:::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
// Pass engine to Fiber's Views Engine
// 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,
// Views Layout is the global layout for all template render until override on Render function.
ViewsLayout: "layouts/main"
})

app.Get("/", func (c *fiber.Ctx) error {
return c.Render("index", fiber.Map{
"Content": "hello, world!"
})
})
```

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.
</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
app.Get("/", func(c *fiber.Ctx) error {
// 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{
"hello": "world",
});
"Content": "hello, world!"
})
})
```

## Engines
</TabItem>
<TabItem value="add-func-map-template" label="views/index.html">

Fiber team maintains [templates](https://docs.gofiber.io/template) package that provides wrappers for multiple template engines:
```html
<!DOCTYPE html>
<html>
<body>
<p>This will be in {{ToUpper "all caps"}}:</p>
<p>{{ToUpper .Content}}</p>
</body>
</html>
```

* [ace](https://docs.gofiber.io/template/ace/)
* [amber](https://docs.gofiber.io/template/amber/)
* [django](https://docs.gofiber.io/template/django/)
* [handlebars](https://docs.gofiber.io/template/handlebars)
* [html](https://docs.gofiber.io/template/html)
* [jet](https://docs.gofiber.io/template/jet)
* [mustache](https://docs.gofiber.io/template/mustache)
* [pug](https://docs.gofiber.io/template/pug)
* [slim](https://docs.gofiber.io/template/slim)
</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">
Expand All @@ -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")

Expand All @@ -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"))
Expand All @@ -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>