Lava Documentation
Lava is an open source javascript framework that allows you to build responsive web applications very quickly, while adhering to MVC best practices. Lava is compact, powerful and flexible. Not only does it give you awesome features like data binding, templates and routing, it also gives your application structure.Objects (Lava.Object)
At the heart of Lava is the object. An object in lava is a structure with properties and behaviors that can
be bound to the DOM. A Lava object is basically a normal javascript object with additional functionality.
You define an object by calling Lava.Object() and passing a javascript object as an argument like so:
var Car = Lava.Object({ make: 'Ford', model: 'Mustang', year: 2013 });Now, to create other instances of the Car object, you simply call the clone() method.
var myCar = Car.clone();The myCar object now has all of the properties, values, and behavior that the Car object contains. You can also pass additional properties to the new object, or even overwrite existing properties.
var myCar = Car.clone({ color: 'blue', year: 2011 });Adding additional properties or behavior to an existing Lava object is made trivial through the use of the extend() method.
myCar.extend({ color: 'blue' });Along with properties, Lava objects can contain behaviors. For example, let's say that we needed a way to obtain a summary of information about the car. This can be done easily by adding a method to the object to return a summary.
myCar.extend({ summary: function () { return myCar.make + ' - ' + myCar.model + ' - ' + myCar.year + ' - ' + myCar.color; } });Setting or getting properties on an object works exactly how you would expect.
// set a property myCar.color = 'red'; // get a property var make = myCar.make; var summary = myCar.summary();
Controllers (Lava.Controller)
A Controller is similar to a Lava Object. One difference is that a controller is meant to be singular. You cannot clone a controller.
Controllers in Lava are used to add behavior to the web application. They serve as the glue between the model (Lava.Object) and the
view (the DOM). Creating a Controller is identical to creating an Object.
var PersonController = Lava.Controller({ getPeople: function () { ... }, addPerson: function (e, args) { ... }, deletePerson: function (e, args) { ... } });Extending a Controller is identical to extending an Object.
PersonController.extend({ getCount: function () { ... } });
Computed Properties (Lava.Computed)
Computed Properties in Lava make it possible to create a property on an object whose value is dependent on other properties. Each time a dependent property changes, the computed property will change as well.
A simple example of a computed property is the following, in which we compute the full name using two properties.
A simple example of a computed property is the following, in which we compute the full name using two properties.
var Person = Lava.Object({ firstName: 'Terry', lastName: 'Phillips', fullName: Lava.Computed(function () { return this.firstName + ' ' + this.lastName; }) });Accessing the computed property is a bit different than a normal property. To do so, you use the get() method on the property.
var fullName = Person.fullName.get();Anytime the first or last properties change, it will update any bindings tied to the fullName property. As you can see, there is no need to specify which dependencies to watch for the computed property. Lava can determine which properties the computed property is dependent on automatically, in most cases. If you have a complex dependency, or just want to make certain properties dependencies, Lava allows you to manually declare the dependencies like so:
var Person = Lava.Object({ firstName: 'Terry', lastName: 'Phillips', fullName: Lava.Computed('Person.firstName', function () { return this.firstName + ' ' + this.lastName; }) });
Arrays
In Lava, arrays are added to objects just as other scalar properties are, but when you add an array
property to an object, additional functionality is given to the array to support binding. Unlike other
data binding frameworks, there is no messy sntax with Lava arrays. Let's look at a simple example of
adding an array property to an Object.
var Person = Lava.Object({ contacts: [] });Yes, it's that simple! To manipulate the array, there are intuitive methods like add(), addAt(), remove(), and removeAt().
// Let's assume that Contact is a valid Lava Object // example of add() Person.contacts.add(Contact.clone()); // example of addAt(). We will add an Object at index 0. Person.contacts.addAt(0, Contact.clone()); // example of remove() Person.contacts.remove(myContact); // example of removeAt(). We will remove the Object at index 0. Person.contacts.removeAt(0);
Binding & Templates
One of the most powerful features available in Lava is Binding. Lava allows you to bind object properties
directly to the UI, easily and efficiently. The nice part about lava is that there is no additional code
required to bind existing DOM elements to Lava Objects. Bindings are automatically resolved when the document
is ready. It is also just as easy to bind a new set of DOM elements manually at any time. There are two
main ways to bind your objects to the UI, basic bindings and template bindings.
Here is an example of basic bindings using our Person object.
Let's see the same thing using a template.
Here is an example of basic bindings using our Person object.
var Person = Lava.Object({ firstName: 'Terry', lastName: 'Phillips', fullName: Lava.Computed('Person.firstName', function () { return this.firstName + ' ' + this.lastName; }) });Here, we bind the properties of the Person object to separate DOM elements.
<input type="text" data-bind="{value: Person.firstName}" /><br> <input type="text" data-bind="{value: Person.lastName}" /><br> <h2 data-bind="{text: Person.fullName}"></h2>Let's look at the binding expression on the first input to get an idea of what is going on here. We use the data-bind attribute to tell Lava that we need binding done to this element. The binding expression uses the same syntax as javascript object literal syntax. So, if you know how to create an object literal, you know how to write Lava binding expressions. Inside of the data-bind attribute, we specify an object literal with the following format: {<attribute>: <property path|binding expression object>}. In this case, the attribute that we are binding to is value, and the property path is Person.firstName.
Let's see the same thing using a template.
<script type="text/html" id="person-template"> <input type="text" data-template="{value: Person.firstName}" /><br> <input type="text" data-template="{value: Person.lastName}" /><br> <h2 data-template="{text: Person.fullName}"></h2> </script> <div data-bind="{template: 'person-template'}"></div>In the template example, instead of directly binding property values to the DOM elements, we bind a template to a DOM element by using the template binding property and assign it a value equal to the templates id. Inside of the template, we just have the html with the bindings to the properties on the object. One very important thing to remember when using templates is that you must use the data-template attribute when binding as opposed to the data-bind.