When Component

Related documents

• Component Overview
• Component Reference
• Built-in Components
• Template Markup Language (TML) Reference

Table of Contents

• Introduction
• Attributes
• Children
• Usage
• DOM element properties

Introduction

Syntax

tml`
	<When hasChanged=stateVariable1>
		${io => (...)}
	</When>
`
tml`
	<When hasChanged="stateVariable1,stateVariable2">
		${io => (...)}
	</When>
`
tml`
	<When hasChanged=${SV.find(/stateVariable\d+/)}>
		${io => (...)}
	</When>
`

The When component re-evaluates its child, a rendering function, whenever any of the state variables or SvMonitor objects specified by the hasChanged attribute change and then mounts the results.
There should be only one child, and it must be a function.

Attributes

The When component ignores the standard attributes.

• hasChanged
  The hasChanged attribute can accept:

  • A string containing the comma-separated public state variable IDs.
  • A View or Model type StateVar object.
  • An SvMonitor object.
  • A RegExp to match against a state variable ID.
  • A function that takes a single state variable argument. The function returns true if the state variable should be monitored for change
  • An array of a mix of ID strings, View or Model type StateVar objects, and SvMonitor objects.

  The hasChanged attribute will accept the output of SV.find(). Any argument acceptable to SV.find() is acceptable as a value of the hasChanged attribute.

Children

The When component accepts a single child that must be a function. The function is invoked with the following parameter:

• io
  A state variable namespace object that contains all the state variables listed in hasChanged, including state variables from any SvMonitors.

In general, the function should only refer to state variables in the io namespace since changes to those state variables are the only ones that will force the function to be re-evaluated.

The function must return a Template object, a string, a number, a DOM node, a Component object, or an array containing a mix of these types; the same return values as the render() Component instance method.

Usage

Use the When component when the layout of a subtree must change depending on the value of the state variable. Here's an example;

tml`
	<When hasChanged=stateVariable1>
		${io => (
			io.stateVariable1.value > 10
				? tml`<span className=warning>Too large</>`
				: ''
		)}
	</When>
`

The When component will completely discard the generated subtree whenever a change occurs. Use with care if the state variable often changes.

Passing an SvMonitor object instead of a state variable can be useful when used inside another component.
It can also be used to filter when a change is declared by overriding the hasChanged() or isChanged() methods. See SvMonitor Reference.

DOM element properties

The When component is remounted when the hasChanged conditions change.

• If the When child function returns template, the Component renders the template.
• If the When child function returns an empty string, the Component renders a single <span> with the class 'whenMarker'. This allows the Component to keep a placeholder for any future template nodes.