It’s possible to map URLs by the configuration files for Routing. URLs are restricted to the routes only declared in route.yml.

Configuring A Route For Home Page

You have just one route and is for homepage after generating an application.

preference/your_environment/route.yml

WelcomeHandler:
    path: /
    execute: index
    template: welcome/index
    css: /css/welcome.css
    page-title: Welcome

WelcomeHandler is a Handler that will be used on the above route.

Handler is explained this chapter.

The above route matches http://example.com or http://example.com/.

css and page-title are custom fields. Custom fields will be assigned into your template files automatically. It’s possible to reference the above value by {{field-name}} in your template files. e.g. {{css}}, {{page-title}}

The Required Directive

The values on path directive will be converted to regular expression.

The Optional Directives

path directive is the required though, there are some optional directives for routes.

Configuring Multiple Pathes

It’s possible to set multiple paths by regular expression.

preference/environment_name/route.yml

FooHandler
    path: /(foo|bar|baz)
    execute: index

The above route matchs on following URLs http://example.com/foo or http://example.com/bar or http://example.com/baz.

It’s possible to use the same Handler again any times you want.

FooHandler
    path: /foo
    execute: index

FooHandler
    path: /bar
    execute: index

FooHandler
    path: /baz
    execute: index

Configuring Routes

This is a tutorial to configure routes.

1. First, setting a Handler class to use in a route.

FooHandler:

There is a need to create FooHandler, but let's put that aside for now.

2. Filling ‘path’ directive

FooHandler:
    path: /foo

path directive is the required. It's supposed to be set in each of routes.

path is supposed to be started from slash.

3. Setting the Handler’s method

FooHandler:
    path: /foo
    execute: do_something

You can set template and/or layout in your Handlers but it’s possible to set them by the directives.

FooHandler:
    path: /foo
    execute: do_something
    template: article/index
    layout: default

Requesting http://example.com/foo matchs this route and the method named foo in FooHandler will be called. template/article/index.tpl and template/layout/default.tpl will be rendered.

Custom Fields

Anything not listed in the above directives are special. That will be assigned in your template files automatically.

Example

Setting Custom Fields

FooHandler:
    path: /foo
    name: Luna
    state: kittien

handler is the reserved word for route_error.yml.

Referencing Custom Fields In Liquid templates

Output is => {{name}} is {{state}}.

The above string will be replaced to Output is => Luna is kittien.

Referencing Custom Fields In Handler

Custom Fields has been set in @custom_fields.

class FooHandler < BaseHandler
    def index
        p @custom_fields #=> {"name"=>"Luna", "state"=>"kittien"}
    end
end

Empty Hash object will be set in @custom_fields in case of no Custom Fields given.

URL Path Parameters

It’s possible to get input from URL paths. Staring from : in path directive is special.

Just for instance,

preference/environment_name/route.yml

ArticleHandler:
    path: /article/:user_id/:id
    execute: index
    method: get
    content: json

There is a need to generate ArticleHandler.

Creating ArticleHandler

$ nekonote new handler article #=> handler/article.rb will be generated

The above route matches http://example.com/article/99/2002.

Nekonote::Request class object is set to a property named @request. You can reference the values from URL by @request.path_params.

handler/article.rb

class ArticleHandler < BaseHandler
    def index
        @request.path_params #=> {"user_id"=>"99", "id"=>"2002"}
        @request.path_params 'user_id' #=> 99
        @request.path_params :id #=> 2002   # symbol is OK as well
        @request.path_params 'not-defined' #=> nil
    end
end

Configuring Common Preferences

route_include.yml is supposed to configure a group of some common preferences to configure routes in route.yml.

preference/your_environment/route_include.yml

article:
    content: json

preference/your_environment/route.yml

GetHandler:
    path: /get
    execute: get
    include: article

EditHandler:
    path: /add
    execute: add
    method: post
    include: article

EditHandler:
    path: /sort
    execute: sort
    method: post
    include: article

The directives in route.yml take precedence.