README
¶
gomponents
gomponents are declarative view components in Go, that can render to HTML5. gomponents aims to make it easy to build HTML5 pages of reusable components, without the use of a template language. Think server-side-rendered React, but without the virtual DOM and diffing.
The implementation is very usable, but the API may change until version 1 is reached.
Check out the blog post gomponents: declarative view components in Go for background.
Features
- Build reusable view components
- Write declarative HTML5 in Go without all the strings, so you get
- Type safety
- Auto-completion
- Nice formatting with
gofmt
- Simple API that's easy to learn and use (you know most already if you know HTML)
- No external dependencies
Usage
Get the library using go get:
go get -u github.com/maragudk/gomponents
The preferred way to use gomponents is with so-called dot-imports (note the dot before the gomponents/html import),
to give you that smooth, native HTML feel:
package main
import (
"net/http"
g "github.com/maragudk/gomponents"
c "github.com/maragudk/gomponents/components"
. "github.com/maragudk/gomponents/html"
)
func main() {
_ = http.ListenAndServe("localhost:8080", http.HandlerFunc(handler))
}
func handler(w http.ResponseWriter, r *http.Request) {
_ = Page("Hi!", r.URL.Path).Render(w)
}
func Page(title, currentPath string) g.Node {
return Doctype(
HTML(
Lang("en"),
Head(
TitleEl(title),
StyleEl(Type("text/css"), g.Raw(".is-active{ font-weight: bold }")),
),
Body(
Navbar(currentPath),
H1(title),
P(g.Textf("Welcome to the page at %v.", currentPath)),
),
),
)
}
func Navbar(currentPath string) g.Node {
return Nav(
NavbarLink("/", "Home", currentPath),
NavbarLink("/about", "About", currentPath),
)
}
func NavbarLink(href, name, currentPath string) g.Node {
return A(Href(href), c.Classes{"is-active": currentPath == href}, g.Text(name))
}
Some people don't like dot-imports, and luckily it's completely optional. If you don't like dot-imports, just use regular imports.
You could also use the provided HTML5 document template to simplify your code a bit:
package main
import (
"net/http"
g "github.com/maragudk/gomponents"
c "github.com/maragudk/gomponents/components"
. "github.com/maragudk/gomponents/html"
)
func main() {
_ = http.ListenAndServe("localhost:8080", http.HandlerFunc(handler))
}
func handler(w http.ResponseWriter, r *http.Request) {
_ = Page("Hi!", r.URL.Path).Render(w)
}
func Page(title, currentPath string) g.Node {
return c.HTML5(c.HTML5Props{
Title: title,
Language: "en",
Head: []g.Node{
StyleEl(Type("text/css"), g.Raw(".is-active{ font-weight: bold }")),
},
Body: []g.Node{
Navbar(currentPath),
H1(title),
P(g.Textf("Welcome to the page at %v.", currentPath)),
},
})
}
func Navbar(currentPath string) g.Node {
return Nav(
NavbarLink("/", "Home", currentPath),
NavbarLink("/about", "About", currentPath),
)
}
func NavbarLink(href, name, currentPath string) g.Node {
return A(Href(href), c.Classes{"is-active": currentPath == href}, g.Text(name))
}
For more complete examples, see the examples directory.
What's up with the specially named elements and attributes?
Unfortunately, there are three main name clashes in HTML elements and attributes, so they need an El or Attr suffix,
respectively, to be able to co-exist in the same package in Go:
form(FormEl/FormAttr)style(StyleEl/StyleAttr)title(TitleEl/TitleAttr)
Documentation
¶
Overview ¶
Package gomponents provides declarative view components in Go, that can render to HTML5. The primary interface is a Node, which has a single function Render, which should render the Node to a string. Furthermore, NodeFunc is a function which implements the Node interface by calling itself on Render. All DOM elements and attributes can be created by using the El and Attr functions. The package also provides a lot of convenience functions for creating elements and attributes with the most commonly used parameters. If they don't suffice, a fallback to El and Attr is always possible.
Index ¶
Constants ¶
const ( ElementType = NodeType(iota) AttributeType )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Node ¶
Node is a DOM node that can Render itself to a io.Writer.
func Attr ¶
Attr creates an attribute DOM Node with a name and optional value. If only a name is passed, it's a name-only (boolean) attribute (like "required"). If a name and value are passed, it's a name-value attribute (like `class="header"`). More than one value make Attr panic. Use this if no convenience creator exists.
func Group ¶ added in v0.7.0
Group multiple Nodes into one Node. Useful for concatenation of Nodes in variadic functions. The resulting Node cannot Render directly, trying it will panic. Render must happen through a parent element created with El or a helper.
type NodeFunc ¶
NodeFunc is render function that is also a Node of ElementType.
func El ¶
El creates an element DOM Node with a name and child Nodes. See https://dev.w3.org/html5/spec-LC/syntax.html#elements-0 for how elements are rendered. No tags are ever omitted from normal tags, even though it's allowed for elements given at https://dev.w3.org/html5/spec-LC/syntax.html#optional-tags If an element is a void kind, non-attribute children nodes are ignored. Use this if no convenience creator exists.
func Textf ¶ added in v0.4.0
Textf creates a text DOM Node that Renders the interpolated and escaped string t.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package assert provides testing helpers.
|
Package assert provides testing helpers. |
|
Package components provides high-level components and helpers that are composed of low-level elements and attributes.
|
Package components provides high-level components and helpers that are composed of low-level elements and attributes. |
|
examples
|
|
|
Package html provides common HTML elements and attributes.
|
Package html provides common HTML elements and attributes. |