Rownd.js A super lightweight Front-End Framework

What is Rownd.js?

Rownd.js is a quick and simple Front-end framework. Lightweight and easier to build with than other MVC frameworks such as Angular.js or Ember.js.
It uses Ractive.js at it's heart which makes rendering pages instant and offers two way data-binding with a pre-defined and user tested model API.

Set Up

Setting up Rownd.js is very simple, just download the Start up kit and you're off.

Don't want to use the Start up kit? Just donwload Rownd and the Rownd template compiler from npm. Put it all together with Grunt and build something cool.

Installing with npm

              
  npm install rownd --save
  npm install rownd-ractive-compiler --save
              
            

Base Structure

Setting up your Rownd.js application only requires a few lines of code. First thing you have to do is create your own instance of Rownd.js with your desired configuration.

            
  var rnd = Rownd.start({
    'debug': true,
    'useHistory': true,
    'hideInfo': false,
    'showVersion': true,
    'rootUrl': ''
  });
            
          

Click here to learn more about the configuration options available in the start function.

After you've done that, you'll need to create a route to run. The first route should always be root. To create a route, use the createRoute() function and pass an object inside that declares your path and controller name.

            
  rnd.createRoute({
    'path': '',
    'controller': 'index'
  });
            
          

Now that you have a route and told Rownd what controller to use for that route, you need to create the controller itself. To create a controller, use the createController() function. This function requires two parameters; the controller name and the function which contains your initial view, controller logic and template actions. Check out the example below for more details.

            
  rnd.createController('index', function() {

    // Specifiy the initial template
    'view': {
      'template': 'index'
    },

    // All your logic goes here
    'controller': function(routeData){
    },

    //  All the template logic functions
    'actions': {
      'concat': funtion(wordOne, wordTwo) {
        return wordOne + wordTwo;
      }
    }
  });
            
          

The last step is to create a view using handlebars. To compile the handlebars files to Ractive templates you need to use the Rownd-Ractive-compiler.

Routes

History or Hashing

Routing can be done in Rownd in two different ways. If supported by the browser and useHistory is set to true, the URL routing will work just like a server routing system. If history isn't supported Rownd will fall back to loading each page just like a server with a page load.

If you'd rather just use a hashed URL which is supported on all browsers. Instead of linking to pages with strings such as /new-page, use a string such as this; #/new-page. Putting this hash there will allow Rownd to detect page changes without reloading when no history API is available.

Creating Routes

To create a route you will need to use the createRoute() function. To use this function you simply add it to your routes file and pass it an object with two parameters; controller and path. The controller item must be the same as the name of the controller you want to use and the path is the url you would like to use for this new page.

404 Pages

To create a 404 page you will need to utilize the routeNotFound() function. This function will fire whenever a route cannot be found. You can run anything you want inside this function but we suggest serving up a nice 404 page.

Variable Routes

Paths can contain variables by putting a : infront of the section. E.g. /users/:username. To access the variable you can get it from the routeData object inside your controller.

Templates

Templates in Rownd are handlebars files that are rendered by Ractive into html. Because they are rendered by ractive they are extremely quick to render. They also allow for two way data-binding between the controller and the template.

generateTemplate()

If you want to load in a partial template or render a whole new template on the current page you can use the generateTemplate() function. generateTemplate() only requires an object as it's parameter with the following contents.

• template - Name of the new template
• outlet - The location of the template. Leave out if you want to replace the whole document with the new template
• data - If you want to add any intial data when loading the template
• append - Append new template to the selected outlet or overwrites the outlet specified

Controllers

Controllers are where most of the logic for your application will be based. Some small logic may be in the template actions or in your helper library. Creating a controller is simple, just use the createController() function and match up the name of the controller with the name used in the createRoute() function. Below is an example controller:

            
  rwnd.createController('index', function() {

    // Specifiy the initial template
    'view': {
      'template': 'index',
      'data': {
        'foo': 'bar'
      }
    },

    // All your logic goes here
    'controller': function(routeData){
      // Change the value of foo to hello
      this.set({
        'foo': 'hello'
      });
    },

    //  All the template logic functions
    'actions': {
      'concat': funtion(wordOne, wordTwo) {
        return wordOne + wordTwo;
      }
    }
  });
            
          

Route Data

To get the current route data add the parameter routeData to the controller function and then you can use that variable to get the current path and the name of the controller you're currently using.

View Object

The view object is what Rownd uses to load in a template when a new route is hit and the controller is fired. This view object is ran through the generateTemplate function which means you can add data to the template by adding an object called data inside this view object.

Actions Object

The actions object is used to give functionality to the template. Inside here you can write functions that are accessable from the template.

Using Data-Binding

To use data binding in the controller you can use the Ractive get and set functions. Because the view is directly rendered with Ractive we can use all of Ractive's instance methods. Which you can find all the documentation here. You can also use these methods inside the templates themselves.

Ajax Requests

There's no need to pull in jQuery to do your Ajax requests. Rownd has built in Ajax requests implemented with promises that follow the ES6 specifications. Rownd uses the Ractive Promise polyfill for when there is no browser support for it.

            
  rnd.ajax('GET', '/foo').then(function(res) {
    // Log response
    console.log(res);
  });
            
          

The ajax function allows to any http method and setting of the content-type header.

            
  rnd.ajax('POST', '/foo', {foo: 'bar'}, 'application/json').then(function(res) {
    // Log response
    console.log(res);
  });
            
          

Promises

Rownd uses the Ractive Promise implementation which is simply a polyfill for the ES6 specification. Learn more about them here.

            
  rnd.Promise(function(resolve, reject) {
    if(true) {
      resolve('success');
    } else {
      reject('failed');
    }
  });
            
          

Helpers

Instead of using directives and injecting them like Angular.js, in Rownd you have the Helpers object. The Helpers object contains a range of functions created by simply adding an item to the Helpers object. Helpers can be used in any controller as many times as you want. Below is an example of creating a Helper using the Rownd instnace we set up at the top.

            
  rnd.Helpers.stringValidator = function(stringOne, stringTwo){
    return stringOne === stringTwo;
  };
            
          

Configuring Rownd

In Rownd there are four settings to configure. To set a configuration, add an object as a parameter to the start function. Then add an item to the object, of which the key will be the configuration setting your editing and the value as the value.