Data Binding

How SA5's databinding works

SA5 supports binding data in two ways;

• Element binding replaces the entire content of the element. It is also element-type-aware, so that for example binding to a text element replaces the inner text content, while binding to a form input element sets the value of that input element.

• Content binding selectively binds data to the content within an element, using handlebars style macro-expressions of the format {{ data-path }}. This is useful for e.g. rich text elements and descriptive text where you only wish to replace specific words. It is also designed to support CMS content.

Currently, all binding is specific to a Data Item, which always resolves to a text value. In the future, lists, tables, objects and media elements may be added.

Data-Binding is read-only. It's designed to integrate information into your site from various internal and external sources - but not to update those data sources.

wfu-bind = ( data-path )

Apply the wfu-bind attribute to any element which you want to replace the full content of with your data-bound content.

You can place wfu-bind on;

• Simple content elements;

  • Text elements

  • Paragraph elements

  • Heading elements

• Form elements, including;

  • INPUT elements

  • SELECT elements - case sensitive

  • TEXTAREA elements

  • CHECKBOX elements

Complex elements, including sliders, tabs, and rich text blocks don't make sense here, since there isn't a clear point for content-binding a simple string value. Some elements such as images and video elements may be supported in the future.

The data-path value can be any valid SA5 data path that identifies a data point.

Examples;

wfu-bind=$query.name

wfu-bind=+events.item.slug

wfu-bind=$local.test

Here's an example of an element that is bound to the current user's custom data, specifically a the custom data you've named link-field.

Setting defaults. The value will only be applied if one is found, therefore you can specify a default value by setting initial content for the element itself. Here we have ... but it can be whatever you prefer.

wfu-bind-content = (data-context)

SA5's contextual binding is used to provide macro expansion support within the content of a plain-text or rich-text template element.

Templates are text marked up with field that contain SA5 data paths, like this;

{{ $user.data.link-field }}

When the template is processed, these are expanded.

For certain data sources such as $db, it's common to specify a data context on the element. This allows the context to change to e.g. a collection list item before the content binding occurs.

Data Paths

At the center of data binding is SA5's data paths, which are formatted strings that specifically identify the data that you want to bind.

A data path is a dot-notated string with several parts;

<data-source type>.<data-source-name>.<object-id>.<field-id>

Path Root	Abbr	Data Source Type	Data Path Examples
$user	@	User object	$user.name - The current user's name @data.birthdate - A custom User field named birthdate
$cookie		Cookie	$cookie.foo - The cookie named foo
$local		Local storage	$local.myval - A Webstorage Local-stored value named myval.
$session		Session storage	$session.myval - A WebStorage Session-stored value named myval.
$query	?	Query string	$query.foo - The query param named foo. ?foo - The query param named foo.
$db	+	Database	$db.my-db.my-record.my-field - Describes a value in an SA5 Datasource.
$global		Site global vars	$global.year - The year property of a Global object you've created.

Abbreviations are shorthand for the full datasource type name, so e.g. $user.name and @name are considered identical.

SEO Notes

Bound data may or may not be picked up by search indexing bots. Google is generally good at executing script and indexing the page after modification, however you will need to test this yourself.

Deprecated Notes

Ignore the notes below, we're reviewing and integrating during migration.

Dynamic DSD References, using Data-Binding Context

You can specify fixed reference items using a fully-qualified DSD like this, however if the template is in a dynamic context such as a collection list or collection page, SA5 allows you to set the context for partial DSDs to operate in.

The way this works is to assign these attributes to the parent of your wfu-bind-content tagged element.

• wfu-bind-dsn = The data source name, e.g. my-data.

• wfu-bind-item-id = The data source item ID, e.g. row-28.

These context elements can be on the same element as your wfu-bind-content tag, but they can also be on any ancestor element. They also do not need to be on the same element. This gives you different flexibilities

Data Binding can be applied to;

• Any text element

• Rich text elements, to {{ expand }} macro content

• Form input fields, specifically

  • Text fields, to set the current text input

  • Textarea fields, to set the current text input

  • Checkboxes, to set the checked/unchecked state

  • Select fields, to select the current item