Templating Syntax

Summary

Templates allow you to define your view markup, data bindings, and event handlers declaratively. A declarative approach means that by default, they are written in an easily parseable, easily translatable format. As technology improves, the templates can be translated into new formats in the future if necessary.

Defining a view

Views should each be defined in their own directory under your project's src directory. So to make a new view, make a new directory under src that is TitleCased, indicating the class name of your view. For example, ToggleButton.

A view file is simply an html file that gets parsed and translated into a TypeScript class. The root element must have a js-type attribute, which defines the classname.

src/ToggleButton/ToggleButton.html:

<div js-type="ToggleButton"></div>

Binding to states

State data is sent to the view as a json object containing name/value pairs that will be mixed into the view's viewModel. For example:

var toggleButton = new ToggleButton();

toggleButton.setData({ isToggled: true });
console.alert(toggleButton.viewModel.isToggled); // alerts 'true'

In your template, you can use the js-bind attribute to indicate a binding of the viewModel state to the effect it has on the view. In the following example, I bind the text value of the button to the viewModel property "name", and the className "toggled" to the viewModel property "isToggled".

<button
    js-type="ToggleButton"
    js-bind="text:name, className.toggled:isToggled">
</button>

js-bind attribute options

A js-bind statement by default binds to the view's viewModel scope. The format of the js-bind syntax is:

[destinationType].[destinationSubType]:[sourcePath]<,[...]>

Where destinationType can be:

• text - binds the text value of the element to the source value.

• html - binds the html value of the element to the source value. Careful, this is not encoded.

• attr - binds an attribute (provided as the subType) to the source value. This is the default binding type if no destinationType is provided. (e.g. binding "href:foo" will bind the href attribute to foo.)

• className - toggles a given class name (provided as the subType) based on the source value's truthiness. (e.g. binding "className.foo:bar" will enable the class "foo" on the element if the source "bar" resolves as truthy.

The sourcePath defaults to the viewModel scope.

You can use a dot notation to drill into a specific value within the viewModel:

<div js-bind="text:item.name"></div>

If you want to bind to child view scopes, you can use the $ syntax, which indicates to "start at the view to resolve the scope" rather than the viewModel.

For example, you can bind to a child view's "isToggled" viewModel state:

<div js-type="MyView" js-bind="className.isHighlighted:$toggleButton.isToggled">
    <toggle-button js-name="toggleButton" />
</div>

Handling events

Repeat blocks

TBD

Conditionals

TBD

Nesting views