FilesExpand file tree

main

/

mold.go

Copy path

Blame

More file actions

Blame

More file actions

Latest commit

 

History

History

History

172 lines (154 loc) · 4.62 KB

main

/

mold.go

Copy path

Top

File metadata and controls

• Code
• Blame

172 lines (154 loc) · 4.62 KB

Raw

Copy raw file

Download raw file

Open symbols panel

Edit and raw actions

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

65

66

67

68

69

70

71

72

73

74

75

76

77

78

79

80

81

82

83

84

85

86

87

88

89

90

91

92

93

94

95

96

97

98

99

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

package mold

import (

"errors"

"html/template"

"io"

"io/fs"

"path/filepath"

)

// Engine represents a web page renderer, incorporating a specific layout.

// It provides a flexible way to generate HTML by combining views with a

// predefined layout structure.

//

// The layout defines the overall page structure,

// while views provide the dynamic content.

type Engine interface {

// Render executes the layout template, merging it with the specified view template,

// then writes the resulting HTML to the provided io.Writer.

//

// Parameters:

// w: The writer to which the rendered HTML will be written.

// view: The path of the view template whose content will be injected into the layout.

// data: The data to be made available to both the layout and view templates during rendering.

//

// Returns:

// An error, if any, that occurred during template execution or while writing to the writer.

Render(w io.Writer, view string, data any) error

}

// Config is the configuration for a new [Engine].

type Config struct {

fs fs.FS

layoutRaw string

// options

root optionVal[string]

layout optionVal[string]

exts optionVal[[]string]

funcMap optionVal[template.FuncMap]

}

// Option is a configuration option for a new [Engine].

// It is passed as argument(s) to [New].

type Option func(*Config)

// ErrNotFound is returned when a template is not found.

var ErrNotFound = errors.New("template not found")

// New creates a new [Engine] with fs as the underlying filesystem.

//

// The directory will be traversed and all files matching the configured filename extensions would be parsed.

// The filename extensions can be configured with [WithExt].

//

// At most one layout file would be parsed, if set with [WithLayout]. Others would be skipped.

//

// Layout files are files suffixed (case insensitively) with "layout" before the filename extension.

// e.g. "layout.html", "Layout.html", "AppLayout.html", "app_layout.html" would all be regarded as layout files

// and skipped.

//

// Example:

//

// //go:embed web

// var dir embed.FS

// var engine, err = mold.New(dir)

//

// To use a directory on the filesystem.

//

// var dir = os.DirFS("web")

// var engine, err = mold.New(dir)

//

// To specify option(s) e.g. a custom layout file.

//

// option := mold.WithLayout("layout.html")

// engine, err := mold.New(fs, option)

func New(fs fs.FS, options ...Option) (Engine, error) {

return newEngine(fs, options...)

}

// Must is a helper that wraps a call to a function returning ([Engine], error)

// and panics if the error is non-nil.

//

// Example:

//

// engine := mold.Must(mold.New(fs))

func Must(l Engine, err error) Engine {

if err != nil {

panic(err)

}

return l

}

// With is a helper for specifying multiple options.

//

// Example:

//

// options := mold.With(

// mold.WithLayout("layout.html"),

// mold.WithRoot("web"),

// mold.WithExt("html"),

// )

// engine := mold.New(dir, options)

func With(opts ...Option) Option {

return func(c *Config) {

for _, opt := range opts {

opt(c)

}

}

}

// WithRoot configures the base directory from which template files are loaded.

func WithRoot(subdir string) Option {

return func(c *Config) { c.root = newVal(subdir) }

}

// WithLayout configures the path to the layout file.

func WithLayout(layout string) Option {

return func(c *Config) { c.layout = newVal(layout) }

}

// WithExt configures the filename extensions for the templates.

// Only files with the specified extensions would be parsed.

//

// Default: [".html", ".gohtml", ".tpl", ".tmpl"]

func WithExt(exts ...string) Option {

return func(c *Config) { c.exts = newVal(exts) }

}

// WithFuncMap configures the custom Go template functions.

func WithFuncMap(funcMap template.FuncMap) Option {

return func(c *Config) { c.funcMap = newVal(funcMap) }

}

// HideFS wraps an [fs.FS] and restricts access to files with the specified extensions,

// essentially hiding them.

// This is useful to prevent exposing templates (or sensitive files) when serving

// static assets and templates from the same directory.

//

// Example:

//

// var dir = os.DirFS("web")

// http.Handle("/static", http.FileServerFS(mold.HideFS(dir)))

//

// If no extensions are specified, the default template extensions are used.

//

// Default: [".html", ".gohtml", ".tpl", ".tmpl"]

func HideFS(fsys fs.FS, exts ...string) fs.FS {

if len(exts) == 0 {

exts = defaultExts

}

return &hideFS{

FS: fsys,

exts: exts,

}

}

var _ fs.FS = (*hideFS)(nil)

type hideFS struct {

exts []string

fs.FS

}

// Open implements fs.FS.

func (s *hideFS) Open(name string) (fs.File, error) {

ext := filepath.Ext(name)

if hasExt(s.exts, ext) {

return nil, fs.ErrNotExist

}

return s.FS.Open(name)

}