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]}

find:path

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

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.

load:url

Loads JSON data from url and pushes it to the template scope. A new data object is created per load request.

html

When scope is a string, replaces the content of the current element with scope by setting .innerHTML.

template:url

Replaces the content of the element with the cloned, mounted content of the element referenced by url. Usually this is a hashref for a <template> in the same document, but Sparky will also import the contents of nodes in external documents.

Note that the original content of the element is never mounted.

log

For debugging. Logs node and scopes to the console.

post-on-submit

Posts the content of a form as JSON.

prevent: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.

append:string

Appends string to value.

lowercase

Converts value to lowercase.

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.

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

timeformat:format

Converts Date or JSON time string to string in format.

yesno:value1,value2

Returns value1 where value is truthy, otherwise value2.

Hello