Sparky(selector)

Sparky('#id');

Mount selected element as a Sparky template.

Sparky('#id', data);

Mount selected element as a template and render it immediately using data as scope.

var sparky = Sparky('#id');

The constructor returns a sparky object that is both an array-like object of DOM nodes and a pushable stream of data.

methods.

.push(data)

Push data into sparky to be rendered as template scope on the next animation frame.

.stop()

Unmount the template, disconnecting its tags from scope updates. Tags and nodes are left in the DOM in their stopped state.

Tip: you could remove them with sparky.forEach(dom.remove).

.then(fn)

Call fn after sparky is stopped.

properties.

.status

Sparky is in one of two states: "active" or "done".

Sparky templates

Sparky templates are made of plain old HTML enhanced with functions and tags.

functionparameterpathtransform

The import function imports 'package.json' and pushes it into scope, then Sparky takes the 'version' property, prepends it with 'v' and replaces the tag with the text. The result?

Latest: {[version|prepend:'v']}

sparky-fn

Functions, declared in the sparky-fn attribute, are run before the template is mounted. They have two parts, a name followed by 0 or more parameters.

Functions are view-controllers with responsibility for getting data and spitting out scopes, and can listen to and mutate nodes. They're powerful. You're going to want to write your own. But first, let's have a look at some built-ins.

Getting scope

We have already seen the import function in action. load also loads data, but with a subtle difference: where import makes a single request and creates a single data object (per url), distributing it to other imports, load makes makes a new request and creates a new data object each time.

The find function takes a JS path (in dot notation) and looks for data at that path in the global object (window).

The get function takes a JS path and looks for data at that path in the current scope.

Composing templates

Sparky has a function for cloning and inserting a template into a node: the template function. It performs the import only when the first scope is available, so it can be used to provide initial content.

Looping over arrays

The third function worth a special mention is each. It copies and remounts the node for each object found in scope, where scope must be an array or array-like.

Result:

{[.]}

functions.

each

Where scope is an array or array-like, duplicates the element for each object in scope.

<ul sparky-fn="import:example.json">
<li sparky-fn="get:path.to.array each">{[name]}</li>
</ul>
  • {[name]}

global:path

Get an object from path in the global scope (window) and push it to the template scope.

<pre sparky-fn="global:location">
href: {[href]}
</pre>
href: {[href]}

get:path

Gets the value of path of the current scope.

<pre sparky-fn="import:example.json get:path.to.array[0]">
name: {[name]}
id: {[id]}
</pre>
name: {[name]}
id:   {[id]}

import:url

Looks in the object cache for data for that url, or loads JSON data from the url and caches it, pushing that data to the template scope.

template:url

Replaces the content of the element with the cloned, mounted content of the template referenced by url. Usually this is a hashref for a <template id="ref"> in the same document. Sparky will also import the contents of other elements or elements in external documents.

Note that the initial content of the element is left untouched until the template has data and is ready to render.

<pre sparky-fn="import:package.json template:#example-template">
Loading...
</pre>
<template id="example-template">
My name is {[title]} and I'm {[version]}!
</template>
Loading...

log

For debugging. Logs node and scopes to the console.

request-on-submit

Sends a request on form submit, where the type of request is determined by the current state of the method attribute and the URL determined by the action attribute of the form. The JSON data payload is the current scope.

prevent-on:type

Calls .preventDefault() on events of type.

stop

Stops sparkifying the element. No more functions are run, and the contents of the element are not parsed.

Use stop to ignore blocks of static HTML inside a Sparky template.

{[tag]}

Tags, found in the attributes and content of the node and its descendants, are rendered with values from the scope.

{[name|truncate:6|uppercase]}

A tag may have three parts. A path, followed by any number of pipe-seperated transfoms and their parameters.

transforms.

get:name

Get property name from value.

invoke:name,params

Returns the result of invoking method name with params on an object.

is:n

Returns the (boolean) result of a strict equality check between n and value.

type

Returns typeof value.

map:name,arguments

Maps array using transform name with arguments.

filter:name,arguments

Filters array using transform name with arguments.

append:string

Appends string to value.

lowercase

Converts value to lowercase.

match:regex

Returns result of matching value against regex.

matches:regex

Tests value against regex.

postpad:n,string

Appends string to value to output a string of length n.

prepad:n,string

Prepends string to value to output a string of length n.

prepend:string

Prepends string to value.

slugify

Outputs slug of value.

translate

Looks up value in Sparky.translations and outputs it. If a translation does not exist, warns the console and outputs the original value.

uppercase

Converts value to uppercase.

decibels

Converts value to decibels.

degrees

Converts a numeric value from radians to degrees.

denormalise:min,max

Converts numeric values in the range 0-1 to the range min-max.

See also normalise:min,max.

floatformat:n

Converts numeric values to strings with n decimal places.

interpolate:coord1,coord2,...

Given a number of coordinates of the form [x, y], performs linear interpolation to transform input (x) values to output (y) values.

localise:n

Returns localised number string with n decimal places.

normalise:min,max

Converts numeric values in the range min-max to the range 0-1.

See also denormalise:min,max.

pluralise:str1,str2,lang

Takes a number and outputs str1 or str2 depending on whether that number is considered plural in lang. Currently there are 4 languages supported out-of-the-box – EN, DE, FR, IT – but it is easy to add more.

date:format

Maps either JSON date strings or JS date objects to human-readable date strings in a format defined by format, where format describes the output in a Django/PHP-style date format strings.

Deprecated, will remain supported as an add-on.

dateformat:format

Maps either JSON date strings or JS date objects to human-readable date strings in a format defined by format

formatdate:formattime,timeZone,locale

Converts Date, ISO8601 date string or UNIX time (in seconds) to string in format.

formatdate:format

Converts ISO time string, a number (in seconds) or the UTC time values of a Date object to string in format.

yesno:value1,value2

Returns value1 where value is truthy, otherwise value2.

Sparky options

Sparky.attributeFn

A string that names the fn attribute. The default is 'sparky-fn'.

Sparky.attributePrefix

A string that prefixes attributes where Sparky looks for tags. The default is 'sparky-'.

Sparky looks for tags in prefixed attributes before trying unprefixed attributes. There are three main cases where this is useful:

  • In IE, where Sparky cannot mount the style attribute (because IE does not provide access to the original text of the attribute), use sparky-style.
  • For the value attribute, where you don't want to interfere with the browser's autocompletion or default values, use sparky-value.
  • Where you want to provide different html content to browsers that fail to run Sparky.

Hello