Rikulo Blog

CouchClient

Henri Chen — Tue, 07 May 2013 00:00:00 +0200

CouchClient is our attempt to access NoSQL document database. It is a Couchbase client library for Dart language. Just finished the first version and we would like to talk a bit about how to use it. If you are interested in the behind-the-hood implementation details, here are the source code in Github.

Our implementation of Couchbase client in Dart language is inspired by the official Couchbase Java Client Library 1.1 thus the APIs are quite similar to those ones found in official Java client. However, we adapted only asynchronous version of those Java APIs because they fit to the asynchronous natural of Dart's dart:io module. Also, we tends to limit the number of APIs and arguments in each API such that the learning experience of using this Couchbase client is as simple and easy as possible.

Cannot guarantee all APIs will not be changed afterward. There are still a lot of functions that we have not implemented. Couchbase reconfiguration and automatic rebalance are still on the way and this is an implementation of early stage. Asynchronous programming is quite an interesting topic and we anticipate that the code would be refactored several times. Some APIs might have to be added/deleted/changed accordingly.

Nevertheless, following we will introduce the most basic way to use this Dart client first, namly, by explaining a "Hello Couchbase" example and a "Query Couchbase" example. You are welcome to try them. By the way, the examples used in this article are shamelessly stolen from those of the official Java client's with minor modification and make it a Dart version. All credits shall go to the ones that writes the Java examples.

Enough chichat. Let us go straight to the classic "Hello Couchbase".

Before Everything

Install a Couchbase Server if you have not had one

Get and Install Couchbase Server. Remember to load the sample bucket beer-sample.

Install the CouchClient

Like all other Dart libraries, simply add a dependency line in pubspec.yaml of your application:

dependencies:
  couchclient:

Then run the Pub Package Manager (comes with the Dart SDK):

pub install

Or if you want to try the stuff still in development, add this to your pubspec.yaml of your application:

dependencies:
  couchclient:
    git: git://github.com/rikulo/couchclient.git

Hello Couchbase!

Following is a typical use pattern of the CouchClient:

Create a client connecting to a cluster of Couchbase servers asynchronously.
When the client is ready, access the Couchbase cluster with APIs.

HelloCouch.dart

import "dart:uri";
import "dart:utf";
import "dart:async";
import "package:couchclient/couchclient.dart";

void main() {
  // Connect to server per the provided URIs
  // Here assume your Couchbase Server is installed on localhost
  // Use "default" bucket with no password
  CouchClient.connect([Uri.parse("http://localhost:8091/pools")], "default", "")
  // When client is ready, access the database
  .then((client) => access(client))
  // Catch all possible errors/exceptions
  .catchError((err) => print('Exception: $err'));
}

// The unique document id of the document
final String DOC_ID = "beer_Wrath";

// The JSON encoded document
final String VALUE =
  '{"name":"Wrath","abv":9.0,'
  '"type":"beer","brewery_id":"110f1a10e7",'
  '"updated":"2010-07-22 20:00:20",'
  '"description":"WRATH Belgian-style ",'
  '"style":"Other Belgian-Style Ales",'
  '"category":"Belgian and French Ale"}';

Future access(CouchClient client) {
  // Do a set
  return client.set(DOC_ID, encodeUtf8(VALUE))
  // Check if set succeeded and show message
  .then((ok) => print(ok ? "Set Succeeded" : "Set failed"))
  // Then get the value back by document id
  .then((_) => client.get(DOC_ID))
  // Check if get data equals to set one
  .then((val) => decodeUtf8(val.data) == VALUE)
  // Show message
  .then((ok) => print(ok ? "Get Succeeded" : "Get failed"))
  // Close the client
  .then((_) => client.close());
}

Let us go through the above example.

CouchClient.connect(List<Uri> servers, String bucket, String password);

This is the entry point of all CouchClient operations. It accepts URIs of servers in a cluster, the target bucket name, and the password to login the bucket, and then returns a Future that will give the client connecting to the specified bucket. After the connection is created successfully(the Future is completed), you are allowed to use the client.

Someone might ask why we have to specify ALL servers in the cluster in the connect() API. Actually, you don't have to. It is more of an insurance to avoid if the specified server happens to be down. That is, the servers are only for booting up the connection to the cluster. Either one of them is connected successfully the client would be connected to the whole cluster. In other words, you can specify only one server URI in the cluster if you like; as long as the specified server is active and ready to be connected.

OK. After the client is ready, you can call the access APIs as your wish. Here in the example we call set() to store a document and then get() to retrieve the document we just set. And check if the value read back equals to the one we wrote into database.

Following is the set() API.

Future<bool> set(String docID, List<int> document)

Use it to persist a document with the provided document id. The returned Future would give true if the set() operation is completed successfully:

Following is the get() API.

Future<GetResult> get(String docID);

Use it to read back a document per the provided document id. The returned Future would provide detail information about the document including document id, flags, CAS version, and data in a GetResult object when the get operation is completed.

Actually almost all APIs in CouchClient are asynchronous and will return a Future to the proper results. Here we also makes access() application function to returns a Future such that we can chain the Futures together and catch all errors in one place(see main() function) during the whole process.

The result of this "Hello Couch" program should be

Set Succeeded
Get Succeeded

If you need full source code, here it is.

Query Couchbase

In previous example, we have demonstrated the way to set and get document by document id. In this example, we will focus on how to query documents per the given map function and Query conditions on JSON-based documents.

To query Couchbase, you would have to define map functions in JavaScript language and add them into the design document of the database. Later on, you can use these predefined map functions to query the database and retrieve documents that match the query conditions.

QueryCouch.dart

import 'dart:async';
import 'dart:utf';
import 'dart:uri';
import 'dart:json' as json;
import 'package:memcached_client/memcached_client.dart';
import 'package:couchclient/couchclient.dart';

void main() {
  // Connect to server per the provided URIs
  // Here assume your Couchbase Server is installed on localhost
  // Use "beer-sample" bucket with no password
  CouchClient
  .connect([Uri.parse("http://localhost:8091/pools")], "beer-sample", "")
  //when client is ready, query the database
  .then((client) => queryByView(client))
  .catchError((err) => print("$err"));
}

Let us go through the above example.

CouchClient.connect(List<Uri> servers, String bucket, String password);

Again, this is the entry point of all CouchClient operations. It accepts URIs of servers in a cluster, the target bucket name, and the password to login the bucket, and then returns a Future that will give the client connecting to the specified bucket. After the connection is created successfully(the Future is completed), we call queryByView(client) application function to access the map function.

Following is the definition of queryByView() function.

/**
 * Read a document whose name is "Wrath" using the map function.
 */
Future queryByView(CouchClient client) {
  // Prepare map function with name "by_name"
  ViewDesign vd = new ViewDesign("by_name", MAP_FUNC);
  // Prepare design document with the name "beer"
  DesignDoc dd = new DesignDoc("beer", views: [vd]);

  // Add the design document "beer" with "by_name" map function into database
  return client.addDesignDoc(dd)
  // Get map function "by_name" from design document "beer"
  .then((_) => client.getView("beer", "by_name"))
  // When ViewDesign function is ready
  .then((view) {
    // Configurate Query object
    Query query = new Query();
    // Retreive the beer with name "Wrath"
    query.key = "Wrath";
    // Include associated document as well
    query.includeDocs = true;

    // Query the server and return the ViewResponse
    return client.query(view, query);
  })
  // Process the query results
  .then((results) {
    for (ViewRow row in results.rows) {
      // Convert List<int> to String
      String data = decodeUtf8(row.doc.data);
      // Print out some infos about the document
      print("The Key is: ${row.key}");
      print("The full document is : ${data}");

      // Convert it back to an object with json
      Map bm = json.parse(data);
      Beer beer = new Beer.fromMap(bm);

      print("Hi, my name is ${beer.name}!");
    }
  })
  // Close the client
  .then((_) => client.close());
}

This function creates a map function by_name, stores it into design document beer and then add the design document into the database. The map function can then be used in query database document per the query conditions. In the example, the map function would retrieve only those documents with type equals to beer(as filtered by the map function) and with name equals to Wrath(as constrained by the Query object). To conclude, the query will return documents whose type is beer and whose name is Wrath.

Following is the map function(in JavaScript) used in this example. It checks each document and emit only those documents has a document name with type equals to beer.

String MAP_FUNC = '''
function (doc, meta) {
  if (doc.type && doc.name && doc.type == "beer") {
    emit(doc.name, meta.id); //emit document name as the key and document id as the value
  }
}''';

Following is the code snippet that shows how to prepare a map function in design document and add it into database.

// Prepare map function with name "by_name"
ViewDesign vd = new ViewDesign("by_name", MAP_FUNC);
// Prepare design document with the name "beer"
DesignDoc dd = new DesignDoc("beer", views: [vd]);
// Add the design document "beer" into database
return client.addDesignDoc(dd)
// ...

As long as the map function is added into the database, you can read the map function back per the design document name and map function name and then use it to query the database per the given Query condition.

// Configurate Query object
Query query = new Query();
// Retreive the beer with name "Wrath"
query.key = "Wrath";
// Include associated document as well
query.includeDocs = true;
// Query the server and return the ViewResponse
return client.query(view, query);

The client.query() method would return documents in a ViewResponse object that match the provided map function and the Query conditions. You can then process the results accordingly.

Note that we make queryByView() function to returns a Future such that we can chain the Futures together and catch all errors in one place(see main() function) during the whole process. This is a typical practice to handle asynchronous error handing.

The result of this "Query Couch" program should be

The Key is: Wrath
The full document is : {"name":"Wrath","abv":8.2,"ibu":0.0,"srm":0.0,... // omitted
Hi, my name is Wrath!

If you need full source code, you can find them here.

Summary

Though we show only the set(), get(), and query() APIs in this article, they did demonstrate the typical usage of the client's APIs. There are other APIs that will help you handle things more than create, retrieve, update, delete(CRUD), and query documents. Take a look of the CouchClient class to find details.

Happy trying and do provide us feedbacks!

Bootjack and DQuery

Simon Pai — Fri, 03 May 2013 00:00:00 +0200

Bootjack is a project porting Twitter Bootstrap into Dart's world. Following Bootstrap's original implementation, Bootjack was built upon DQuery, a Dart porting of jQuery. Both libraries are unique, popular, and very useful in the Javascript community; we hope Dartisans can enjoy the powers of them in the Dart world as well.

Bootjack

Bootstrap offers abundant style resources and many UI components. With its implementation concentrated on CSS as much as possible, its integration is the least invasive. Bootjack hopes to bring these values into the Dart world.

Coverage

There are roughly more than 20 components in Bootstrap. Many of them only involve simple DOM structure combined with CSS rules, requiring even no Javascript. Those "pure CSS" components are naturally ready to use in Bootjack along with the CSS assets from Bootstrap:

Breadcrumbs
Pagination
Progress bars
Thumbnails
Labels and badges
etc.

On the other hand, there are 12 Bootstrap components requiring Javascript to attain their full functionality. In Bootjack, we are planning to translate all of them, gradually. So far, the following are done:

Alert
Button
Dropdown
Modal
Tab

In the future, we are looking forward to translate the rest of them:

Affix
Collapse
Carousel
Popover
Scrollspy
Tooltip
Typeahead

Usage

First of all in your HTML file, you need to include the CSS resource:

<head>
    ...
    <link rel="stylesheet" href="packages/bootjack/css/bootstrap-2.3.1.css">
</head>

Most of the functions in Bootjack components are automatic -- you only need to give the right CSS class on DOM elements and call a global function to register.

For example, a Dropdown button component is prepared by giving the following HTML snippet:

<button class="btn dropdown-toggle" data-toggle="dropdown">
    <span class="caret"></span>
</button>
<ul class="dropdown-menu">
    <li><a href="#">Menu Item #1</a></li>
    <li><a href="#">Menu Item #2</a></li>
    <li><a href="#">Menu Item #3</a></li>
</ul>

With the following global registration in Dart:

void main() {
    Dropdown.use();
}

That's right. All you need to do in Dart is to tell Bootjack you are using Dropdown components. You can also progammatically access and manipulate the Dropdown:

Dropdown dd = Dropdown.wire(element);
dd.toggle();

Check more examples and the API reference for more features. Also, you can read the reference of Bootstrap.

DQuery

DQuery is a porting of jQuery in Dart, which transports jQuery's the event system and many useful features to Dart.

Design Philosophy

The jQuery library consists of many benefits, including:

DOM element query, including basic selector query and enhanced traversing functions
Wrapper of element collection, which grants you batch operation and null safe navigation
Element/CSS attribute value normalization
Event system, including name space, delegate, trigger, enhanced event object, etc.
Simplified DOM API

and more.

Thanks to Dart, we already have the some of the values from DOM Query, simplified API, and normalization. However, we think jQuery's element wrapper and event system still have a great potential for Dartisans. In addition to being a cornerstone of Bootjack implementation, the purpose of DQuery is to leverage what we already have with Dart and bring in some other great values of jQuery we yet to have in the Dart world. In the current version of DQuery, we explicitly focus on the values of event system and element wrapper.

In DQuery, to work with Dart smoothly, we keep the API as strong-typed as possible. Dart and jQuery convensions are also taken into consideration.

Coverage

Among the categories of jQuery API, the following are included in the current version of DQuery:

Core: element wrapper
Traversing: good leverage with element wrapping
Data: prerequisite for Event
Event: event system
addClass/removeClass/hasClass/toggleClass: commonly used
show/hide/toggle: commonly used

The following are not included yet:

Attributes, Dimentions, CSS
Manipulation
Event alias
Effect
Ajax
Deferred Object (same as Dart's Future)

Usage

You can create a query object by selector. With context provided, the query will be based on different element.

// selects all elements containing 'active' in CSS class
ElementQuery $elems = $('.active');

// selects all descendant elements of div containing 'active' in CSS class
ElementQuery $elems = $('.active', div);

It implements List.

$('.active')[0];
$('.active').isEmpty;
for (Element e in $('.active')) { ... }

Create another query object with traversing API, including find, closest, parent, children.

$('.active').closest('ul');
$('#myDiv').find('a.btn');

Manipulate selected elements.

$('.active').removeClass('active');
$('.fade').hide();

$('#myBtn').on('click', (DQueryEvent e) {
    ...
});
$('#myBtn').trigger('click', data: 'my data');

There are query objects of HtmlDocument and Window too.

DocumentQuery $doc = $document();
WindowQuery $win = $window();

Check the API reference for more features.

Future Development

Bootstrap and jQuery are two important cornerstones in the Javascript community. We hope Bootjack and DQuery can offer the same benefits to the Dartisans and open up brand new possibilities for even more exciting UI libraries in the Dart community.

Explore our website to figure out our other projects including Rikulo UI for web/mobile frontend, Rikulo Stream for the backend, and the soon-coming Couchclient as Couchbase 2.0 client in Dart! Join us on Google+!

Rikulo's todoMVC

Simon Pai — Thu, 20 Dec 2012 00:00:00 +0100

What's todoMVC

todoMVC is a collection of a sample "Todo" web application implemented by different MVC frameworks, for helping interested users to compare and inspect them. It includes many popular frameworks, like Backbone.js, KnockoutJS, AngularJS, and other interesting constructions, like GWT, Dart (Vanilla), etc.

Rikulo's implementation

Here is the demo of Rikulo's implementation.

You can explore the source code.

Elements in MVC

We are going to explore the crutial elements in an MVC framework.

Data Flow

An MVC framework usually need to take care of two kinds of data flow: rendering flow and update flow.

Rendering Flow: Page Request -> ... -> Model -> ... -> UI Rendering
Update Flow: UI Event -> ... -> Model -> ... -> UI Update

Rendering flow is about how DOM elements are initially loaded, and mostly involves view representation. We will explore this part in the next section.

Update flow is about how model and view communicate through controller (or, view model/binder/presenter/etc.), which pretty much determines the paradigm (MVC/MVVM/MVB/MVP/etc.) of the entire framework. We are not going to introduce each possibility in details, but you can surf the source code of the following implementations to get a quick understanding of each paradigm.

Backbone.js: MVC, with data event
AngularJS: MVVM
GWT implementation of todoMVC: MVP
Dart Web UI: model driven view (MDV)

Most MVC/MVVM frameworks encourage user to separate view, model, and controller, so user can focus on views and models individually, and then think about putting them together with controllers.

In Rikulo, model, view, and controller are kept as separate files. Views are represented by XML, models can be arbitrary classes, and controllers are classes extended from a base class. As shown in the code snippet below, view files concern purely views, containing no mixture of business logic.

Model

Rikulo does not have any restriction on the type of model -- it can be any plain Dart object. For example, in our todoMVC implementation, the model is as simple as:

class Todo {
    String title;
    bool completed;

    Todo(this.title, [this.completed = false]);

    // JSON, for local storage persistence //
    Todo.fromJson(Map m) : this(m["title"], m["completed"]);
    Map toJson() => { "title": title, "completed": completed };
}

However, if you prefer using data event like in Backbone.js, Rikulo also supports it via DataModel. You can register callbacks to listen to data events, which is fired when model is updated. For details, please refer to our documentation.

View

To render UI from a page request, some component-based frameworks introduce their own ways of specifying UI layout, to relief user from bizzare Swing-like component construction.

Rikulo uses UXL, an XML language, to help you specifying widget layout. Rikulo UXL compiler will then compile the xml file to a human-readable dart class which builds up the corresponding component tree for you.

UXL contains some neat features to make UI declaration friendly:

Expression Language (EL), to access variables from template caller
Flow control unit, such as for loop and conditional operator
Template declaration

Here is a snippet of UXL in todoMVC implementation:

<View tag="ul" id="todo-list" layout="type: linear; orient: vertical; spacing: 0">
    <Apply forEach="t in app.todos">
        <View tag="li" class="${t.completed ? 'completed' : ''}" 
        control="new TodoItemControl(app, t)">
            <View class="show">
                <CheckBox class="toggle" value="${t.completed}" 
                on.change="toggleCompleted" />
                <TextView class="title" text="${t.title}" on.dblclick="editTitle" />
                <Button class="destroy" on.click="destroy" />
            </View>
            <TextBox class="edit" profile="width: ignore; height: ignore" 
            value="${t.title}" on.blur="submitTitle" on.keyUp="enterTitle" />
        </View>
    </Apply>
</View>

You can also read the full source code.

Due to the need of rendering a collection of items, view modularization is a necessity in a MVC framework. Component-based frameworks have a natural layer for packing DOM elements into a view unit. However, frameworks with DOM-based view (i.e. pure HTML) may also introduce a thin layer of view unit to provide the right granularity of views.

When combined with the need of view representation, this part is often assisted by template definition utilities. For instance,

Backbone.js: uses Underscore.js to define HTML template
Dart Web UI: has a template infrastructure that implements Web Components standard

In Rikulo, a view file will be compiled into a dart class, as an reusable template object. Thus it naturally covers the demand of template definition.

Controller

In Rikulo, controller connects view to model, and handles the business logic between them. The controller listens to DOM event, manipulates model directly, and then update DOM elements. For example,

class TodoItemControl extends Control {

    final TodoAppControl _appc;
    final Todo _todo;

    TextBox get input => view.query("TextBox.edit");
    TextView get label => view.query("TextView.title");

    TodoItemControl(this._appc, this._todo);

    // event handlers, which listen to DOM events (specified in view file) //
    void toggleCompleted(ChangeEvent<bool> event) {
        _appc.increaseCompleted(_todo.completed = event.value);
    }
    void editTitle(ViewEvent event) {
        view.classes.add("editing");
        input.node.focus();
    }
    void enterTitle(DomEvent event) {
        if (event.keyCode == ENTER_KEY)
            input.node.blur();
    }
    void submitTitle(ViewEvent event) {
        final String title = input.value.trim();
        if (!title.isEmpty) {
            label.text = _todo.title = title;
            _appc.save();
            view.classes.remove("editing");
        } else 
            destroy();
    }
    void destroy([ViewEvent event]) => _appc.destroy(_todo);
}

Having controller taking care of business logic, view and model can be kept clean to a maximal extent.

Conclusion

Rikulo, as an MVC framework, provides model data events, UXL view representation, and controller skeleton for an easy and scalable development experience. Explore our website and join our community on Google+!

Visual Effects in Rikulo

Simon Pai — Tue, 13 Nov 2012 00:00:00 +0100

Last time we talked about EasingMotion in Rikulo. In this post, we are going to show you how to work on visual effects in Rikulo.

Many UI frameworks provide built-in effects to choose from, but few of them allow you to customize the effects to the finest details. In Rikulo, following the philosophy behind Motion, we let you do so, for Dart has a powerful class/closure fusion and a clear threading model, and we think users should be able to control visual effects to the maximal possible extent.

The effect infrastructure is designed to be loosely coupled with other parts of the view utilities, allowing you to do anything straightforward.

In the following sections, we are going to demonstrate how to use effects in your application.

Effects for Showing/Hiding Views

// demo 1 (view)

You can read the source code.

To add a view without effect is simple:

parent.addChild(view);

To add a view with an effect (say, fade-in) is not difficult either. Without the need of extending the old API, we shall do the following:

view.style.visibility = "hidden"; // add the view while invisible
parent.addChild(view);
new FadeInEffect(view.node).run();

FadeInEffect is a subclass of EasingMotion, which iteratively assign CSS opacity to the element from 0 to 1 in a given period (default: 500 ms). Like other EasingMotions, you can customize its running time, easing function, and pass in callback at the end of motion. For example,

view.style.visibility = "hidden"; // add the view while invisible
parent.addChild(view);
new FadeInEffect(view.node, end: (MotionState state) {
    // called when the effect ends
}).run();

When you need to remove a view with an effect, do it reversely:

new FadeOutEffect(view.node, end: (MotionState state) {
    view.remove();
    view.style.visibility = ""; // change the visibility back after removal
}).run();

Note that FadeInEffect is also a subclass of ShowEffect, which assumes element's visibility to be "hidden" to start with, and will make the element visible during the effect. On the contrary, FadeOutEffect, as a HideEffect, assumes element to be visible at the beginning, and will turn it invisible at the end.

Rikulo supplies a few built-in effects: FadeInEffect, ZoomInEffect, SlideInEffect for showing an element, and FadeOutEffect, ZoomOutEffect, SlideOutEffect for hiding an element. However, you can always easily customize them, or design your own effects by subclassing ShowEffect and HideEffect.

Dialog Effects

// demo 2 (dialog/panel)

You can read the source code.

Effects for showing or hiding a dialog is similar, expect that there is an additional mask element to take care of.

dialog.style.visibility = "hidden";
dialog.addToDocument(mode: "dialog");
Element mask = dialog.maskNode; 
// mask will inherit dialog's visibility, which allows you to control its effect
new EasingMotion.join([new ZoomInEffect(dialog.node), new FadeInEffect(mask)]).run();

Joint EasingMotion takes multiple EasingMotion and combines their actions. It has it's own period length and easing function.

View Switching Effects

// demo 3 (switch)

Here goes some slightly advanced effect applications. In the demo above, we switch two views with visual effects by

Add a second view to the document with hidden visibility
Apply the effect on both views together
Remove the first view

Feel free to take a glance at the source code to get more details.

Conclusion

We believe visualization is an important part in the application that you don't want to compromise. With the effect infrastructure of Rikulo, you can achieve almost every kind of effect you want.

In the next post, we are going to talk about MVC and UXL (User-interface eXtensible language) in Rikulo, with an implementation of todoMVC.

Easing Function in Rikulo

Simon Pai — Fri, 05 Oct 2012 00:00:00 +0200

A Demo

Try different combinations of easing functions and actions.

The source code is also available.

EasingMotion

Many of web prgrammers are familiar with the idea of easing function when working on visual effects. In Rikulo, we provided EasingMotion as a utility to easily construct easing-function-based effects and motions.

If you are not familiar with the idea, here is a quick explanation: Imagine we are going to implement a slide-down effect by iteratively setting the height of a DIV element from 0 to 100px. If the height increment is linear to elapsed time, the element will slide down linearly. (OK, this sounds like rubblish!)

However, we can also plug in a function to map the input t to a different value. Say, if we map t to t^2, the element will slide down in a varying speed (in this case, like a free fall).

In Rikulo code, this will be:

MotionAction action = (num x, MotionState state) {
    element.style.height = CSS.px((100 * x).toInt());
};
new EasingMotion(action, easing: (num t) => t * t).run();

You can specify the number of iterations and duration:

new EasingMotion(action, period: 2000 /* in millisecond */).run(); // runs for 2 sec
new EasingMotion(action, repeat: 3).run(); // repeat 3 times
new EasingMotion(action, repeat: -1).run(); // goes forever until explicitly stopped

At the start and the end of motion, you can provide callbacks:

new EasingMotion(action, start: (MotionState state) {
    // invoked when the motion starts
}, end: (MotionState state) {
    // invoked when the motion ends
}).run(); // runs for 2 sec

There are lifecycle managements:

EasingMotion motion = new EasingMotion(action); // some easing motion
motion.run();
if (motion.isRunning()) {
    motion.pause();
    motion.stop();
}

Easing Function Tips

Unlike jQuery, where you pass in easing function by name (as a string) and customize via plug-in, Rikulo allows you to work on the function directly. In our opinion, this is the right way to go, because the choice of easing function will often strongly affect user experience.

Here are some tips we would like to share:

Good easing functions are often functions that resembles real-life physics. For instance, free fall, simple harmonic motion, bouncing, etc.
On the other hand, the mathematical properties on an easing function will directly impact the user experience.
For example, to make the motion smooth, avoid cusp in the easing function.
In a bounced free-fall function, keep the gravity consistent.
Effects regarding to change of color or opacity are rather insensitive to the choice of easing function. The linear function is usually good enough.

Here are some nice easing functions:

// free fall, gives a natural sense of gravity/attraction
EasingFunction ef1 = (num t) => t * t;
// simple harmonic motion, spring-like bouncing
EasingFunction ef2 = (num t) => sin(t * PI * 2);
// heart beat
EasingFunction ef3 = (num t) =>  t < 0.3 ? (t * t / 0.09) : (1 - t) / 0.7;

Conclusion

EasingMotion is one of our building blocks to conveniently cover visual effects in application, component, and view switching. There are also built-in effects coming with the Rikulo library. We will further introduce them in the following blog posts.

Rikulo EL, an Expression Language for and in Dart

Henri Chen — Fri, 28 Sep 2012 00:00:00 +0200

Isn't EL for Java and JSP/JSF?

Yes, it is. And with Rikulo EL, you are now enabled to use EL for and in Dart, too.

And No, it is not.

EL indeed is more of a specification than an implementation. You can see it as a light weight scripting mechanism allowing you to easily access application logic and data with simple expression. You can see it as a templating engine that helps you generate proper text format of your choice. You can hook it with your presentation layer and do things similar to JSP pages. Or you can even use it to establish the whole data binding system that support MVVM design patterns.

Use Rikulo EL

Rikulo EL implements the EL specification thus you can use it as what you have used it before if you are familiar with it. Or maybe you want to check the EL specificationn for details.

Nevertheless, I will show you the enhancements that Rikulo EL added that are specific for Dart language.

Access variables

Following is a typical "Hello World" example. The variable to be evaluated is provided by use of VariableMapper.

import 'dart:mirrors' show reflect;
import 'package:rikulo_el/el.dart';

class Person {
  String name;
  Person(this.name);
}

void main() {
  //Prepare an expression factory.
  ExpressionFactory ef = new ExpressionFactory();

  //Prepare the expression script
  //expression inside #{...} is to be evaluated
  String script = 'Hello, #{person.name}!';

  //Prepare an expression context.
  ELContext ctx = new ELContext(
    resolveVariable:
      (String name) => name == 'person' ? new Person('Rikulo'): null);

  //Parse the script and create a value expression which expect a String type
  ValueExpression ve = ef.createValueExpression(ctx, script, reflect('').type);

  //Evaluate the expression and return the evaluated result
  print(ve.getValue(ctx)); //'Hello, Rikulo!'
}

Instead of reflecting the string's type (with reflect()), you can use STRING_MIRROR instead.

Access functions

Following is still a typical "Hello World" example. Here we use FunctionMapper.

import 'dart:mirrors' show reflect;
import 'package:rikulo_el/el.dart';

class Person {
  String name;
  Person(this.name);
}

void main() {
  //Prepare an expression factory.
  ExpressionFactory ef = new ExpressionFactory();

  //Prepare the expression script
  //expression inside #{...} is to be evaluated
  String script = 'Hello, #{currentPerson().name}!';

  //Prepare an expression context.
  Person currentPerson() => new Person('Rikulo');
  ELContext ctx = new ELContext(
    resolveFunction:
      (String name) => name == "currentPerson" ? currentPerson: null);

  //Parse the script and create a value expression which expect a String type
  ValueExpression ve = ef.createValueExpression(ctx, script, reflect('').type);

  //Evaluate the expression and return the evaluated result
  print(ve.getValue(ctx)); //'Hello, Rikulo!'
}

Allow using Dart array syntax in EL expression

There is no counter part in EL specification and Rikulo EL enhances the parser and evaluator to handle the Dart arrays. Following is a simple example.

import 'dart:mirrors' show reflect;
import 'package:rikulo_el/el.dart';

class Person {
  String name;
  Person(this.name);
}

void main() {
  //Prepare an expression factory.
  ExpressionFactory ef = new ExpressionFactory();

  //Prepare the expression script
  //expression inside #{...} is to be evaluated
  String script = 'Hello, #{[henri, john, mary][0].name}!';

  //Prepare an expression context.
  Person getPerson(String name) {
    switch (name) {
      case 'henri':
        return new Person('Henri');
      case 'john':
        return new Person('John');
      case 'mary':
        return new Person('Mary');
    }
  }
  ELContext ctx = new ELContext(resolveVariable: getPerson);

  //Parse the script and create a value expression which expect a String type
  ValueExpression ve = ef.createValueExpression(ctx, script, reflect('').type);

  //Evaluate the expression and return the evaluated result
  print(ve.getValue(ctx)); //'Hello, Henri!'
}

Note that such Dart array instance is created everytime the value expression is evaluated and its life scope is only within that "Evaluation". That is, after the evaluation is done, it will be left as is and finally garbage collected.

Allow using Dart map syntax in EL expression

import 'dart:mirrors' show reflect;
import 'package:rikulo_el/el.dart';

class Person {
  String name;
  Person(this.name);
}

void main() {
  //Prepare an expression factory.
  ExpressionFactory ef = new ExpressionFactory();

  //Prepare the expression script
  //expression inside #{...} is to be evaluated
  String script = 
    "Hello, #{{'henri' : henri, 'john' : john, 'mary' : mary}['henri'].name}!";

  //Prepare an expression context.
  Person getPerson(String name) {
    switch (name) {
      case 'henri':
        return new Person('Henri');
      case 'john':
        return new Person('John');
      case 'mary':
        return new Person('Mary');
    }
  }
  ELContext ctx = new ELContext(resolveVariable: getPerson);

  //Parse the script and create a value expression which expect a String type
  ValueExpression ve = ef.createValueExpression(ctx, script, reflect('').type);

  //Evaluate the expression and return the evaluated result
  print(ve.getValue(ctx)); //'Hello, Henri!'
}

Note that such Dart map instance is created everytime the value expression is evaluated and its life scope is only within that "Evaluation". That is, after the evaluation is done, it will be left as is and finally garbage collected.

Conclusion

Rikulo EL implements the Unified Expression Language specification and adds some enhancement features specific for Dart language. Authoring the presentation layer(web pages) in Dart and Rikulo will be easier and more versatile. It will serve as the important base templating engine for Rikulo UXL UI eXtensible Language and the Rikulo ORM libraries. Stay tuned.

A Rotatable Map Prototype

Simon Pai — Tue, 28 Aug 2012 00:00:00 +0200

A Rotatable Map

This is going to be a very simple demo. Have you tried Google Maps on a touch device? Have you ever wondered what if Google Maps is rotatable by two fingers? This will be the demo that realizes the imagination.

The Outcome

You will need to play on a touch device to explore the full functionality of this demo.
Pinching the image with two fingers results in free scaling, rotating, and moving.
The picture is distributed under Creative Commons license. It came from Norman B. Leventhal Map Center at the BPL.

The Idea

The idea is straightforward: we use the information from a ZoomGesture to determine a CSS transformation to apply to the photo image element. The transformation must satisfy the following properties:

It has to be linear and angle preserving. (i.e. no stretch/skew)
It should map the initial touch positions to the current touch positions, respectively. (i.e. say, on a real map, if you touch London and Paris and move your fingers, they should be always on London and Paris.)

The two properties above has uniquely and naturally defined the transformation from the gesture. In fact, this transformation is exactly how ZoomGesture is interpreted in Rikulo.

ZoomGesture

In Rikulo, ZoomGesture is all about how two fingers move and what they represent, in terms of scale, rotation, and transition.

Anytime during a ZoomGesture, the following raw information are supplied:

int startTime = state.startTime; // the initial timestamp of gesture;
int time = state.time; // the current timestamp of gesture;
Offset[] spos = state.startPositions; // the initial touch positions
Offset[] cpos = state.positions; // the current touch positions

From the initial and current positions, it further derives the following values:

num scalar = state.scalar; // scalar change of distance between touch points
num angle = state.angle; // angular change, in radian
Offset transition = state.transition; // displacement of midpoint

Last but not least, it also supplies a Transformation object to describe the entire transformation, with respect to the midpoint of initial positions as the origin. With Dart's power of operator definition, you can even do matrix multiplication easily.

Transformation t1 = state.transformation;
Transformation t2 = new Transformation.rotate(PI / 3);
Transformation t3 = t1 * t2; // matrix multiplication
element.style.transform = CSS.transform(t3);

Implementation

We are going to skip the basic layout part of this demo, but you can always explore the source code.

One thing to note here: the transformation matrix provided by ZoomGesture has its origin at the midpoint of initial touches, while the CSS transformation has its origin at the center of the element. To make them compatible, we will shift the transformation origin by API.

Offset diff; // used to offset transform origin
Transformation trans; // the transformation on the image element

new ZoomGesture(mainView.node, start: (ZoomGestureState state) {
    // the offset of transformation origins to shift
    diff = center(img) - state.startMidpoint;

}, move: (ZoomGestureState state) {
    // 1. the origin needs to shift
    // 2. the transformation shall stack with ones from previous gestures
    img.style.transform = CSS.transform(state.transformation.originAt(diff) * trans);

}, end: (ZoomGestureState state) {
    // write the transformation back
    trans = state.transformation.originAt(diff) * trans;

});

// calculate the page offset of the center of an element
Offset center(View v) {
    Size size = new DOMQuery(v).outerSize;
    return new DOMQuery(v).pageOffset + new Offset(size.width / 2, size.height / 2);
}

// whenever window resizes, initialize image transformation
img.on.preLayout.add((LayoutEvent event) {
    trans = new Transformation.identity();
    img.style.transform = CSS.transform(trans);

});

DragGesture, Too

When you touch the screen with a single finger, you would expect the image to be dragged as well. Here we can add a DragGesture to handle:

new DragGesture(mainView.node, move: (DragGestureState state) {
    img.style.transform = CSS.transform(new Transformation.transit(state.transition) * trans);

}, end: (DragGestureState state) {
    trans = new Transformation.transit(state.transition) * trans;

});

Note that ZoomGesture and DragGesture naturally avoid each other, so there is no extra work required to keep them apart.

Conclusion

The information given by ZoomGesture are decomposed into the following 3 independent aspects:

scale
rotation
transition

Most of time your would only concern 1 or 2 of them, which are nicely orthogonal, and you don't need to worry about trasformation origin issue.

A Photo Album Prototype with Swipe Gesture

Simon Pai — Fri, 10 Aug 2012 00:00:00 +0200

The Plan

We are going to build an album-like demo as an application of the new SwipeGesture. If you are a front end web developer, you should be familiar with the construction:

Then we are going to wire up a SwipeGesture and a Motion, so that the pictures will shift when they receive a swipe gesture.

The Outcome

Swipe to view next or previous photo.

The pictures are distributed under Creative Commons license.
Original pictures came from Kim Carpenter, sophie, Kate, Chris. P, Kabacchi.

Layout and Responsive Design

We start by laying down the views:

final View frame = new View();
frame.style.overflow = "hidden";
frame.profile.location = "center center";
// frame width/height = minimum of [window width] and [window height]

final View frameInner = new View();
// frameInner height = [frame height]
// frameInner width = [frame width] * [photo count]
// frameInner top = 0 (default)
// frameInner left = - [photo index] * [frame width]
frame.addChild(frameInner);

for (int i = 0; i < photoCount; i++) {
    View photoBox = new View();
    // photoBox width/height = [frame width/height] - 50, capped at 500
    // photoBox top = an offset which makes it center-aligned to frame
    // photoBox left = [the offset] + [photo index] * [frame width/height]

    Image photo = new Image();
    photo.classes.add("photo");
    photo.profile.text = "location: top left; width: 100%; height: 100%";
    photo.src = "res/alpaca-0${i+1}.jpg";

    View mask = new View(); // to block browser's default image dragging
    mask.classes.add("photo-mask");
    mask.profile.text = "location: top left; width: 100%; height: 100%";

    photoBox.addChild(photo);
    photoBox.addChild(mask);
    frameInner.addChild(photoBox);
}

mainView.addChild(frame);

Note that the size settings of some views are purposely left out, as we are going to handle it directly within the layout callback, so they will be responsive automatically:

frame.on.preLayout.add((LayoutEvent event) {
    final Size msize = new DOMQuery(mainView).innerSize;
    frameSize = min(msize.width, msize.height);
    final int photoSize = min(frameSize - 50, 500);
    final int photoOffset = ((frameSize - photoSize) / 2).toInt();

    frame.width = frame.height = frameInner.height = frameSize;
    frameInner.width = frameSize * photoCount;
    frameInner.left = -_index * frameSize;

    for (int i = 0; i < photoCount; i++) {
        View photoBox = frameInner.children[i];
        photoBox.width = photoBox.height = photoSize;
        photoBox.left = photoOffset + i * frameSize;
        photoBox.top = photoOffset;
    }
});

Business Logic

Now we are going to write down the business logic:

int _index = 0;

void next() => select(_index + 1);

void previous() => select(_index - 1);

void select(int index) {
    if (index < 0 || index >= photoCount) {
        // do nothing
        return;
    }
    // TODO: trigger an animation to shift the photos
}

Animation

The animation part is straightforward:

void select(int index) {
    if (index < 0 || index >= photoCount) {
        // do nothing
        return;
    }
    // trigger an animation to shift the photos
    final Offset origin = new Offset(-_index * frameSize, 0);
    final Offset dest = new Offset(-index * frameSize, 0);
    new LinearPathMotion(frameInner.node, origin, dest, end: (MotionState state) {
        _index = index;
    }, easing: (num x) => x * x);
}

Swipe Gesture

Here we are going to capture user's swipe gesture.

new SwipeGesture(mainView.node, (SwipeGestureState state) {
    final int diff = state.delta.x;
    if (diff < -50) // swipe left
        next();
    else if (diff > 50) // swipe right
        previous();
});

But wait! There is an issue with this implementation. Whenever there are multiple gestures/motions in the game, it is necessary to consider whether they will conflict each other. Generally there will be a priority, where one gesture/motion will block or interrupt another.

In the previous example we have shown how a gesture interrupts a motion. In this scenario, we are going to make the photo-shifting motion block the incoming swipe gesture:

SwipeGesture gesture;

gesture = new SwipeGesture(mainView.node, (SwipeGestureState state) {
    gesture.disable();
    final int diff = state.delta.x;
    if (diff < -50) // swipe left
        next();
    else if (diff > 50) // swipe right
        previous();
    else
        gesture.enable();
});

void select(int index) {
    if (index < 0 || index >= photoCount) {
        gesture.enable();
        return;
    }
    final Offset origin = new Offset(-_index * frameSize, 0);
    final Offset dest = new Offset(-index * frameSize, 0);
    new LinearPathMotion(frameInner.node, origin, dest, end: (MotionState state) {
        _index = index;
        gesture.enable();
    }, easing: (num x) => x * x);
}

The gestures come with enable/disable APIs, allowing us to easily turn it on and off.

Conclusion

At the end we added a few more decorations to the demo to make it fancier. They are quite straightforward to figure out from the source code.

Building a Grid Demo using Rikulo

Simon Pai — Thu, 02 Aug 2012 00:00:00 +0200

Introduction

Continued from the previous post, this time we are going to build a grid sample, with scrolling on both directions. In addition, we would like to try the events on ScrollView and Scroller control functions, by contructing multiple ScrollViews whose scrolling are "linked" to each others.

The Outcome

Grag or swipe on the each area to scroll.

Prepare ScrollView and Their Contents.

The ScrollView and content preparation itself is quite straightforward. You can refer to the previous blog post or the source code. Here is an overview of what we do:

final int barSize = 50, barInnerSize = 40;
final Size msize = new DOMQuery(mainView).innerSize;

final View container = new View();
container.profile.text = "location: center center; width: 80%; height: 80%";
mainView.addChild(container);
final csize = new DOMQuery(container).innerSize;

final ScrollView view = new ScrollView();
view.profile.text = 
    "location: bottom right; width: ${csize.width - barSide}px; height: ${csize.height - barSide}px";
view.classes.add("list-view");

final ScrollView hbar = new ScrollView(direction: Dir.HORIZONTAL);
hbar.profile.anchorView = view;
hbar.profile.text = "location: north center; width: 100%; height: ${barSize}px";
hbar.classes.add("list-view list-view-hbar");

final ScrollView vbar = new ScrollView(direction: Dir.VERTICAL);
vbar.profile.anchorView = view;
vbar.profile.text = "location: west center; width: ${barSize}px; height: 100%";
vbar.classes.add("list-view list-view-vbar");

// fill children
// ...

Cling Together

To link these parts, there are two things we need to handle: 1. When user starts scrolling on one ScrollView, stop current scrollings on the others, if any. 2. While scrolling, update scroll position of linked ScrollViews as well.

view.on.scrollStart.add((ScrollEvent event) {
    hbar.scroller.stop();
    vbar.scroller.stop();
});
view.on.scrollMove.add((ScrollEvent event) {
    hbar.scroller.scrollPosition = vbar.scroller.scrollPosition = event.state.position;
});

hbar.on.scrollStart.add((ScrollEvent event) {
    view.scroller.stop();
    vbar.scroller.stop();
});
hbar.on.scrollMove.add((ScrollEvent event) {
    view.scroller.scrollPosition = 
        new Offset(event.state.position.x, view.scroller.scrollPosition.y);
});

vbar.on.scrollStart.add((ScrollEvent event) {
    view.scroller.stop();
    hbar.scroller.stop();
});
vbar.on.scrollMove.add((ScrollEvent event) {
    view.scroller.scrollPosition = 
        new Offset(view.scroller.scrollPosition.x, event.state.position.y);
});

Be Responsive

In the current code, the size depends on browser window size. However, if we resize the window after the page is loaded, some of the component sizes will not change. To make it responsive, we have to intercept the size setting in the pre-layout event:

final ScrollView view = new ScrollView();
view.profile.text = "location: bottom right";

view.on.preLayout.add((LayoutEvent event) {
    final cs = new DOMQuery(container).innerSize;
    view.width = cs.width - barSize;
    view.height = cs.height - barSize;
});

In the future we may come up with a more natural and intuitive way to support responsive design implementation.

Conclusion

Many of the motion/gesture related constructions come with the same lifecycle callbacks: start, move, and end.

For example, you may often consider:

Interrupt some current actions when a gesture/motion starts.
Update the state of some element when a gesture/motion is running.
When a gesture/motion ends, trigger another motion.

The homogeneity makes it easy chain or link these constructions together to compose them into a larger unit, and we believe these patterns should be quite friendly to web effect/animation designers.

Building a List View Demo using Rikulo

Simon Pai — Wed, 25 Jul 2012 00:00:00 +0200

Introduction

As we are building up the UI infrastructure of Rikulo, there is a critical widget we can't miss: List View. On our skretch paper, the rough architecture is like this:

Before we rush to create a List View widget, we would like to simulate its left part as an application of ScrollView first. Also this gives us a chance to test the strength of the Scroller utility.

The Outcome

To scroll down the list drag with mouse or swipe with finger.

Starting with ScrollView

We start with putting down a ScrollView widget at the center of mainView.

ScrollView view = new ScrollView(direction: Dir.VERTICAL);
view.profile.text =
    "location: center center; width: 80%; height: 80%";
view.classes.add("list-view");
mainView.addChild(view);

Loading List Items

Then, we are going to fill up the list items in ScrollView. Note that if we don't give ScrollView a content height, it will adjust automatically depending on the size and position of its children.

for (int x = 0; x < 50; ++x) {
    View child = new TextView("Row ${x + 1}");

    final int height = 50;
    child.classes.add("list-item");
    child.style.cssText = "line-height: ${height}px";
    child.style.userSelect = "none"; // so it does not interrupt dragging
    child.profile.width = "flex"; // take full width
    child.top = x * height;
    child.height = height;

    view.addChild(child);
}

Snap Function

Stepping further, we can add a snap function, which tells the ScrollView to "snap to" a position based on the ending position of a scrolling. In the implementation below, we let it snap to closest border of each list item.

ScrollView view;
view = new ScrollView(direction: Dir.VERTICAL, 
snap: (Offset off) {
    final num vlimit = 50 * 50 - view.innerHeight;
    final num y = off.y >= vlimit ? vlimit : ((off.y + 25) / 50).floor() * 50;
    return new Offset(off.x, y);
});

Conclusion

Based on the nature of ScrollView, such a List View example is really easy to achieve.

In our next blog post, we are going to explore creating another example using ScrollView: a 2D scrolling panel with its scrolling linked to side bars. Please don't hesitate to leave your comment.

Rikulo team members on Dartisans Ep 8!

Timothy Clare — Wed, 25 Jul 2012 00:00:00 +0200

Update

Well the Dartisans show has passed and we had a great time. We would like to thank everyone at Google for having us, especially jj and Seth for hosting a great show. If you missed the show fear not the video of it is now available!

Click here for the video!

Dartisans!

Just to inform the Rikulo community that Simon Pai and I will be on Dartisans episode 8 tonight as special guests. We will be discussing about Rikulo so if you would like to join us you can click here!

Full details

Dartisans Ep. 8 - Dart news and special guests

Time

July 25, 2012 9 a.m. — 10 a.m. (PDT)

About

We'll be talking to Tim Clare and Simon Pai about Rikulo, a "free and open source framework for creating incredible cross-platform web and native mobile applications in Dart & HTML5." We'll also be talking with Gilad Bracha about upcoming changes to the way libraries and imports work.

More info:

Watch it here

The Rikulo Way

Timothy Clare — Tue, 10 Jul 2012 00:00:00 +0200

Introduction

Rikulo is a free and open source framework for creating incredible cross-platform web and native mobile applications in Dart & HTML5. Our aim is soley to provide developers with the easiest and most powerful ways to create their application. We do this by bringing structure to your user interface.

Dart has brought structured programming to the web allowing code to be run at the client and on the server. With Rikulo we wanted to push this philosophy further and place it into the UI. HTML and CSS are great for websites which contain a lot of textual content and with the advent of HTML 5 and CSS 3 even better features have been introduced. However, when creating complex applications HTML and CSS can cause more problems than it solves due to side-effects introduced when creating and updating complex layouts.

Our solution is "Structured UI Model".

Structured UI Model

The Structured UI Model forms a central basis of our philosophy which has been adapted for use since the very first GUI system was introduced, it simply states:

UI elements should be positioned using coordinates in relation to their parent

This simple philosophy gives developer's the power they require when laying out their while keeping the implementation simple. This simplicity is the key. We shield the developer from any need to interact with the DOM. The following diagram outlines our architecture.

The above architecture outlines that you do not need to touch the DOM at all, Rikulo's UI Model will do all that work for you.

You can create your own layout when needed effortlessly, the following example outlines the power of Rikulo by laying out components in a simple and elegant manner.

for (int x = 0; x < 30; ++x) {
    for (int y = 0; y < 30; ++y) {
        View child = new View();
        final String color = CSS.color(250 - x * 4, 250 - y * 4, 200);
        child.style.cssText = "border: 1px solid #553; background-color: $color";
        child.left = x * 50 + 2;
        child.top = y * 50 + 2;
        child.width = child.height = 46;
        view.addChild(child);
    }
}

As well as being able to effortlessly layout components manually, Rikulo also provides a set of stock layout components.

Layouts

The layouts are an extensions of Rikulo's UI Model a good example of said layout is a Linear layout which can help developers layout their components vertically or horizontally. An example of linear layouts with different sized views is shown below.

In additon to linear layouts Rikulo also provides an Anchor layout. The example below shows an Anchor layout in action.

TextView welcome = new TextView("Hello World!");
welcome.profile.text = "anchor: parent; location: center center";

In addition to the provided layouts developers are able to create their own using Rikulo's base layout, more information on layouts can be found here.

HTML & CSS - you can still use it

The Rikulo philosophy is all about constructing a structured user interface with the minimum of fuss, though of course in all applications there will be areas where developers want total control over the layout, this is easily achieved. Rikulo's View completely supports HTML markup, for example:

textView.html = "<table><tr><td>${data1}</td><td>${data2}</tr></table>";

This means should you need HTML & CSS capabilities then it is available to you.

Mobile strength

One of the major areas in which Rikulo and Dart shines is in the mobile arena where JavaScript is not suited to creating large applications but where HTML & CSS alone are not enough. Combining the structure, simplicity and power of Rikulo and Dart means that developers have an exciting way of creating native mobile applications.

Conclusion

This post serves as a quick introduction to Rikulo's philosophy. To learn more about Rikulo please visit the learn page.

Creating a Snake game using Rikulo, HTML 5 and the canvas

Timothy Clare — Mon, 09 Jul 2012 00:00:00 +0200

Introduction

This blog post details how to create a Snake style game using Rikulo, Dart, HTML 5 and the Canvas. The final game serves as a sample of how to use Rikulo along with Dart.

The Result

To control the Snake try using the arrow keys or using a mouse on a computer or finger to swipe on a tablet or phone.

For a better experience you can view the demo on its own here

Modeling the items

I started by modeling the different elements of the game, we are required to model the Snake, its environment and the food that it eats. If an item was complex I split it over a couple of classes. The file names should give you all a clue as to what elements are modeled within them, but just for completeness sake here is a list of files and what they represent.

Snake.dart - The actual snake, will require a body, direction and will be responsible for acting on turns
Food.dart - The food that the snake eats
SnakePoint.dart - A point on the canvas
SnakeEvironment.dart - The environment that the snake acts in
SnakeCanvas.dart - The main class which sets up the game

I will walk you through the process of modeling the Snake and Food.

Snake

As previously mentioned the Snake will be responsible for its own body and direction. First of all let's setup the snake body. The body will be represented via a list of SnakePoints. The SnakePoint is very easy so we can include the entire code for the class here.

class SnakePoint {
    int x, y;

    SnakePoint(this.x, this.y);

    String toString() {
        return "($x, $y)";
    }
}

As we can see the SnakePoint class is just used to represent a point and does nothing else. So the body representation of the snake in Snake.dart. The snippet below also includes methods for retrieving the Snake's length and head.

List<SnakePoint> body;

int length() {
  return body.length;
}

SnakePoint head() {
  return body.last();
}

The Snake also has a direction which is represented internally via an integer. The directions are also provided using static integer which represent the directions of the Snake. The following code snippet outlines the possible snake directions and the getter and setters.

static final int UP = -2, DOWN = 2, LEFT=-1, RIGHT=1;  
int _direction;

int get direction() => _direction;

set direction(int value) {
  if((_direction + value) != 0) {
    _direction = value;
  }
}

In this case the setter for direction does not check whether the direction is one of UP, DOWN, LEFT or RIGHT. That is of course desired should a production quality game being created but for the purposes of our example we will leave it be. The set direction function prevents an opposite direction being set, so the Snake cannot be moving left and be made to move right. It does this by assigning absolute equal values to opposite directions, thus when _direction is added to the proposed value and the outcome is 0 then the direction is not set.

Finally we move onto looking to implement the actions of the snake, this is generally to move and to grow depending on whether the snake consumes the food or not. To implement these actions we create a function called act which takes the canvas rendering context and the location of the food, this function is responsible for movement and checking for growth, let's take a look at the function.

bool act(CanvasRenderingContext2D context, Food food) {

    if(initial) {
      body.forEach((element) => drawSnake(context, element, null));
      initial = false;
      return false;
    }

    SnakePoint moveTo = nextMove();
    bool grow = (moveTo.x == food.x && 
                 moveTo.y == food.y);

    var removed = move(moveTo, grow);
    draw(context, removed);

    return grow;
}

As shown in the function when the snake is initialized this function will draw the entire snake using the drawSnake method which we will talk after this section. The snake also looks at the next available move before moving to determine whether or not it will actually consume the food. Whether or not the snake will grow is stored in a boolean value and then passed to the move method to move the actual snake, the following shows this method.

SnakePoint move(SnakePoint to, bool grow) {
    var removed = null;

    if(!grow) {
      removed = body[0];
      body.removeRange(0, 1);
    }
    body.add(to);

    return removed;
}

In this method if the snake will not grow the last point of the body is removed and the new point where the snake moves to is added. However, if the snake will in fact grow then the last point is not removed, so in effect the snake grows by 1 square. The removed point is then returned from the function.

The snake, as all actors are in this simple example, is responsible for its own drawing. Drawing the shape of the Snake is a reasonably simple affrair, let's take a look at the code.

void draw(CanvasRenderingContext2D context, SnakePoint removed) {    
    drawSnake(context, body.last(), removed);
}

void drawSnake(CanvasRenderingContext2D context, SnakePoint point, SnakePoint removed) {
    context.beginPath();
    context.fillStyle = "black";

    num adjustment = SnakeEnvironment.adjustment;

    if(removed != null) {
        context.clearRect(removed.x, removed.y, adjustment, adjustment);
    }

    int width = SnakeEnvironment.adjustment;
    int height = SnakeEnvironment.adjustment;
    int radius = SnakeEnvironment.adjustment / 3;

    context.beginPath();
    context.moveTo(point.x + radius, point.y);
    context.lineTo(point.x + width - radius, point.y);
    context.quadraticCurveTo(point.x + width, point.y, point.x + width, 
                             point.y + radius);
    context.lineTo(point.x + width, point.y + height - radius);
    context.quadraticCurveTo(point.x + width, point.y + height, 
                             point.x + width - radius, point.y + height);
    context.lineTo(point.x + radius, point.y + height);
    context.quadraticCurveTo(point.x, point.y + height, point.x, 
                             point.y + height - radius);
    context.lineTo(point.x, point.y + radius);
    context.quadraticCurveTo(point.x, point.y, point.x + radius, point.y);
    context.closePath();
    context.fill();
}

This code will draw one point of the snake and remove one point of the snake. The new point is the new head of the snake to simulate mvoement and the point removed is the last point of the snake, unless it grows. The quadraticCurveTo and lineTo function calls will paint a rounded rectangle. If a rounded rectangle is not required it is of course possible to just replace this with a context.rect function call which would simplify the code a lot.

Food

The food is the easy part as it just consists of 3 functions, relocate, draw and the constructor. In addition to that there are two properties, one for x and one for y which hold the location of the food.

Let's start with the relocate method:

void relocate(List<SnakePoint> avoid) {

    double suggestedX = Math.random()*((snakeEnvironment.width / SnakeEnvironment.adjustment) - 1);
    double suggestedY = Math.random()*((snakeEnvironment.height / SnakeEnvironment.adjustment) - 1);

    suggestedX = suggestedX.floor() * SnakeEnvironment.adjustment;
    suggestedY = suggestedY.floor() * SnakeEnvironment.adjustment;

    bool has = false;

    for(final point in avoid) {
        if(suggestedX == point.x && suggestedY == point.y) { 
            has=true;
            break;
        }
    }

    if(has)
        relocate(avoid);
    else {
        x = suggestedX.toInt();
        y = suggestedY.toInt();
    }
}

The above relocate function takes a list of points to avoid (in this case the Snake's location) and then locates a point on the grid where the food can be painted. The algorithm is a very simple implementation and no doubt can be improved. The last function is the draw function which is self explanatory. It will draw an old style Snake food item which consists of 4 small rectangles within a small area.

void draw(CanvasRenderingContext2D context) {

    double smallSquareWidthAndHeight = SnakeEnvironment.adjustment / 3;

    context.beginPath();
    context.fillStyle = "black";

    //first rectangle, top row
    context.rect(_x + smallSquareWidthAndHeight, _y, smallSquareWidthAndHeight, smallSquareWidthAndHeight);

    //two rectangles second row
    context.rect(_x, _y + smallSquareWidthAndHeight, smallSquareWidthAndHeight, smallSquareWidthAndHeight);
    context.rect(_x + (smallSquareWidthAndHeight * 2), _y + smallSquareWidthAndHeight, smallSquareWidthAndHeight, smallSquareWidthAndHeight);

    //bottom row rectangle
    context.rect(_x + smallSquareWidthAndHeight, _y + (smallSquareWidthAndHeight * 2), smallSquareWidthAndHeight, smallSquareWidthAndHeight);

    context.closePath();
    context.fill();
}

Having walked through individual classes it is time to discuss how the environment and gaming loop were implemented, the following section introduces these concepts.

The environment, game loop, UI and controls

These are 3 pretty large topics, however, first of all let's take a look at how the environment is setup.

The environment

In our class the canvas is initialized in the SnakeCanvas.dart class which is the main class for the UI and the game loop. First of all let's walk through the SnakeEnvironment class which initializes all of the objects within the game and determines whether the gamer scored, continues or loses.

class SnakeEnvironment {

    static final int SCORED=0, GAMEOVER=1, CONTINUE=2;
    static final num adjustment = 10;

    num height,width;
    Snake snake;
    Food food;

    SnakeEnvironment(this.height, this.width) {

        if((this.height % adjustment != 0) ||
        (this.width % adjustment != 0)) {
            throw new IllegalArgumentException("Height & Width must be divisible by the adjustment (${adjustment}) without a remainder");
        }

        snake = new Snake(this);
        food = new Food(this);

        food.relocate(snake.body);
    }

    int draw(CanvasRenderingContext2D context) {
        food.draw(context);
        bool grown = snake.act(context, food);

        var head = snake.head();
        if((head.x >= width || head.x < 0)
        || (head.y >= height || head.y < 0)) {
            return GAMEOVER;
        }

        if(grown) {
            food.relocate(snake.body);
            return SCORED;
        }

        return CONTINUE;
    }
}

The SnakeEnvironment is pretty simple, it accepts a height & width and if the height and width are not divisible by the scale factor without a remainder it will throw an error. This is only to keep x, y co-ordinates integers throughout the application for simplicity's sake. The Snake & Food are then initialized and food is relocated depending on the Snakes body.

The draw method is a bit different as it returns an integer, we could have kept it void and wrapped it with another function which returns an integer to signify the status of the game, whether to continue, whether it is gameover or whether the snake scored.

That pretty much wraps up the SnakeEnvironment, it is time to discuss how the game loop is implemented.

Game Loop

Now under normal circumstances it is better to separate the UI loop from the actual game loop. In the future I will look into doing this with an Isolate. However, for the purposes of simplicity in this example the game loop is also responsible for the painting the items onto the canvas.

The game loop is activated in the SnakeCanvas class by creating a Rikulo Animator object.

new Animator().add((int time, int elapsed) {
  int timeSinceCycle = time - lastCycle;
  bool ret = true;

  if(timeSinceCycle > UPDATE) {
    int message = environment.draw(ctx2d);

    switch(message) {
      case SnakeEnvironment.GAMEOVER:
        ret = false;
        window.alert('GAME OVER!! Your score was ${score}');
        break;
      case SnakeEnvironment.SCORED:
        score += 1;
        break;
    }

    lastCycle = time;
  }

  return ret;
});

The Animator is used to create the game loop by checking whether the current time subtracted from the last update time is greater than the update period. Currently the update period (contained in the variable UPDATE) is set at 100ms. If the the time since the last cycle is greater than 100ms then the SnakeEnvironment's draw method is called which creates a cascading effect on the canvas and what needs to be redrawn is redrawn.

The returned value from the draw method is then checked and if it is game over the loop is stopped and the score is shown. On the other hand if the player scored then the score is incremented. The game loop is very simple indeed and just continues until the player loses.

Let's now look at how the UI and control elements were implemented.

UI and controls

To build the UI with Rikulo is very easy to do. In our case we want a background so we will create a view to hold that, then we will require a new View to hold both the canvas and score positioning the score underneath the canvas. Here is the code to do this which is contained in the onCreate method.

mainView.width = 572;
mainView.height = 396;
mainView.style.backgroundImage = "url('http://static.rikulo.org/blogs/tutorial/creating-snake/res/snake_bg.png')";

//vlayout
View vlayout = new View();
vlayout.layout.type = "linear";
vlayout.layout.orient = "vertical";
vlayout.profile.anchorView = mainView;   
vlayout.profile.location = "center center";

//canvas
canvas = new Canvas();
canvas.profile.text = "width: ${width}; height: ${height}";
canvas.style.border = "1px solid black";
vlayout.addChild(canvas);

scoreBar = new TextView("Your score is: ${score}");
scoreBar.profile.width = "flex";
scoreBar.profile.height = "30";
vlayout.addChild(scoreBar);

mainView.addChild(vlayout);

The code above demonstrates how the views are combined to create the layout. The View with the background is named div and created first, then a view which arranges its children vertically is created. Then the Canvas and a TextView is added to the vlayout view to complete the cycle.

This is how simple is it to create the view you see at the top in Rikulo.

The controls are also equally easy to implement, there are two sets of controls, one for tablets & smartphones and the other for a keyboard, the next two sections outline these controls.

Keyboard

For the keyboard we would like to use the arrow keys to set the direction of the snake, this is easily done using the onKeyDown function provided by Dart.

void onKeyDown(KeyboardEvent event) {
    if(event.keyCode == 37)
        environment.snake.direction = Snake.LEFT;
    else if(event.keyCode == 39)
        environment.snake.direction = Snake.RIGHT;
    else if(event.keyCode == 38)
        environment.snake.direction = Snake.UP;
    else if(event.keyCode == 40)
        environment.snake.direction = Snake.DOWN;
}

As you can see the code is in fact very very simple and upon keypress will just access the snake and then set its direction.

Tablets & Smartphones

For tablets and Smartphones we would like to be able to change the movement of the snake using DragGestures. Rikulo makes this easy by providing a class, to create the class you are required to pass it the node you want the gesture to apply to and optionally functions which correspond to start, moving and end. The following demonstrates how the class was created.

new DragGesture(this.canvas.node, moving: _gestureMove(), end: _gestureEnd());

As you can see above we pass the class two methods, _gestureMove() which is the callback function while moving and _gestureEnd() which is the callback function when the gesture has ended, the functions are as follows.

DragGestureMove _gestureMove() {
    return (DragGestureState state) {

        final int MINIMUM_DRAG_LENGTH = 5;

        if(state.delta.x.abs() > state.delta.y.abs() && 
        state.delta.x.abs() > MINIMUM_DRAG_LENGTH) {
            //horizontal swipe
            state.delta.x > 0 ? 
            environment.snake.direction = Snake.RIGHT :
            environment.snake.direction = Snake.LEFT;
        } else if(state.delta.y.abs() > MINIMUM_DRAG_LENGTH) {
            //vertical swipe
            state.delta.y > 0 ?
            environment.snake.direction = Snake.DOWN :
            environment.snake.direction = Snake.UP;
        }

        return true;
    };
}

DragGestureMove _gestureEnd() {
    return (DragGestureState state) {
        return true;
    };
}

The _gestureMove() function returns the callback method and it is easy to see what it does. The functions checks to see whether the movement is longer than the minimum drag length and if it is then it checks the direction of the movement and sets the snake's direction according. Very simple but very effective.

Conclusion

That is really all there is to the snake example. It is important to remember that it is just an example and there is of course major room for improvement both architecturally and feature wise. For example we can attempt to split the game loop from the UI loop and when the snake crossed its own path it will die. However, for the scope of a tutorial this is beyond what I would like to show for now.

If you have any feedback please let me know. In addition if you would like to improve the game, maybe implementing a few of the ideas suggested in the above paragraph please go ahead and do so.