The Kdu Instance

Creating a Kdu Instance

Every Kdu application starts by creating a new Kdu instance with the Kdu function:

var vm = new Kdu({
  // options
})

Although not strictly associated with the MVVM pattern, Kdu’s design was partly inspired by it. As a convention, we often use the variable vm (short for ViewModel) to refer to our Kdu instance.

When you create a Kdu instance, you pass in an options object. The majority of this guide describes how you can use these options to create your desired behavior. For reference, you can also browse the full list of options in the API reference.

A Kdu application consists of a root Kdu instance created with new Kdu, optionally organized into a tree of nested, reusable components. For example, a todo app’s component tree might look like this:

Root Instance
└─ TodoList
   ├─ TodoItem
   │  ├─ TodoButtonDelete
   │  └─ TodoButtonEdit
   └─ TodoListFooter
      ├─ TodosButtonClear
      └─ TodoListStatistics

We’ll talk about the component system in detail later. For now, just know that all Kdu components are also Kdu instances, and so accept the same options object (except for a few root-specific options).

Data and Methods

When a Kdu instance is created, it adds all the properties found in its data object to Kdu’s reactivity system. When the values of those properties change, the view will “react”, updating to match the new values.

// Our data object
var data = { a: 1 }

// The object is added to a Kdu instance
var vm = new Kdu({
  data: data
})

// Getting the property on the instance
// returns the one from the original data
vm.a == data.a // => true

// Setting the property on the instance
// also affects the original data
vm.a = 2
data.a // => 2

// ... and vice-versa
data.a = 3
vm.a // => 3

When this data changes, the view will re-render. It should be noted that properties in data are only reactive if they existed when the instance was created. That means if you add a new property, like:

vm.b = 'hi'

Then changes to b will not trigger any view updates. If you know you’ll need a property later, but it starts out empty or non-existent, you’ll need to set some initial value. For example:

data: {
  newTodoText: '',
  visitCount: 0,
  hideCompletedTodos: false,
  todos: [],
  error: null
}

The only exception to this being the use of Object.freeze(), which prevents existing properties from being changed, which also means the reactivity system can’t track changes.

var obj = {
  foo: 'bar'
}

Object.freeze(obj)

new Kdu({
  el: '#app',
  data: obj
})

<div id="app">
  <p>{{ foo }}</p>
  <!-- this will no longer update `foo`! -->
  <button k-on:click="foo = 'baz'">Change it</button>
</div>

In addition to data properties, Kdu instances expose a number of useful instance properties and methods. These are prefixed with $ to differentiate them from user-defined properties. For example:

var data = { a: 1 }
var vm = new Kdu({
  el: '#example',
  data: data
})

vm.$data === data // => true
vm.$el === document.getElementById('example') // => true

// $watch is an instance method
vm.$watch('a', function (newValue, oldValue) {
  // This callback will be called when `vm.a` changes
})

In the future, you can consult the API reference for a full list of instance properties and methods.

Instance Lifecycle Hooks

Each Kdu instance goes through a series of initialization steps when it’s created - for example, it needs to set up data observation, compile the template, mount the instance to the DOM, and update the DOM when data changes. Along the way, it also runs functions called lifecycle hooks, giving users the opportunity to add their own code at specific stages.

For example, the created hook can be used to run code after an instance is created:

new Kdu({
  data: {
    a: 1
  },
  created: function () {
    // `this` points to the vm instance
    console.log('a is: ' + this.a)
  }
})
// => "a is: 1"

There are also other hooks which will be called at different stages of the instance’s lifecycle, such as mounted, updated, and destroyed. All lifecycle hooks are called with their this context pointing to the Kdu instance invoking it.

Don’t use arrow functions on an options property or callback, such as created: () => console.log(this.a) or vm.$watch('a', newValue => this.myMethod()). Since an arrow function doesn’t have a this, this will be treated as any other variable and lexically looked up through parent scopes until found, often resulting in errors such as Uncaught TypeError: Cannot read property of undefined or Uncaught TypeError: this.myMethod is not a function.

← Introduction Template Syntax →

Guide

Essentials

Components In-Depth

Transitions & Animation

Reusability & Composition

Tooling

Scaling Up

Internals

Migrating

Meta

The Kdu Instance

Creating a Kdu Instance

Data and Methods

Instance Lifecycle Hooks