Data Binding

Scripting allows you to read, modify, and subscribe to changes in View Model properties, as well as create new View Model instances at runtime.

For a conceptual overview of View Models and how they drive your graphic, see View Models & Data Binding.

View Models

There are three ways that a script can gain access to a View Model and its properties:

• Accessing View Models through Context
• Data binding a View Model as an input
• Data binding view model properties to inputs

Context

The init lifecycle function includes a context parameter that gives you access to your view models. This allows you to read values (strings, enums, lists, etc.), set values, fire triggers, listen for triggers, and subscribe to value changes.

In addition to view models, Context gives you access to named assets and update scheduling.

type MyNode = {}

function init(self: MyNode, context: Context): boolean
  -- Get the view model from the node's immediate context.
  local vmi = context:viewModel()

  -- Get the root view model
  local rootVmi = context:rootViewModel()

  -- Get the view model from the parent node.
  local parentDC = dc:parent()
  local parentVmi = dc:viewModel()
end

return function(): Node<MyNode>
  return {
    init = init,
  }
end

View Models as Inputs

You can create a Script Input that can be bound to a view model. This allows you to read values (strings, enums, lists, etc.), set values, fire triggers, listen for triggers, and subscribe to value changes.

type MyNode = {
  -- This input expects a view model instance of type Character
  character: Input<Data.Character>
}

function init(self: MyNode, context: Context): boolean
  local vmi = self.character
end

return function(): Node<MyNode>
  return {
    init = init,
    -- Initialize with `late()` so the value
    -- can be provided by the editor at runtime.
    character = late(),
  }
end

For a detailed explanation, see View Models Inputs.

Binding Inputs

If you only need to read, not set view model properties, you can data bind view model property values to script inputs. For more information see Data Binding Inputs.

Nested View Models

To reference a nested view model, use getViewModel.

local vmi = context:viewModel(),
local dateVmi = vmi:getViewModel('dateViewModel')

Reading and Setting Properties

The following methods allow you to reference view model properties:

• getNumber
• getTrigger
• getString
• getBoolean
• getColor
• getList
• getViewModel
• getEnum

local vmi = context:viewModel()

if vmi then
  -- Get a reference to the score property from the view model
  local score = vmi:getNumber('score')
  if score then
    -- Read the score
    print(score.value)

    -- Set the score
    score.value = 100
  end

  -- Get a reference to the myTrigger property from the view model
  local myTrigger = vmi:getTrigger('myTrigger')
  if myTrigger then
    -- Fire the trigger
    mytrigger:fire()
  end
end

Listening for Property Changes

Add a Listener

Use addListener to listen for triggers or changes to view model properties.

type MyNode = {}

function handleHoursChanged()
  print('hours changed!')
end

function handleTriggerFired()
  print('Fire!')
end

function init(self: MyNode, context: Context): boolean
  local vmi = context:viewModel()

  local hours = vm:getNumber('hours')
  if hours then
    -- handleHoursChanged is called whenever the hours value changes
    hours:addListener(handleHoursChanged)
  end

  local trigger = vm:getTrigger('triggerProperty')
  if trigger then
    -- handleTriggerFired is called whenever the trigger is fired
    trigger:addListener(handleTriggerFired)
  end

  return true
end

return function(): Node<MyNode>
  return {
    init = init,
  }
end

Remove a Listener

Always remove listeners when they are no longer needed to avoid memory leaks.

type MyNode = {}

function init(self: MyNode, context: Context): boolean
  local vmi = context:viewModel()

  if not vmi then
    print('No view model found')
    return false
  end

  local hours = vmi:getNumber('hours')
  if hours then
    local function handleHoursChanged()
      print('hours changed!')

      -- Remove the event listener
      hours:removeListener(handleHoursChanged)
    end

    -- handleHoursChanged is called whenever the hours value changes
    hours:addListener(handleHoursChanged)
  end

  return true
end

return function(): Node<MyNode>
  return {
    init = init,
    hours = late(),
    trigger = late(),
  }
end

Creating a View Model Instance

Coming soon