Ground

#Introduction

Ground is a compact, modern web development framework that provides you a firm foundation to create rich, modular, scalable, realtime interactive web applications that are required to work seamlessly both online and offline.

Ground is light (22Kb + 5Kb of dependencies), and well suited for both desktop and mobile applications.

In ground, most of the application logic is moved from the server to the client, whereas the server acts mostly as an scalable, efficient distributed storage and synchronization controller.

It includes also some rather useful features such as a hierarchical routing system, an undo/redo manager, property and declarative bindings, reference counting and automatic synchronization between clients and servers. It is design to always deliver high performance and low memory consumption.

Ground is written in TypeScript, for modularity and stability and is suitable for both javascript and TypeScript projects.

##Highlights

• Designed and optimized for Node.js servers.
• Hierarchical routing system simplifies routing by matching the DOM hierarchical nature.
• Define models and use them both client and server side.
• Models, Collections and Sequences with property bindings, persistence and client-server synchronization.
• Offline support.
• Declarative Bindings for easily connecting views and models.
• Sessions and rights managements support.

##Philosophy

The philosophy of Ground is to focus on performance and simplicity. We wrote the complex code so that you don't.

It should be a complete Web framework that is fun to use, that uses efficiently the newest web browser technologies, and that relies on Node.js server technology to provide scalability and synchronization. It provides some innovations such as hierarchical routes and bi-directional client / server communication.

##Dependencies

Ground depends on the following external libraries: Curl, Socket.io and Underscore or LoDash.

Ground is provided both as a set of TypeScript classes, and as a javascript AMD module. It can be included using script tags or using an AMD loader. While it should work with any AMD compatible loader, we recommend Curl since it is already a required dependency.

For the server component both Redis and MongoDB are required at the moment.

##Install

Install Ground by using npm:

npm install gnd -g

##Command line

Ground provides a command line tool that can be used to generate the skeleton of a ground application. This is a very convenient way to start playing with the framework with a minimum effort. For example:

gnd myapplication

Will generate a ground application in the directory myapplication. Enter in the directory and execute:

npm install

This will install all the required dependencies, then just fire the server with the application:

npm start

The hello world application will be started automatically in your default browser.

Grunt is used for building the application for deployment. If you don't have grunt already installed:

npm install -g grunt-cli

Then just:

grunt

The resulting app will be placed in the build directory.

For testing we use Mocha. If you don't have mocha installed:

npm install -g mocha

You can run tests in developing mode

npm test

Or run the tests on the production built code:

npm test --production

#Demos

Take a look at some demos created with Ground that demonstrate some of its highlights:

• Hierarchical Routing
• Dynamic lists
• Dynamic tables
• Realtime multi user chat

#Routing

In modern web applications, it is desired to avoid page refreshes in order to provide a better user experience as well as to help keeping the application state and reduce latency. While it is possible to keep an internal state between the application different components, it is often convenient to offer urls that links to different "global" states of the application. This is achieved using a client side url routing system.

Ground takes a less traditional approach to url routing. Instead of defining a list of independent routes, the routes are assumed to be hierarchical, matching the hierarchical nature of a web page and the underlying DOM structure. The framework is smart enough to avoid re-rendering unnecessary DOM nodes, as well as deleting the ones that are not part of the current route.

With this approach it is possible to reduce redundancy dramatically and also create transition effects between views very easily.

##Basics

The routing module is started by specifying an optional root (defaults to '/') and a function callback where all the routes will be defined. Lets see the simplest possible example:

Gnd.router.listen(function(req: Request){
  req.get(function(){
    req.render('/templates/main.jade');	
  });
});

In this case we will render the jade template main.jade into the body tag.

Note that we used jade as an example template engine, any template engine can be used by ground, although it defaults to underscore microtemplates.

The template engine to use is defined by the use method of Gnd global object, for example to use jade as template engine:

Gnd.use.template(templ: string){
  return jade.compile(templ);
});

Since the system is hierarchical, if we want to add some more sub routes we can do it like so:

Gnd.router.listen(function(req){
  req.get(function(){
    req.render('/templates/main.jade');

	req.get('products', '#content', function(){
	  req.render('/templates/products.jade');

	  req.get('foo', '#content', function(){
		  req.render('/templates/foo.jade');
	  });

	  req.get('bar', '#content', function(){
		  req.render('/templates/bar.jade');
	  });
	});

	req.get('about', '#content', function(){
	  req.render('/templates/about.jade');
	});
  });
});

This simple example will handle the following routes:

/
/products
/products/foo
/products/bar
/about

Note that the second parameter in the get function is a node selector. This parameter is optional (defaulting to 'body'), and it is used by the render function to place the content, as well as used by the framework internally to provide some smart features.

Also note that the framework is taking care of the asynchronicity between calls, for example, the render function will fetch a template from the server, but the user does not need to wait for it before calling the next get functions.

##Entering the routes

The get method in the Request class defines a subroute in the route hierarchy. The callback parameter is used to determine what is going to happen when that subroute is matched by the url, for example we can call get again to define a new subroute or we can call several other methods that make useful things. These methods can be called in any order, but Ground will always call them in a specified order, and depending if we are entering or exiting the route different methods are called:

When entering the route:

Request##before(done?: ()=>void)
Request##load(url: string, done?: ()=>void)
Request##render(urlTemplate: string, urlCss?: string, done?: ()=>void)

Request##enter(el: HTMLElement, done?: ()=>void)
Request##after(done?: ()=>void)

When exiting the route:

Request##exit(el: HTMLElement, done?: ()=>void)

###Asynchronous and synchronous operations

Sometimes it is needed to do something after the function has finished, so render accepts a callback function for this means:

req.render('/templates/products.jade', function(done){
  // Do something asynchronous...
  done();
});

The callback takes an optional parameter done. This is a function used to tell the system that your function has finished doing what it was doing. You need this parameter only when your function performs asynchronous operations. If your callback is just doing simple synchronous stuff, just skip the parameter and the system will understand that it is a synchronous callback:

req.render('/templates/products.jade', function(){
  // Do something synchronous
});

Templates usually need data that may be fetched from the server as well. For that purpose, the function load can be used. Let's see an example:

gnd.route.listen(function(req){
  req.get(function(){
    req.render('/templates/main.jade');	

	req.get('news', '#content', function(){
	  req
        .load('/data/news.json');
        .render('/templates/news.jade');
	});
  });
});

load will fetch the data from the server and place it in req.data, which will be used by render placing it in the context variable of the template system.

###Transitions

The framework also provides a mechanism to make transitions between routes possible. They are enabled by using the pair of functions Request##enter and Request##exit.

enter will be called when the top DOM node for the route has been rendered, but it is still hidden. If you do not call enter, Ground will just show the DOM node directly without animation, otherwise, you can specify an animation using any framework of your choosing.

Lets see a simple example conveing animations using jquery:

Gnd.router.listen(function(req){
  req.get(function(){
    req
	    .render('/templates/main.jade')
      .enter(function(el, done){
      $(el).fadeIn(done)
    })
      .exit(function(el, done){
      $(el).fadeOut(done)
    });
  });
});

The call to exit will perform a fade out operation on the content of the body, while the call to exit will fade in the render