123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535 |
- package render
-
- import (
- "bytes"
- "fmt"
- "html/template"
- "io"
- "log"
- "net/http"
- "os"
- "path/filepath"
- "strings"
- "sync"
-
- "github.com/fsnotify/fsnotify"
- )
-
- const (
- // ContentBinary header value for binary data.
- ContentBinary = "application/octet-stream"
- // ContentHTML header value for HTML data.
- ContentHTML = "text/html"
- // ContentJSON header value for JSON data.
- ContentJSON = "application/json"
- // ContentJSONP header value for JSONP data.
- ContentJSONP = "application/javascript"
- // ContentLength header constant.
- ContentLength = "Content-Length"
- // ContentText header value for Text data.
- ContentText = "text/plain"
- // ContentType header constant.
- ContentType = "Content-Type"
- // ContentXHTML header value for XHTML data.
- ContentXHTML = "application/xhtml+xml"
- // ContentXML header value for XML data.
- ContentXML = "text/xml"
- // Default character encoding.
- defaultCharset = "UTF-8"
- )
-
- // helperFuncs had to be moved out. See helpers.go|helpers_pre16.go files.
-
- // Delims represents a set of Left and Right delimiters for HTML template rendering.
- type Delims struct {
- // Left delimiter, defaults to {{.
- Left string
- // Right delimiter, defaults to }}.
- Right string
- }
-
- // Options is a struct for specifying configuration options for the render.Render object.
- type Options struct {
- // Directory to load templates. Default is "templates".
- Directory string
- // FileSystem to access files
- FileSystem FileSystem
- // Asset function to use in place of directory. Defaults to nil.
- Asset func(name string) ([]byte, error)
- // AssetNames function to use in place of directory. Defaults to nil.
- AssetNames func() []string
- // Layout template name. Will not render a layout if blank (""). Defaults to blank ("").
- Layout string
- // Extensions to parse template files from. Defaults to [".tmpl"].
- Extensions []string
- // Funcs is a slice of FuncMaps to apply to the template upon compilation. This is useful for helper functions. Defaults to empty map.
- Funcs []template.FuncMap
- // Delims sets the action delimiters to the specified strings in the Delims struct.
- Delims Delims
- // Appends the given character set to the Content-Type header. Default is "UTF-8".
- Charset string
- // If DisableCharset is set to true, it will not append the above Charset value to the Content-Type header. Default is false.
- DisableCharset bool
- // Outputs human readable JSON.
- IndentJSON bool
- // Outputs human readable XML. Default is false.
- IndentXML bool
- // Prefixes the JSON output with the given bytes. Default is false.
- PrefixJSON []byte
- // Prefixes the XML output with the given bytes.
- PrefixXML []byte
- // Allows changing the binary content type.
- BinaryContentType string
- // Allows changing the HTML content type.
- HTMLContentType string
- // Allows changing the JSON content type.
- JSONContentType string
- // Allows changing the JSONP content type.
- JSONPContentType string
- // Allows changing the Text content type.
- TextContentType string
- // Allows changing the XML content type.
- XMLContentType string
- // If IsDevelopment is set to true, this will recompile the templates on every request. Default is false.
- IsDevelopment bool
- // If UseMutexLock is set to true, the standard `sync.RWMutex` lock will be used instead of the lock free implementation. Default is false.
- // Note that when `IsDevelopment` is true, the standard `sync.RWMutex` lock is always used. Lock free is only a production feature.
- UseMutexLock bool
- // Unescape HTML characters "&<>" to their original values. Default is false.
- UnEscapeHTML bool
- // Streams JSON responses instead of marshalling prior to sending. Default is false.
- StreamingJSON bool
- // Require that all partials executed in the layout are implemented in all templates using the layout. Default is false.
- RequirePartials bool
- // Deprecated: Use the above `RequirePartials` instead of this. As of Go 1.6, blocks are built in. Default is false.
- RequireBlocks bool
- // Disables automatic rendering of http.StatusInternalServerError when an error occurs. Default is false.
- DisableHTTPErrorRendering bool
- // Enables using partials without the current filename suffix which allows use of the same template in multiple files. e.g {{ partial "carosuel" }} inside the home template will match carosel-home or carosel.
- // ***NOTE*** - This option should be named RenderPartialsWithoutSuffix as that is what it does. "Prefix" is a typo. Maintaining the existing name for backwards compatibility.
- RenderPartialsWithoutPrefix bool
- // BufferPool to use when rendering HTML templates. If none is supplied
- // defaults to SizedBufferPool of size 32 with 512KiB buffers.
- BufferPool GenericBufferPool
- }
-
- // HTMLOptions is a struct for overriding some rendering Options for specific HTML call.
- type HTMLOptions struct {
- // Layout template name. Overrides Options.Layout.
- Layout string
- // Funcs added to Options.Funcs.
- Funcs template.FuncMap
- }
-
- // Render is a service that provides functions for easily writing JSON, XML,
- // binary data, and HTML templates out to a HTTP Response.
- type Render struct {
- lock rwLock
-
- // Customize Secure with an Options struct.
- opt Options
- templates *template.Template
- compiledCharset string
- hasWatcher bool
- }
-
- // New constructs a new Render instance with the supplied options.
- func New(options ...Options) *Render {
- var o Options
- if len(options) > 0 {
- o = options[0]
- }
-
- r := Render{opt: o}
-
- r.prepareOptions()
- r.CompileTemplates()
-
- return &r
- }
-
- func (r *Render) prepareOptions() {
- // Fill in the defaults if need be.
- if len(r.opt.Charset) == 0 {
- r.opt.Charset = defaultCharset
- }
- if !r.opt.DisableCharset {
- r.compiledCharset = "; charset=" + r.opt.Charset
- }
- if len(r.opt.Directory) == 0 {
- r.opt.Directory = "templates"
- }
- if r.opt.FileSystem == nil {
- r.opt.FileSystem = &LocalFileSystem{}
- }
- if len(r.opt.Extensions) == 0 {
- r.opt.Extensions = []string{".tmpl"}
- }
- if len(r.opt.BinaryContentType) == 0 {
- r.opt.BinaryContentType = ContentBinary
- }
- if len(r.opt.HTMLContentType) == 0 {
- r.opt.HTMLContentType = ContentHTML
- }
- if len(r.opt.JSONContentType) == 0 {
- r.opt.JSONContentType = ContentJSON
- }
- if len(r.opt.JSONPContentType) == 0 {
- r.opt.JSONPContentType = ContentJSONP
- }
- if len(r.opt.TextContentType) == 0 {
- r.opt.TextContentType = ContentText
- }
- if len(r.opt.XMLContentType) == 0 {
- r.opt.XMLContentType = ContentXML
- }
- if r.opt.BufferPool == nil {
- r.opt.BufferPool = NewSizedBufferPool(32, 1<<19) // 32 buffers of size 512KiB each
- }
- if r.opt.IsDevelopment || r.opt.UseMutexLock {
- r.lock = &sync.RWMutex{}
- } else {
- r.lock = &emptyLock{}
- }
- }
-
- func (r *Render) CompileTemplates() {
- if r.opt.Asset == nil || r.opt.AssetNames == nil {
- r.compileTemplatesFromDir()
- return
- }
-
- r.compileTemplatesFromAsset()
- }
-
- func (r *Render) compileTemplatesFromDir() {
- dir := r.opt.Directory
- tmpTemplates := template.New(dir)
- tmpTemplates.Delims(r.opt.Delims.Left, r.opt.Delims.Right)
-
- var watcher *fsnotify.Watcher
- if r.opt.IsDevelopment {
- var err error
- watcher, err = fsnotify.NewWatcher()
- if err != nil {
- log.Printf("Unable to create new watcher for template files. Templates will be recompiled on every render. Error: %v\n", err)
- }
- }
-
- // Walk the supplied directory and compile any files that match our extension list.
- _ = r.opt.FileSystem.Walk(dir, func(path string, info os.FileInfo, _ error) error {
- // Fix same-extension-dirs bug: some dir might be named to: "users.tmpl", "local.html".
- // These dirs should be excluded as they are not valid golang templates, but files under
- // them should be treat as normal.
- // If is a dir, return immediately (dir is not a valid golang template).
- if info != nil && watcher != nil {
- _ = watcher.Add(path)
- }
- if info == nil || info.IsDir() {
- return nil
- }
-
- rel, err := filepath.Rel(dir, path)
- if err != nil {
- return err
- }
-
- ext := ""
- if strings.Contains(rel, ".") {
- ext = filepath.Ext(rel)
- }
-
- for _, extension := range r.opt.Extensions {
- if ext == extension {
- buf, err := r.opt.FileSystem.ReadFile(path)
- if err != nil {
- panic(err)
- }
-
- name := (rel[0 : len(rel)-len(ext)])
- tmpl := tmpTemplates.New(filepath.ToSlash(name))
-
- // Add our funcmaps.
- for _, funcs := range r.opt.Funcs {
- tmpl.Funcs(funcs)
- }
-
- // Break out if this parsing fails. We don't want any silent server starts.
- template.Must(tmpl.Funcs(helperFuncs).Parse(string(buf)))
- break
- }
- }
- return nil
- })
-
- r.lock.Lock()
- defer r.lock.Unlock()
- r.templates = tmpTemplates
- if r.hasWatcher = watcher != nil; r.hasWatcher {
- go func() {
- select {
- case _, ok := <-watcher.Events:
- if !ok {
- return
- }
- case _, ok := <-watcher.Errors:
- if !ok {
- return
- }
- }
- watcher.Close()
- r.CompileTemplates()
- }()
- }
- }
-
- func (r *Render) compileTemplatesFromAsset() {
- dir := r.opt.Directory
- tmpTemplates := template.New(dir)
- tmpTemplates.Delims(r.opt.Delims.Left, r.opt.Delims.Right)
-
- for _, path := range r.opt.AssetNames() {
- if !strings.HasPrefix(path, dir) {
- continue
- }
-
- rel, err := filepath.Rel(dir, path)
- if err != nil {
- panic(err)
- }
-
- ext := ""
- if strings.Contains(rel, ".") {
- ext = "." + strings.Join(strings.Split(rel, ".")[1:], ".")
- }
-
- for _, extension := range r.opt.Extensions {
- if ext == extension {
- buf, err := r.opt.Asset(path)
- if err != nil {
- panic(err)
- }
-
- name := (rel[0 : len(rel)-len(ext)])
- tmpl := tmpTemplates.New(filepath.ToSlash(name))
-
- // Add our funcmaps.
- for _, funcs := range r.opt.Funcs {
- tmpl.Funcs(funcs)
- }
-
- // Break out if this parsing fails. We don't want any silent server starts.
- template.Must(tmpl.Funcs(helperFuncs).Parse(string(buf)))
- break
- }
- }
- }
- r.lock.Lock()
- defer r.lock.Unlock()
- r.templates = tmpTemplates
- }
-
- // TemplateLookup is a wrapper around template.Lookup and returns
- // the template with the given name that is associated with t, or nil
- // if there is no such template.
- func (r *Render) TemplateLookup(t string) *template.Template {
- r.lock.RLock()
- defer r.lock.RUnlock()
- return r.templates.Lookup(t)
- }
-
- func (r *Render) execute(templates *template.Template, name string, binding interface{}) (*bytes.Buffer, error) {
- buf := new(bytes.Buffer)
- return buf, templates.ExecuteTemplate(buf, name, binding)
- }
-
- func (r *Render) layoutFuncs(templates *template.Template, name string, binding interface{}) template.FuncMap {
- return template.FuncMap{
- "yield": func() (template.HTML, error) {
- buf, err := r.execute(templates, name, binding)
- // Return safe HTML here since we are rendering our own template.
- return template.HTML(buf.String()), err
- },
- "current": func() (string, error) {
- return name, nil
- },
- "block": func(partialName string) (template.HTML, error) {
- log.Println("Render's `block` implementation is now depericated. Use `partial` as a drop in replacement.")
- fullPartialName := fmt.Sprintf("%s-%s", partialName, name)
- if templates.Lookup(fullPartialName) == nil && r.opt.RenderPartialsWithoutPrefix {
- fullPartialName = partialName
- }
- if r.opt.RequireBlocks || templates.Lookup(fullPartialName) != nil {
- buf, err := r.execute(templates, fullPartialName, binding)
- // Return safe HTML here since we are rendering our own template.
- return template.HTML(buf.String()), err
- }
- return "", nil
- },
- "partial": func(partialName string) (template.HTML, error) {
- fullPartialName := fmt.Sprintf("%s-%s", partialName, name)
- if templates.Lookup(fullPartialName) == nil && r.opt.RenderPartialsWithoutPrefix {
- fullPartialName = partialName
- }
- if r.opt.RequirePartials || templates.Lookup(fullPartialName) != nil {
- buf, err := r.execute(templates, fullPartialName, binding)
- // Return safe HTML here since we are rendering our own template.
- return template.HTML(buf.String()), err
- }
- return "", nil
- },
- }
- }
-
- func (r *Render) prepareHTMLOptions(htmlOpt []HTMLOptions) HTMLOptions {
- layout := r.opt.Layout
- funcs := template.FuncMap{}
-
- for _, tmp := range r.opt.Funcs {
- for k, v := range tmp {
- funcs[k] = v
- }
- }
-
- if len(htmlOpt) > 0 {
- opt := htmlOpt[0]
- if len(opt.Layout) > 0 {
- layout = opt.Layout
- }
-
- for k, v := range opt.Funcs {
- funcs[k] = v
- }
- }
-
- return HTMLOptions{
- Layout: layout,
- Funcs: funcs,
- }
- }
-
- // Render is the generic function called by XML, JSON, Data, HTML, and can be called by custom implementations.
- func (r *Render) Render(w io.Writer, e Engine, data interface{}) error {
- err := e.Render(w, data)
- if hw, ok := w.(http.ResponseWriter); err != nil && !r.opt.DisableHTTPErrorRendering && ok {
- http.Error(hw, err.Error(), http.StatusInternalServerError)
- }
- return err
- }
-
- // Data writes out the raw bytes as binary data.
- func (r *Render) Data(w io.Writer, status int, v []byte) error {
- head := Head{
- ContentType: r.opt.BinaryContentType,
- Status: status,
- }
-
- d := Data{
- Head: head,
- }
-
- return r.Render(w, d, v)
- }
-
- // HTML builds up the response from the specified template and bindings.
- func (r *Render) HTML(w io.Writer, status int, name string, binding interface{}, htmlOpt ...HTMLOptions) error {
- // If we are in development mode, recompile the templates on every HTML request.
- r.lock.RLock() // rlock here because we're reading the hasWatcher
- if r.opt.IsDevelopment && !r.hasWatcher {
- r.lock.RUnlock() // runlock here because CompileTemplates will lock
- r.CompileTemplates()
- r.lock.RLock()
- }
- templates := r.templates
- r.lock.RUnlock()
-
- opt := r.prepareHTMLOptions(htmlOpt)
- if tpl := templates.Lookup(name); tpl != nil {
- if len(opt.Layout) > 0 {
- tpl.Funcs(r.layoutFuncs(templates, name, binding))
- name = opt.Layout
- }
-
- if len(opt.Funcs) > 0 {
- tpl.Funcs(opt.Funcs)
- }
- }
-
- head := Head{
- ContentType: r.opt.HTMLContentType + r.compiledCharset,
- Status: status,
- }
-
- h := HTML{
- Head: head,
- Name: name,
- Templates: templates,
- bp: r.opt.BufferPool,
- }
-
- return r.Render(w, h, binding)
- }
-
- // JSON marshals the given interface object and writes the JSON response.
- func (r *Render) JSON(w io.Writer, status int, v interface{}) error {
- head := Head{
- ContentType: r.opt.JSONContentType + r.compiledCharset,
- Status: status,
- }
-
- j := JSON{
- Head: head,
- Indent: r.opt.IndentJSON,
- Prefix: r.opt.PrefixJSON,
- UnEscapeHTML: r.opt.UnEscapeHTML,
- StreamingJSON: r.opt.StreamingJSON,
- }
-
- return r.Render(w, j, v)
- }
-
- // JSONP marshals the given interface object and writes the JSON response.
- func (r *Render) JSONP(w io.Writer, status int, callback string, v interface{}) error {
- head := Head{
- ContentType: r.opt.JSONPContentType + r.compiledCharset,
- Status: status,
- }
-
- j := JSONP{
- Head: head,
- Indent: r.opt.IndentJSON,
- Callback: callback,
- }
-
- return r.Render(w, j, v)
- }
-
- // Text writes out a string as plain text.
- func (r *Render) Text(w io.Writer, status int, v string) error {
- head := Head{
- ContentType: r.opt.TextContentType + r.compiledCharset,
- Status: status,
- }
-
- t := Text{
- Head: head,
- }
-
- return r.Render(w, t, v)
- }
-
- // XML marshals the given interface object and writes the XML response.
- func (r *Render) XML(w io.Writer, status int, v interface{}) error {
- head := Head{
- ContentType: r.opt.XMLContentType + r.compiledCharset,
- Status: status,
- }
-
- x := XML{
- Head: head,
- Indent: r.opt.IndentXML,
- Prefix: r.opt.PrefixXML,
- }
-
- return r.Render(w, x, v)
- }
|