Shaven

Get rid of your old-fashioned face furniture and build sleek templates!

What is Shaven?

Shaven is a DOM building utility and template engine based upon JsonML. This simple markup language lets you easily represent XML/HTML with JSON. Templates are therefore simply Javascript arrays.

All code examples with this icon are editable: edit/

			['#demo',
				['h1#logo', 'Test', {title: 'Test'}],
				['p', 'Some example text'],
				['ul#list.bullets',
					['li', 'item1'],
					['li.active', 'item2'],
					['li',
						['a', 'item3', {href: '#'}]
					]
				]
			]

compiles to

			<div id="demo">
				<h1 id="logo" title="Test">Test</h1>

				<p>Some example text</p>
				<ul id="list" class="bullets">
					<li>item1</li>
					<li class="active">item2</li>
					<li>
						<a href="#">item3</a>
					</li>
				</ul>
			</div>

The first element of the array is the root html element which is going to contain all the child-elements. Those are arrays themselves and are structured as follows:

The first array-element is a string which represents the html-tag (including syntax-sugar)
Other strings are the text-content of the element
One or more Javascript objects contain the attributes
Each sub-array or html-element is a child-element

Installation

On the server you can install Shaven with npm:

			$ npm install shaven

Then require it in your scripts like this:

			var shaven = require('shaven')

In the browser load the browser version of shaven. Get it either from Github or install it with the frontend package manager Bower.

			<script src="shaven.js"></script>

Now you can start using it by passing a JsonML-array to Shaven:

			var shavenObject = shaven(['p', 'some text'])

Insert Methods

There are two different methods to insert a DOM-fragment into the DOM.

Firstly you can inject it straight into the DOM:

			shaven(
				[document.body,
					['div#demo',
						…
					]
				]
			)

Secondly you can assign the Shaven-object to a variable and append the fragment later.

To get the HTML-fragment from the Shaven-object reference it with a [0].

			var shavenObject = shaven(
				['#demo',
					…
				]
			)

			document.body.appendChild(shavenObject[0])

Both compiles to:

			<body>
			<div id="demo">
				…
			</div>
			</body>

Syntax Sugar

Tag

When you omit the html-tag it uses the default div tag. So div#test ist the same as #test

Id

compiles to

			<p id="example">example text</p>

Class

compiles to

			<p class="info">example text</p>

References

When an element with an id is created it automatically gets inserted into the return-object of the shaven function call. Therefore it can get easily referenced later on.

			var shavenObject = shaven(
				[document.body,
					['div#test', 'some text']
				]
			)

			doSomething(shavenObject.test)

Reference an element without an id by using the $ keyword to assign it a reference-name.

			var shavenObject = shaven(
				[document.body,
					['div$test', 'some text']
				]
			)

			doSomething(shavenObject.test)

Properties

All entries of an object will become the attributes. If an object entry is undefined the attribute will be an empty string. If an entry is null or false the attribute will not be created at all.

If the style entry is an object it will automatically get compiled to a string. This is especially useful for working with svgs, where inline styles are still frequently used. Values which are false, null or undefined are deleted from the final style-string.

compiles to

			<p class="new focus" data-lang="de" style="color:red;display:block">
				Hello</p>

Escaping

HTML-strings are escaped by default.

compiles to

			<div>&lt;p&gt;This is &lt;em&gt;HTML&lt;/em&gt;&lt;/p&gt;</div>

To disable escaping add a & at the end of the element-tag string.

compiles to

			<div><p>This is <em>HTML</em></p></div>

Namespaces

Shaven supports different namespaces and makes it therefore possible to create SVGs, MathML and various other XML-based languages.

			shaven(
				['svg', {height: 10, width: 10},
					['circle', {
						cx: 5,
						cy: 5,
						r: 5,
						style: 'fill:green'
					}]
				],
				'http://www.w3.org/2000/svg'
			)

compiles to

			<svg height="10" width="10">
				<circle cx="5" cy="5" r="5" style="fill:green"></circle>
			</svg>

Falsy values

When an element array contains an undefined content-value or no content-value at all, the element will get compiled with an empty body.

When an element contains a null or a false value, the element won't get compiled at all. This is handy for disabling parts of templates or ensuring that no empty container-elements get rendered. (A true value does therefore not change the compilation.)

Subarrays

An array which consists exclusively of subarrays will get merged into the current array

compiles to

			<p>
				<span>One</span>
				<span>Two</span>
				<span>Three</span>
			</p>

Templates

In order to create reusable templates it's best practice to create a function which accepts a data object, inserts the data into the JsonML array and returns it.
Finally iterate over the contacts and use one of the two insertion methods to build the DOM with the contacts.

			function contactTemplate(data) {
				return ['div.contact',
					['h1', data.name],
					['dl',
						['dt', 'Age:'],
						['dd', data.age],
						['dt', 'Mobile:'],
						['dd', data.mobile],
						['dt', 'Email:'],
						['dd', data.email]
					]
				]
			}

			contacts.forEach(function(contact){
				shaven([
					document.body,
					contactTemplate(contact)
				])
			})

Callback Functions

You can provide a callback function, which will be called after the element has been created, with the element as the only argument. This functionality is especially suited to add event-listeners.

			function doSomething(element) {
				alert(element + ' was created')
			}

			shaven(
				[document.body,
					['div', doSomething]
				]
			)