README
¶
Humble/View
Version 0.3.1
A small library for organizing view-related code written in pure go which compiles to javascript via gopherjs. View includes a View interface and some helper functions for operating on views (e.g. Append, Replace, Remove, AddEventListener, etc.). View works great as a stand-alone package or in combination with other Humble packages.
View is written in pure go. It feels like go, follows go idioms when possible, and compiles with the go tools. But it is meant to be compiled to javascript and run in the browser.
Browser Support
View works with IE9+ (with a polyfill for typed arrays) and all other modern browsers. View compiles to javascript via gopherjs and this is a gopherjs limitation.
View is regularly tested with the latest versions of Firefox, Chrome, and Safari on Mac OS. Each major or minor release is tested with IE9+ and the latest versions of Firefox and Chrome on Windows.
Installation
Install view like you would any other go package:
go get github.com/go-humble/view
You will also need to install gopherjs if you don't already have it. The latest version is recommended. Install gopherjs with:
go get -u github.com/gopherjs/gopherjs
Quickstart Guide
What is a View?
The View interface consists of only two methods:
type View interface {
Render() error
Element() dom.Element
}
Element expects an element object from the gopherjs dom bindings package.
The Default View
If you want, you can embed DefaultView to satisfy the Element method.
When you call Element on DefaultView, if there is not already an element
assigned to the view, it creates a <div> element for you. DefaultView also
provides a SetElement method which you can call to set the element manually.
DefaultView is pretty simple, so here's the full implementation:
type DefaultView struct {
el dom.Element
}
func (v *DefaultView) Element() dom.Element {
if v.el == nil {
// Create an element if there is not one already
v.el = document.CreateElement("div")
}
return v.el
}
func (v *DefaultView) SetElement(el dom.Element) {
v.el = el
}
If you are using an embedded DefaultView, you will often need to work with a
pointer to your View type (e.g. *TodoView instead of TodoView). This is
because the Element method of DefaultView requires a pointer receiver.
Defining the Render Method
DefaultView doesn't define a Render method, so if you are embedding you still
need to define one. Here's an example of a TodoView:
type TodoView struct {
title string
isCompleted bool
view.DefaultView
}
func (todo TodoView) Render() {
todo.Element().SetInnerHTML(`"<div class="todo-item" <span class="title"></span>`)
}
The Render method is really flexible and the view package is templating language agnostic.
For simpler views, it is totally fine to use string literals or fmt.Sprintf. However,
for more comlicated views, we highly recommend temple,
a small wrapper around go's builtin template/html package that is designed to work with
gopherjs and humble.
Using the Helper Functions
The view package provides a number of helper functions for inserting and removing views
from the DOM. The goal is to eliminate the need to use github.com/gopherjs/gopherjs/js
or the dom package directly, at least for the most
common use cases. Here's a list of all the helper functions:
You can also view all the documentation on godoc.org.
Testing
View uses the karma test runner to test the code running in actual browsers.
The tests require the following additional dependencies:
- node.js (If you didn't already install it above)
- karma
- karma-qunit
Don't forget to also install the karma command line tools with npm install -g karma-cli.
You will also need to install a launcher for each browser you want to test with, as well as the
browsers themselves. Typically you install a karma launcher with npm install -g karma-chrome-launcher.
You can edit the config file at karma/test-mac.conf.js or create a new one (e.g. karma/test-windows.conf.js)
if you want to change the browsers that are tested on.
Once you have installed all the dependencies, start karma with karma start karma/test-mac.conf.js (or
your customized config file, if applicable). Once karma is running, you can keep it running in between tests.
Next you need to compile the test.go file to javascript so it can run in the browsers:
gopherjs build karma/go/view_test.go -o karma/js/view_test.js
Finally run the tests with karma run karma/test-mac.conf.js (changing the name of the config file if needed).
If you are on a unix-like operating system, you can recompile and run the tests in one go by running
the provided bash script: ./karma/test.sh.
Contributing
See CONTRIBUTING.md
License
View is licensed under the MIT License. See the LICENSE file for more information.
Documentation
¶
Overview ¶
Package view is a small library for organizing view-related code written in pure go which compiles to javascript via gopherjs (https://github.com/gopherjs/gopherjs). View includes a View interface and some helper functions for operating on views (e.g. Append, Replace, Remove, AddEventListener, etc.). View works great as a stand-alone package or in combination with other Humble packages (https://github.com/go-humble).
Version 0.3.1 ¶
For the full source code, a getting started guide, and more information visit https://github.com/go-humble/view.
Index ¶
- func Append(parent View, child View)
- func AppendToEl(parent dom.Element, child View)
- func Hide(v View)
- func InsertBefore(v View, before View)
- func InsertBeforeEl(v View, before dom.Element)
- func Remove(v View)
- func Replace(new View, old View)
- func ReplaceEl(new View, old dom.Element)
- func Show(v View)
- type DefaultView
- type EventListener
- type View
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Append ¶
Append appends child to a parent View. More specifically, it appends child.Element() to parent.Element() using the appendChild method from the DOM API.
func AppendToEl ¶
AppendToEl appends child to a parent element. More specifically, it appends child.Element() to parent using the appendChild method from the DOM API.
func Hide ¶
func Hide(v View)
Hide hides the view from the DOM by adding the inline style "display:none". Hide is safe to use even if you have other attributes and inline styles. It has no effect if the view is already hidden.
func InsertBefore ¶ added in v0.3.0
InsertBefore inserts v directly before before. More specifically, it inserts v.Element() before before.Element() using the insertBefore method from the DOM API.
func InsertBeforeEl ¶ added in v0.3.0
InsertBeforeEl inserts v directly before before. More specifically, it inserts v.Element() using the insertBefore method from the DOM API.
func Remove ¶
func Remove(v View)
Remove removes the view from the DOM entirely. It does not destory the Element propery of the view.
func Replace ¶
Replace replaces an old View with new. More specifically, it replaces old.Element() with new.Element() using the replaceChild method from the DOM API.
Types ¶
type DefaultView ¶
type DefaultView struct {
// contains filtered or unexported fields
}
DefaultView provides an implementation of the Element method of the View interface, and is meant to be embedded. When Element is called on DefaultView (or a struct that embeds DefaultView), it will create a new div element if an element has not yet been assigned to the view.
func (*DefaultView) Element ¶
func (v *DefaultView) Element() dom.Element
Element satisfies View.Element. If the view does not already have an element assigned, it creates a new div element (but does not insert it into the DOM). If the view already has an element assigned, it returns the element.
func (*DefaultView) SetElement ¶
func (v *DefaultView) SetElement(el dom.Element)
SetElement can be used to manually set the element for a view.
type EventListener ¶ added in v0.2.0
type EventListener struct {
// contains filtered or unexported fields
}
EventListener represents a listener attached to a single type of event on one or more elements.
func AddEventListener ¶ added in v0.2.0
func AddEventListener(view View, eventType string, selector string, listener func(dom.Event)) *EventListener
AddEventListener addds an event listener to one or more child elements of the view. selector is a query selector which starts at the view's root element. AddEventListener will add an event listener to *all* child elements that match the given selector. listener is a function that will be called when the event is triggered. Because of the way gopherjs works, listener cannot be a blocking function. See https://github.com/gopherjs/gopherjs#goroutines for more information. If the view is re-rendered, you may need to remove the old listeners and call AddEventListener again.
func (*EventListener) Elements ¶ added in v0.2.0
func (eventListener *EventListener) Elements() []dom.Element
Elements returns a slice of all elements that the event listener is attached to.
func (*EventListener) Remove ¶ added in v0.2.0
func (eventListener *EventListener) Remove()
Remove removes the event listener from all elements.
Source Files