tpls

Extendable, Fast Template Engine for Go
git clone git://git.lair.cx/tpls
Log | Files | Refs | README | LICENSE

README.md (2985B)

      1 # go.lair.cx/tpls
      2 
      3 Fast and extendable template engine for Go.
      4 
      5 ## Quickstart
      6 
      7 Let's start with this small example.
      8 
      9 ```
     10 <template class="Render(name string)">
     11     <div>Hello, <string>name</string>!</div>
     12 </template>
     13 ```
     14 
     15 Save this file as `./templates/example.html`, and compile it:
     16 
     17 ```
     18 $ go run go.lair.cx/tpls/cmd/tplc
     19 ```
     20 
     21 Command tplc finds html files in current directory, and writes the Go code.
     22 Generated file is `./templates/example.html.go`, let's open this.
     23 
     24 ```
     25 // Code generated by tplc. DO NOT EDIT.
     26 
     27 package templates
     28 
     29 import "go.lair.cx/tpls"
     30 
     31 func Render(w tpls.Writer, name string) {
     32     w.WriteRaw(`<div>Hello, `)
     33     w.WriteString(name)
     34     w.WriteRaw(`!</div>`)
     35 }
     36 ```
     37 
     38 Looks good? Let's write server code.
     39 
     40 ```
     41 package main
     42 
     43 import (
     44     "log"
     45     "net/http"
     46 
     47     "go.lair.cx/tpls"
     48 
     49     "package/templates"
     50 )
     51 
     52 func main() {
     53     log.Fatalln(http.ListenAndServe(":8080", http.HandlerFunc(handler)))
     54 }
     55 
     56 func handler(w http.ResponseWriter, r *http.Request) {
     57     tplw := tpls.NewWriter(nil)
     58     templates.Render(tplw, "World")
     59     w.Header().Set("Content-Type", "text/html;charset=utf-8")
     60     w.WriteHeader(http.StatusOK)
     61     _, _ = w.Write(tplw.Bytes())
     62 }
     63 ```
     64 
     65 Save this file as `./main.go`, `go run .`, open `localhost:8080`. The browser
     66 will print `Hello, World!`.
     67 
     68 For more examples, See `examples/` directory.
     69 
     70 ## Built-in Tags
     71 
     72 `tpls` has many built-in tags. Built-in tags are use class name to define name,
     73 condition, etc. 
     74 
     75 * `template` produces template function. all child elements are rendered in
     76   scope. In other words, no UI element can be rendered in outside of scope.
     77 * `module` defines new tag. For example, the module defined with
     78   `<module class="card">` is can be used as `<card>`.
     79   * `b *tpls.Builder, w *tpls.Writer, t *htmlx.Tokenizer` is provided in
     80     the scope.
     81   * `<body>` tag is provided in this scope.
     82 * `integer` prints integer number.
     83 * `float` prints floating number. `<float class="n">` for precision.
     84 * `string` prints HTML-safe string.
     85   * `<string class="unsafe">` produces unsafe string.
     86   * `<string class="bytes">` can handle `[]byte` type.
     87 * `if` represents Go's `if`.
     88   * `<if class="cond"><then> T1 </then><else> T2 </else></if>`
     89     * When `cond` is true, `T1` is executed, otherwise, `T2` is executed.
     90   * `else` tag can be used continuously to represent else-if, like
     91     `<else class="cond"> T2 </else><else> T3 </else>`.
     92     * `<else>` with class name means else-if.
     93 * `for` represents Go's `for`.
     94   * `<for class="_, i := range V"> T1 </for>`
     95   * `T1` executed `len(V)` times. variable `i` can be used in the scope,
     96     just same as Go.
     97 * `import` produces `import ( ... )`.
     98 * `interface` and `struct` defines type.
     99 * `raw` executes it's code at runtime.
    100 * `title` produces `<title>` tag. It acts the same as the `<string>` tag except
    101   that the result is wrapped with a plain html's `<title>` tag.
    102   * You can use Go string with this tag for represent plain text.
    103     For example: `<title>"Hello, World!"</title>`