View-script NPM

view-script

forget querying! create state-driven user interfaces
write feature-rich view logic in only a handful of lines!
your dom intelligently updates based on changes to your view's state
confuse your coworkers and friends with your weird comment code!
4k gzipped -- no dependencies

installing

(it's not actually on npm yet -- coming soon)

You can install it with npm, then use it with browserify:

npm install view-script

var app = require('view-script')

getting started

<p>
	Hallo, <!--= put name -->.
</p>

See that funny comment? That's viewscript in action, where both put and name are keys in our view's data. Every time we change the value of either of those keys, that line of viewscript gets re-evaluted.

app.def('name', 'Bob Ross')

app.def(key, value) is used to update data in your view. The 'put' function is built-in functionality, and will print your data into the dom.

output

<p>
	Hallo, Bob Ross
</p>

How many things does Bob Ross have to do? Let's tell him.

<p>
	Hallo, <!--= put name -->.
	You have <!--= put (length items) --> things to do.
</p>

app.def('items', [])

output

<p>
	Hallo, Bob Ross.
	You have 0 things to do.
</p>

length is another built-in that just counts the elements of an array.

viewscript uses s-expressions because they're fast to parse and declarative. Every function in viewscript is prefixed, so instead of 1 + 2 + 3 you say add 1 2 3. Instead of console.log('hi there'), you simply say log 'hi there'.

Let's add a couple todo items for Bob.

app.push('items', {content: 'Brush hair', done: false})
app.push('items', {content: 'Mix paints', done: false})

output

<p>
	Hallo, Bob Ross.
	You have 2 things to do.
</p>

As soon as we pushed to 'items', the view updated without any extra work. That's because it knew that 'items' was changed, so re-evaluated all lines of viewscript that depend on 'items.'

Let's list each item for Bob Ross

<p>
	Hallo, <!--= put name -->.
	You have <!--= put (length items) --> things to do.

	<ul>
		<li>
			<!--= repeat items -->
			<!--= put content -->
		</li>
	</ul>
</p>

output

<p>
	Hallo, <!--= put name -->.
	You have <!--= put (length items) --> things to do.

	<ul>
		<li> Brush hair </li>
		<li> Mix paints </li>
	</ul>
</p>

The repeat function will duplicate an element for each item in a given array. Inside the repeat-ed element, everything is scoped to that element, so we can simply call put content and it'll print the content of each to-do item.

As a general rule, every viewscript function that messes with an element will affect its parent element. In the case of the few nodes without children like <img> or <input>, simply place viewscript directly after them to affect them.

So our repeat function repeats an <li> for every element inside `items'.

view function reference

functions that modify the node

name	type	action	example
repeat	Array	repeat the parent node for each element in the array	`(repeat user_listing)`
show_if	Value (predicate to test)	test a Value; if true, set display to ''; if false, set display to 'none'	`(show_if public_profile)`
hide_if	Value(predicate to test)	test a Value; if false, set display to 'none'; if true set display to ''	`(hide_if anonymous_profile)`
attr	name val	set an attribute to a value on the parent node	`(attr 'href' profile_link)`
remove_attr	name	remove the attribute from the parent node	`(remove_attr 'href')`
toggle_attr	name	remove the attribute from the parent node	`(toggle_attr`data-selected`id)`
class	val	set the class on the parent node as the value (will append to the node's class list)	`(class 'active')`
remove_class	val	remove the class from the parent node's class list, if it is present	`(remove_class 'active')`
toggle_class	val	either remove the class from the parent node's class list if present, or add the class if it is absent	`(toggle_class 'active')`

conditionals

name	type	action	example
if	Value Expr Expr	if the predicate is true, evaluate the first expression, else evaluate the second expression (optional)	`(if active_account (class 'active') (class 'inactive'))`
unless	Value Expr Expr	the inverse of `if`	`(unless confirmed_account (class 'confirmed'))`

data manipulation

name	type	action	example
def	String Value	set the key to the given value in the view's data	`(set 'x' 1)`
push	Value String	push a value into an array in the view, given by the array's key name	`(push 1 'numbers')`
concat	Value String	push a value into an array in the view, given by the array's key name	`(push 1 'numbers')`
pop	String	push a value into an array in the view, given by the array's name	`(pop 'user_list')`
remove	Value String	find and remove the value from the array inside the view, given by the array's name	`(remove user 'user_list')`

That's it! In only a dozen lines we have a functioning to-do list.

patterns & tips

Think of your view -- that is, your HTML and your viewscript -- as only the description of the layout and behavior of your data.
Any complicated logic -- like ajax, list reduction, or detailed data processing -- can still live in the JS, not the view.
Logic that's related to an element (like changing a class or setting an attribute) should live in your DOM. Any logic that has no relation to a particular element can live in your JS.

Why S-Expressions?

Reasons for using S-Expressions:

It's very fast and simple to parse
It really serves declarative-style coding -- in fact, it's not really possible to write procedural viewscript
It makes it clear that the view expressions are not javascript
It is visually scannable as distinct from html, but still reads somewhat similarly.

Why comments?

Traditional mustache-style text interpolation is less efficient: we have to check every character of every textContent in the entire templated text. And unless you've jumped through some hoops to hide those mustaches, users will often see a flash of braces and weird text on pageload, before your data is fetched.

With comments (or another special node), we only check the first character of each comment node. We can also use traditonal dom traversal very easily to find viewscript lines. It is also very visually distinct from the html tags. Finally, we don't have to hide or mess with the original viewscript nodes -- we can leave them be and re-evaluate them to our heart's content. So it's simpler.