sails-pathfinder v0.1.1

sails-pathfinder

Get the route to a given controller action so you don't have to hardcode URLs in your sails.js views and redirects.

In Sails it's easy to fall into the trap of hardcoding links in html templates. Instead of hardcoding the links, this module lets you specify the controller action that a link must lead to. Changing the route to a controller action will be as simple as editing the route to it in config/routes.js. You shouldn't need to edit your views and controllers.

Installation

In your sails project, use npm install:

$ npm install sails-pathfinder

Quick Start

The easiest way to use this module is to expose it as a sails service. Make a service file named ActionPath.js (the name is arbitrary):

// api/services/ActionPath.js
var pathfinder = require('sails-pathfinder').use(sails.config.routes);
module.exports = pathfinder.action;

In your views, write URLs using ActionPath:

<!-- Given a route to the UserController's login action in your config/routes.js,
write -->
<form id="loginForm" action="<%= ActionPath('User.login') %>" method="post">
<!-- instead of -->
<form id="loginForm" action="/login" method="post">

<!-- write -->
<a href="<%= ActionPath('User.viewProfile', {id:user.id}) %>">Profile</a>
<!-- instead of -->
<a href="/users/<%= user.id %>/profile">Profile</a>

And in your controller code, e.g. for redirects:

// write
res.redirect(ActionPath('User.login'));
// instead of
res.redirect('/login');

More Examples

Example: route that uses a single parameter

// Given this route in config/routes.js
'/countries/:country': 'CountryController.get'

var pathfinder = require('sails-pathfinder').use(sails.config.routes);
pathfinder.action('Country.get', 'USA') == '/countries/USA';
pathfinder.action('Country.get', 123) == '/countries/123';
pathfinder.action('Country.get', [456]) == '/countries/456';
// Passing an object only works if the parameter is named. It won't work if the parameter is a wildcard.
pathfinder.action('Country.get', {country: 'PH'}) == '/countries/PH';

Example: route that uses multiple :param parameters

// Given this route in config/routes.js
'get /collections/:collection/products/:product': {
  controller: 'ProductController', // 'Product' works too
  action: 'getCollectionProduct'
}

var pathfinder = require('sails-pathfinder').use(sails.config.routes);
// The second argument can be an object or an array
pathfinder.action('Product.getCollectionProduct', {collection:25,product:'some-product'}) == '/collections/25/products/some-product';
pathfinder.action('Product.getCollectionProduct', [32, 'a-product']) == '/collections/32/products/a-product'

Example: route that uses *:

// Given this route in config/routes.js
'/users/*/posts/*': 'PostController.getUserPosts'

var pathfinder = require('sails-pathfinder').use(sails.config.routes);
pathfinder.action('Post.getUserPosts', ['tyrion', 9]) == '/users/tyrion/posts/9';

API

var pathfinder = require('sails-pathfinder')

// Give pathfinder the app's routes. This only needs to be called once. Calling it more than once is fine, but not necessary.
pathfinder.use(sails.config.routes);

// Get the path to a controller action
var path = pathfinder.action('Dog.feed', {dog:'poco'});

The main function to use is pathfinder.action(action, params). This returns the request path that routes to the given action.

• The first argument has to be a string of the form ControllerName.actionName, e.g. User.edit
• The second argument params is required if there are parameters in the action's route. If the path parameters are named (e.g. /user/:id), params can be an object. If the path parameters are not named (e.g. /users/*/posts/*), params must be an array.