Television is an experimental, minimal implementation of the virtual DOM approach to view construction that aims to integrate with the web platform rather than abstract it away. This library is a thin wrapper around the virtual-dom library, and it focuses on allowing you to define HTML 5 custom elements with declarative markup. Efficient DOM access can be ensured in a manner that cooperates with other libraries by assigning an external DOM update scheduler. Other concerns, such as defining and observing a data model and listening for DOM events, are left to other libraries. The examples in this README use an embedded DSL syntax, but it should be possible to target this library with a JSX preprocessor for integrated support for HTML literals.
tv = require 'television'tvbuildTagFunctions'task-list'tvregisterElement 'task-list': ->TaskList id: "on-deck"for task in @tasksli className: 'task'input type: 'checkbox'checked: taskdonetasktitle
In the example above, we define a
task-list element via
tv.registerElement. The prototype template we provide contains a
::render method, which returns a virtual DOM fragment describing the view. To create an element:
taskListElement = documentcreateElement'task-list'taskListElement.tasks =title: "Write code"done: truetitle: "Feed cats"done: falsetitle: "Clean room"done: falsedocumentbodyappendChildtaskListElement
To update an element:
taskListElementtaskspush title: "Do Homework"done: falsetaskListElementupdate
Custom elements have a
refs hash that can be populated with references to DOM nodes. Use a
ref attribute on any element in your
render method to automatically maintain a reference to its node.
tvregisterElement 'user-card': ->UserCardimg href: useravatarURLref: 'avatarImage'span userfullNameuserCard = documentcreateElement'user-card'userCardrefsavatarImage # --> reference to avatar image DOM element
Elements registered via
registerElement can define a few lifecycle hooks:
::didCreateCalled after the element is created but before it has content.
::didAttachCalled after the element is attached and rendered.
::didDetachCalled after the element is detached but before its content is cleared.
::readSyncCalled after the element is updated. If you need to read the DOM, you can safely do so here without blocking a DOM write. Do not write to the DOM in this method!
Assigning a DOM Scheduler
You should assign a DOM update scheduler on Television that's responsible for coordinating DOM updates among all components. The scheduler should have an
updateDocument and a
readDocument method. If you're using this library within Atom, you can assign
atom.views as the scheduler:
tv = require 'television'tvsetDOMScheduleratomview
To unregister a custom element, call
.unregisterElement on the element constructor. After doing so, you'll be able to register another element with the same name.
UserCard = tvregisterElement 'my-element': -> MyElement"Hello World"# Later...UserCardunregisterElement
Under the hood, we dynamically reassign prototypes to make this possible, since the current DOM APIs don't support unregistering elements.