📚 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 <[email protected]>
gofiber · Aug 28, 2024 · ca935c3 · ca935c3
1 parent 87bb93e
commit ca935c3
Showing 1 changed file with 197 additions and 31 deletions.
diff --git a/docs/guide/templates.md b/docs/guide/templates.md
@@ -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">
@@ -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>
+