ruta v0.2.71

RutaJS

RouteKey-Value Collection for Browser and Node.js

Mainly used for an application routing, but can be used for any other purpose

Route

• strict match part(s) - /user (same as !/user) does not match `/user/bob
• begins with part(s) - ^/user matches /user/bob, but does not /users
• optional parts - /?foo Matches only / and /foo paths
• regexp - enclosed in parentheses '(regexp)' - (\.less$) - /user/:action(edit|delete) - /user/:action([a-z]{2,4})
• method - $post /user
• query string (matches key/value at any position(order) in query string) - ?debug - ?debug=js - ?debug=(js|less) (in parenthese regexp is used, note here is also full-match is used - ?:debugger(d|debug)=(js|less) match d=less like debugger: 'less'

Parts

Each route definition (path) is split into parts (folders).

Each part (folder) can be

• strict (default behaviour) /user/:name - all are strict
• optional: /user/?:name - user is strict, but next folder with alias name is optional.
• alias, seen from example above: /user/:name
• alias with regexp: /user/:name(\w{3,8})
• alias with possible values /:action(create|edit|remove)

Collection

Route-Value Collection.

/**
  * @param route <String> : route definition
  * @param obj <Any> : value to store in collection
 \*/
ruta.Collection.prototype.add(route, obj <Any>);


/**
  * @param path <String>: url string
  * @param method <String>: optional, request method GET, POST, DELETE, PUT
  * @return route <Object> {
  *      value <Any> - stored value,
  *      current <Object> {
  *          params <Object>, - holds alias values and querystring arguments
  *          url <String>
  *      }
  * }
 \*/
ruta.Collection.prototype.get(path, ?method);

import ruta from 'ruta'

const collection = new ruta.Collection();

collection
    .add('/user/:id', {foo: 'bar'});

const route = collection.get('/user/20');

route.value === { foo: 'bar' };
route.current.params.id === 20;

Router

If collection is bound to a router, then each item value in the collection should be a function, which will be called, when router emits the URL-change event.

RutaJS supports History API and hashchanged routing.

:warning: ruta object is already the route collection itself. And there is History API Router bound to this collection, or hash as a fallback;

Api

• .add(definition:String, mix:Any) Adds anything to the collection

  	- `definition` String routing definition
  	- `mix` Any Object, that you can later retrieve via `.get` method. When `mix` is a `Function`, then it will be additionally bound to the Router

• .get(url:String) Gets first object from the collection matches the url

• .getAll(url:String) Gets all objects from the collection matches the url

• .navigate(url:String, ?options:Object) Navigate the Router to the url

  	- `options`
  
  		- `extend:Boolean` Preserve current query string parameters, which are not in url string
  		- `silent:Boolean` Default: `false`; Do not trigger change event
  		- `replace:Boolean` Default: `false`; For the History API `replaceState` is used.

Examples

var collection = new ruta.Collection();

collection.add('/user/:id', myObject);
collection.get('/user/10') // -> { key: '/user/:id', value: myObject, current: { id: 10 } }

// Will match '/foo', '/foo/bar', ...
collection.add('^/foo', x);

// Strict Pattern, match '/foo'
collection.add('/foo')
collection.add('/foo?query=string')


// Conditional
collection.add('/user/?:id')


// Query String
collection.add('/users', X);
collection.get('/users?loc=DE')
//> { key: '/users', value: X, current: { params: { loc: 'DE' }, url: '/users?loc=DE' } }

Atma.js Project