README
¶
Gonja
gonja is pongo2 fork intended to be aligned on Jinja template syntax instead of the Django one.
Install/update using go get (no dependencies required by gonja):
go get github.com/noirbizarre/gonja
Please use the issue tracker if you're encountering any problems with gonja or if you need help with implementing tags or filters (create a ticket!).
First impression of a template
<html><head><title>Our admins and users</title></head>
{# This is a short example to give you a quick overview of gonja's syntax. #}
{% macro user_details(user, is_admin=false) %}
<div class="user_item">
<!-- Let's indicate a user's good karma -->
<h2 {% if (user.karma >= 40) || (user.karma > calc_avg_karma(userlist)+5) %}
class="karma-good"{% endif %}>
<!-- This will call user.String() automatically if available: -->
{{ user }}
</h2>
<!-- Will print a human-readable time duration like "3 weeks ago" -->
<p>This user registered {{ user.register_date|naturaltime }}.</p>
<!-- Let's allow the users to write down their biography using markdown;
we will only show the first 15 words as a preview -->
<p>The user's biography:</p>
<p>{{ user.biography|markdown|truncatewords_html:15 }}
<a href="/user/{{ user.id }}/">read more</a></p>
{% if is_admin %}<p>This user is an admin!</p>{% endif %}
</div>
{% endmacro %}
<body>
<!-- Make use of the macro defined above to avoid repetitive HTML code
since we want to use the same code for admins AND members -->
<h1>Our admins</h1>
{% for admin in adminlist %}
{{ user_details(admin, true) }}
{% endfor %}
<h1>Our members</h1>
{% for user in userlist %}
{{ user_details(user) }}
{% endfor %}
</body>
</html>
Features (and new in gonja)
- Entirely rewritten from the ground-up.
- Advanced C-like expressions.
- Complex function calls within expressions.
- Easy API to create new filters and tags (including parsing arguments)
- Additional features:
- Macros including importing macros from other files (see template_tests/macro.tpl)
- Template sandboxing (directory patterns, banned tags/filters)
How you can help
- Write filters / statements
- Write/improve code tests (use the following command to see what tests are missing:
go test -v -cover -covermode=count -coverprofile=cover.out && go tool cover -html=cover.outor have a look on gocover.io/github.com/noirbizarre/gonja) - Write/improve template tests (see the
testData/directory) - Write middleware, libraries and websites using gonja. :-)
Documentation
For a documentation on how the templating language works you can head over to the Jinja documentation. gonja aims to be compatible with it.
You can access gonja's API documentation on godoc.
Caveats
Filters
- format:
formatdoes not take Python's string format syntax as a parameter, instead it takes Go's. Essentially{{ 3.14|stringformat:"pi is %.2f" }}isfmt.Sprintf("pi is %.2f", 3.14). - escape / force_escape: Unlike Jinja's behaviour, the
escape-filter is applied immediately. Therefore there is no need for aforce_escape-filter yet.
API-usage examples
Please see the documentation for a full list of provided API methods.
A tiny example (template string)
// Compile the template first (i. e. creating the AST)
tpl, err := gonja.FromString("Hello {{ name|capfirst }}!")
if err != nil {
panic(err)
}
// Now you can render the template with the given
// gonja.Context how often you want to.
out, err := tpl.Execute(gonja.Context{"name": "axel"})
if err != nil {
panic(err)
}
fmt.Println(out) // Output: Hello Axel!
Example server-usage (template file)
package main
import (
"github.com/noirbizarre/gonja"
"net/http"
)
// Pre-compiling the templates at application startup using the
// little Must()-helper function (Must() will panic if FromFile()
// or FromString() will return with an error - that's it).
// It's faster to pre-compile it anywhere at startup and only
// execute the template later.
var tpl = gonja.Must(gonja.FromFile("example.html"))
func examplePage(w http.ResponseWriter, r *http.Request) {
// Execute the template per HTTP request
out, err := tpl.Execute(gonja.Context{"query": r.FormValue("query")})
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
}
w.WriteString(out)
}
func main() {
http.HandleFunc("/", examplePage)
http.ListenAndServe(":8080", nil)
}
Benchmark
The benchmarks have been run on the my machine (Intel(R) Core(TM) i7-2600 CPU @ 3.40GHz) using the command:
go test -bench . -cpu 1,2,4,8
All benchmarks are compiling (depends on the benchmark) and executing the testData/complex.tpl template.
The results are:
BenchmarkFromCache 30000 41259 ns/op
BenchmarkFromCache-2 30000 42776 ns/op
BenchmarkFromCache-4 30000 44432 ns/op
BenchmarkFromFile 3000 437755 ns/op
BenchmarkFromFile-2 3000 472828 ns/op
BenchmarkFromFile-4 2000 519758 ns/op
BenchmarkExecute 30000 41984 ns/op
BenchmarkExecute-2 30000 48546 ns/op
BenchmarkExecute-4 20000 104469 ns/op
BenchmarkCompileAndExecute 3000 428425 ns/op
BenchmarkCompileAndExecute-2 3000 459058 ns/op
BenchmarkCompileAndExecute-4 3000 488519 ns/op
BenchmarkParallelExecute 30000 45262 ns/op
BenchmarkParallelExecute-2 100000 23490 ns/op
BenchmarkParallelExecute-4 100000 24206 ns/op
Benchmarked on August 18th 2019.
Documentation
¶
Overview ¶
A jinja like template-engine
Blog posts about gonja (including introduction and migration): https://www.florian-schlachter.de/?tag=gonja
Complete documentation on the template language: https://docs.djangoproject.com/en/dev/topics/templates/
Try out gonja live in the gonja playground: https://www.florian-schlachter.de/gonja/
Make sure to read README.md in the repository as well.
A tiny example with template strings:
(Snippet on playground: https://www.florian-schlachter.de/gonja/?id=1206546277)
// Compile the template first (i. e. creating the AST)
tpl, err := gonja.FromString("Hello {{ name|capfirst }}!")
if err != nil {
panic(err)
}
// Now you can render the template with the given
// gonja.Context how often you want to.
out, err := tpl.Execute(gonja.Context{"name": "fred"})
if err != nil {
panic(err)
}
fmt.Println(out) // Output: Hello Fred!
Index ¶
- Constants
- Variables
- func Must(tpl *exec.Template, err error) *exec.Template
- type Config
- type Context
- type Environment
- func (env *Environment) CleanCache(filenames ...string)
- func (env *Environment) FromBytes(tpl []byte) (*exec.Template, error)
- func (env *Environment) FromCache(filename string) (*exec.Template, error)
- func (env *Environment) FromFile(filename string) (*exec.Template, error)
- func (env *Environment) FromString(tpl string) (*exec.Template, error)
- func (env *Environment) GetTemplate(filename string) (*exec.Template, error)
Constants ¶
const VERSION = "0.1.0"
Variables ¶
var ( // DefaultLoader is being used by the DefaultSet. DefaultLoader = loaders.MustNewFileSystemLoader("") // DefaultEnv is an environment created for quick/standalone template rendering. DefaultEnv = NewEnvironment(config.DefaultConfig, DefaultLoader) // Methods on the default set FromString = DefaultEnv.FromString FromBytes = DefaultEnv.FromBytes FromFile = DefaultEnv.FromFile FromCache = DefaultEnv.FromCache // Globals for the default set Globals = DefaultEnv.Globals )
var NewConfig = config.NewConfig
Functions ¶
Types ¶
type Environment ¶
type Environment struct {
*exec.EvalConfig
Loader loaders.Loader
Cache map[string]*exec.Template
CacheMutex sync.Mutex
}
func NewEnvironment ¶
func NewEnvironment(cfg *config.Config, loader loaders.Loader) *Environment
func (*Environment) CleanCache ¶
func (env *Environment) CleanCache(filenames ...string)
CleanCache cleans the template cache. If filenames is not empty, it will remove the template caches of those filenames. Or it will empty the whole template cache. It is thread-safe.
func (*Environment) FromBytes ¶
func (env *Environment) FromBytes(tpl []byte) (*exec.Template, error)
FromBytes loads a template from bytes and returns a Template instance.
func (*Environment) FromCache ¶
func (env *Environment) FromCache(filename string) (*exec.Template, error)
FromCache is a convenient method to cache templates. It is thread-safe and will only compile the template associated with a filename once. If Environment.Debug is true (for example during development phase), FromCache() will not cache the template and instead recompile it on any call (to make changes to a template live instantaneously).
func (*Environment) FromFile ¶
func (env *Environment) FromFile(filename string) (*exec.Template, error)
FromFile loads a template from a filename and returns a Template instance.
func (*Environment) FromString ¶
func (env *Environment) FromString(tpl string) (*exec.Template, error)
FromString loads a template from string and returns a Template instance.
func (*Environment) GetTemplate ¶
func (env *Environment) GetTemplate(filename string) (*exec.Template, error)
Source Files
Directories