README
¶
Vecty is a React-like library for GopherJS so that you can do frontend development in Go instead of writing JavaScript/HTML/CSS.
Features
- Share frontend and backend code.
- Write everything in Go -- not JS/HTML/CSS!
- XSS protection: unsafe HTML must be explicitly denoted as such.
- Reusability: share components by making Go packages that others can import!
Goals
- Simplicity
- Keep things as simple as possible to understand for newcomers.
- Designed from the ground up to be easily mastered (like Go)!
- Performance
- As efficient as possible, make it clear what each operation in your webpage will do.
- Same performance as just using plain JS/HTML/CSS.
- Composability
- Nest components to form your entire user interface, seperate them logically as you would any normal Go package.
Current Status
Vecty is currently considered to be an experimental work-in-progress.
- APIs will change.
- The scope of Vecty is only ~80% defined currently.
- There are a number of important open issues.
For a list of projects currently using Vecty, see the doc/projects-using-vecty.md file.
Community
- Join us in the #gopherjs and #vecty channels on the Gophers Slack!
Changelog
See the doc/CHANGELOG.md file.
Documentation
¶
Index ¶
- func AddStylesheet(url string)
- func RenderBody(body Component)
- func Rerender(c Component)
- func SetTitle(title string)
- type Applyer
- func Attribute(key string, value interface{}) Applyer
- func Class(class ...string) Applyer
- func Data(key, value string) Applyer
- func Key(key interface{}) Applyer
- func MarkupIf(cond bool, markup ...Applyer) Applyer
- func Namespace(uri string) Applyer
- func Property(key string, value interface{}) Applyer
- func Style(key, value string) Applyer
- func UnsafeHTML(html string) Applyer
- type ClassMap
- type Component
- type ComponentOrHTML
- type Copier
- type Core
- type Event
- type EventListener
- type HTML
- type KeyedList
- type Keyer
- type List
- type MarkupList
- type MarkupOrChild
- type Mounter
- type RenderSkipper
- type Unmounter
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddStylesheet ¶
func AddStylesheet(url string)
AddStylesheet adds an external stylesheet to the document.
func RenderBody ¶
func RenderBody(body Component)
RenderBody renders the given component as the document body. The given Component's Render method must return a "body" element.
func Rerender ¶
func Rerender(c Component)
Rerender causes the body of the given Component (i.e. the HTML returned by the Component's Render method) to be re-rendered.
If the Component has not been rendered before, Rerender panics. If the Component was previously unmounted, Rerender is no-op.
Rerender operates efficiently by batching renders together. As a result, there is no guarantee that a calls to Rerender will map 1:1 with calls to the Component's Render method. For example, two calls to Rerender may result in only one call to the Component's Render method.
Types ¶
type Applyer ¶
type Applyer interface {
// Apply applies the markup to the given HTML element or text node.
Apply(h *HTML)
}
Applyer represents some type of markup (a style, property, data, etc) which can be applied to a given HTML element or text node.
func Attribute ¶
Attribute returns an Applyer which applies the given attribute to an element.
In most situations, you should use Property function, or the prop subpackage (which is type-safe) instead. There are only a few attributes (aria-*, role, etc) which do not have equivalent properties. Always opt for the property first, before relying on an attribute.
func Class ¶
Class returns an Applyer which applies the provided classes. Subsequent calls to this function will append additional classes. To toggle classes, use ClassMap instead. Each class name must be passed as a separate argument.
func Key ¶
func Key(key interface{}) Applyer
Key returns an Applyer that uniquely identifies the HTML element amongst its siblings. When used, all other sibling elements and components must also be keyed.
func Namespace ¶
Namespace is Applyer which sets the namespace URI to associate with the created element. This is primarily used when working with, e.g., SVG.
See https://developer.mozilla.org/en-US/docs/Web/API/Document/createElementNS#Valid Namespace URIs
func Property ¶
Property returns an Applyer which applies the given JavaScript property to an HTML element or text node. Generally, this function is not used directly but rather the prop and style subpackages (which are type safe) should be used instead.
To set style, use style package or Style. Property panics if key is "style".
func Style ¶
Style returns an Applyer which applies the given CSS style. Generally, this function is not used directly but rather the style subpackage (which is type safe) should be used instead.
func UnsafeHTML ¶
UnsafeHTML is Applyer which unsafely sets the inner HTML of an HTML element.
It is entirely up to the caller to ensure the input HTML is properly sanitized.
It is akin to innerHTML in standard JavaScript and dangerouslySetInnerHTML in React, and is said to be unsafe because Vecty makes no effort to validate or ensure the HTML is safe for insertion in the DOM. If the HTML came from a user, for example, it would create a cross-site-scripting (XSS) exploit in the application.
The returned Applyer can only be applied to HTML, not vecty.Text, or else a panic will occur.
type ClassMap ¶
ClassMap is markup that specifies classes to be applied to an element if their boolean value are true.
type Component ¶
type Component interface {
// Render is responsible for building HTML which represents the component.
//
// If Render returns nil, the component will render as nothing (in reality,
// a noscript tag, which has no display or action, and is compatible with
// Vecty's diffing algorithm).
Render() ComponentOrHTML
// Context returns the components context, which is used internally by
// Vecty in order to store the previous component render for diffing.
Context() *Core
// contains filtered or unexported methods
}
Component represents a single visual component within an application. To define a new component simply implement the Render method and embed the Core struct:
type MyComponent struct {
vecty.Core
... additional component fields (state or properties) ...
}
func (c *MyComponent) Render() vecty.ComponentOrHTML {
... rendering ...
}
type ComponentOrHTML ¶
type ComponentOrHTML interface {
// contains filtered or unexported methods
}
ComponentOrHTML represents one of:
Component *HTML List KeyedList nil
An unexported method on this interface ensures at compile time that the underlying value must be one of these types.
type Copier ¶
type Copier interface {
// Copy returns a copy of the component.
Copy() Component
}
Copier is an optional interface that a Component can implement in order to copy itself. Vecty must internally copy components, and it does so by either invoking the Copy method of the Component or, if the component does not implement the Copier interface, a shallow copy is performed.
type Core ¶
type Core struct {
// contains filtered or unexported fields
}
Core implements the Context method of the Component interface, and is the core/central struct which all Component implementations should embed.
type EventListener ¶
type EventListener struct {
Name string
Listener func(*Event)
// contains filtered or unexported fields
}
EventListener is markup that specifies a callback function to be invoked when the named DOM event is fired.
func (*EventListener) Apply ¶
func (l *EventListener) Apply(h *HTML)
Apply implements the Applyer interface.
func (*EventListener) PreventDefault ¶
func (l *EventListener) PreventDefault() *EventListener
PreventDefault prevents the default behavior of the event from occurring.
See https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault.
func (*EventListener) StopPropagation ¶
func (l *EventListener) StopPropagation() *EventListener
StopPropagation prevents further propagation of the current event in the capturing and bubbling phases.
See https://developer.mozilla.org/en-US/docs/Web/API/Event/stopPropagation.
type HTML ¶
type HTML struct {
// contains filtered or unexported fields
}
HTML represents some form of HTML: an element with a specific tag, or some literal text (a TextNode).
func Tag ¶
func Tag(tag string, m ...MarkupOrChild) *HTML
Tag returns an HTML element with the given tag name. Generally, this function is not used directly but rather the elem subpackage (which is type safe) is used instead.
func Text ¶
func Text(text string, m ...MarkupOrChild) *HTML
Text returns a TextNode with the given literal text. Because the returned HTML represents a TextNode, the text does not have to be escaped (arbitrary user input fed into this function will always be safely rendered).
type KeyedList ¶
type KeyedList struct {
// contains filtered or unexported fields
}
KeyedList is produced by calling List.WithKey. It has no public behaviour, and List members are no longer accessible once wrapped in this stucture.
type Keyer ¶
type Keyer interface {
// Key returns a value that uniquely identifies the component amongst its
// siblings. The returned type must be a valid map key, or rendering will
// panic.
Key() interface{}
}
Keyer is an optional interface that a Component can implement in order to uniquely identify the component amongst its siblings. If implemented, all siblings, both components and HTML, must also be keyed.
Implementing this interface allows siblings to be removed or re-ordered whilst retaining state, and improving render efficiency.
type MarkupList ¶
type MarkupList struct {
// contains filtered or unexported fields
}
MarkupList represents a list of Applyer which is individually applied to an HTML element or text node.
It may only be created through the Markup function.
func Markup ¶
func Markup(m ...Applyer) MarkupList
Markup wraps a list of Applyer which is individually applied to an HTML element or text node.
func (MarkupList) Apply ¶
func (m MarkupList) Apply(h *HTML)
Apply implements the Applyer interface.
type MarkupOrChild ¶
type MarkupOrChild interface {
// contains filtered or unexported methods
}
MarkupOrChild represents one of:
Component *HTML List KeyedList nil MarkupList
An unexported method on this interface ensures at compile time that the underlying value must be one of these types.
func If ¶
func If(cond bool, children ...ComponentOrHTML) MarkupOrChild
If returns nil if cond is false, otherwise it returns the given children.
type Mounter ¶
type Mounter interface {
// Mount is called after the component has been mounted, after the DOM node
// has been attached.
Mount()
}
Mounter is an optional interface that a Component can implement in order to receive component mount events.
type RenderSkipper ¶
type RenderSkipper interface {
// SkipRender is called with a copy of the Component made the last time its
// Render method was invoked. If it returns true, rendering of the
// component will be skipped.
//
// The previous component may be of a different type than this
// RenderSkipper itself, thus a type assertion should be used no action
// taken if the type does not match.
SkipRender(prev Component) bool
}
RenderSkipper is an optional interface that Component's can implement in order to short-circuit the reconciliation of a Component's rendered body.
This is purely an optimization, and does not need to be implemented by Components for correctness. Without implementing this interface, only the difference between renders will be applied to the browser DOM. This interface allows components to bypass calculating the difference altogether and quickly state "nothing has changed, do not re-render".
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package elem defines markup to create DOM elements.
|
Package elem defines markup to create DOM elements. |
|
Package event defines markup to bind DOM events.
|
Package event defines markup to bind DOM events. |
|
example
|
|
|
todomvc/store/storeutil
Package storeutil contains a ListenerRegistry type.
|
Package storeutil contains a ListenerRegistry type. |