03 Using the framework

After setting up your project, the first thing that you'll probably want to do is to declare an instance of the framework and create a route.

Declaring an instance

After including the router in your project, declare a new instance of it. While creating a new instance, you can optionally pass it some config options to control how your router should behave, see config.

var router = new LodeRactive(/* Configure using an object */);

Creating Routes

Creating a route accepts an Object of options.

As the router operates by a hierarchy, you may be wondering how this shorthand would map to that hierarchy?

Simple! To declare a parent to a current route you wrap that part of the route in square brackets. For example:

Example

var router = new LodeRactive();

router.createRoute({
  path: '/',
  controller: {
    controller: function() {
      console.log('I am the index route!');
    }
  }
});

router.createRoute({
  path: '[/]dashboard',
  controller: {
    controller: function() {
      console.log('I am a child of that ^ index route!');
    }
  }
});

Dynamic Segments

Also as part of the routes, you can declare dynamic segments such as : or *. These dynamic segments allow for values that you may not yet know the value of to be provided such as a blog id. This data is then passed to your controller so that you can use it.

Note: By using Dynamic Segments, if you have two similar URLS that would match, the one that was declared first will take priority.

Dynamic Segment - :

This allows you to add one dynamic segment to your url:

Example

router.createRoute({
  path: '[/blog]/:id',
  controller: {
    controller: function( data ) {
      console.log(data.id + ': This is the id of the blog!' );
    }
  }
});

Wildcard Segment - *

This is a wildcard segment and allows for any amount of values to occur in your url and will return the data to your controller as an array of values:

E.g. '/blog/hello/1/2/3' will be matched to '[/blog]/*anything'.

Example

router.createRoute({
  path: '[/blog]/*anything',
  controller: {
    controller: function( data ) {
      console.log(data.anything + ': This is the array of wildcard values' );
    }
  }
});

Adding Views, Actions and Models

This is where Ractive comes in. If you pass the view option to createRoute, then you can make use of Ractive nearly the same as normal. I say nearly as we have changed how the events work a bit but I'll come to that in a second.

Views

Adding a view is nearly identical to how you add a view in Ractive, but with another cool feature. If you pass an object to template instead of the template string, then you can retrieve HTML from other pages of the website, providing that there is static HTML there i.e. before JavaScript is executed.

Example

var router = new LodeRactive();

router.createRoute({
  path: '/',
  view: {
    el: '#target-element',
    template: '<h1> I am a header </h1>'
  }
});

Actions

For this framework we have moved the .on() and .observe() events from the Ractive object and put them onto the router in an actions object to provide more separation between the two so that less code needs to go directly into the controller.

Example

var router = new LodeRactive();

router.createRoute({
  path: '/',
  controller: {

    actions: {
      sayHi: function(){
        alert('Hi!');
      }
    }

  },
  view: {
    el: '#target-element',
    template: '<h1 on-click="sayHi"> I am a header </h1>'
  }
});

Models

A model is an object that, in this framework, will represent the data of your controller and view. Using data binding any data that you have specified in your html to change, will also change the data available to your controller.

Example

var router = new LodeRactive();

router.createRoute({
  path: '/',
  controller: {

    controller: function() {
      console.log('This is my full name ' + this.get('fullName'));
    }

  },
  view: {
    el: '#target-element',
    template: '<input type="text" value="{{fullName}}"/>',
    data: { fullName: "Test Name" }
  }
});

Side note about controllers

One thing that you may notice, is that you will see the keyword controller is nested with an object named controller. This is because we will be building a cli and we think it will provide clarity when code becomes separated e.g. controllers into their own files. See our homepage source code for an example!