Interface ParamTypeDefinition

A developer can create a custom parameter type definition to customize the encoding and decoding of parameter values. The definition should implement all the methods of this interface.

Parameter values are parsed from the URL as strings. However, it is often useful to parse the string into some other form, such as:

• integer
• date
• array of
• custom object
• some custom string representation

Typed parameter definitions control how parameter values are encoded (to the URL) and decoded (from the URL). UI-Router always provides the decoded parameter values to the user from methods such as Transition.params.

For example, if a state has a url of /foo/{fooId:int} (the fooId parameter is of the int ParamType) and if the browser is at /foo/123, then the 123 is parsed as an integer:

var fooId = transition.params().fooId;
fooId === "123" // false
fooId === 123 // true

Examples

This example encodes an array of integers as a dash-delimited string to be used in the URL.

If we call $state.go('foo', { fooIds: [20, 30, 40] });, the URL changes to /foo/20-30-40. If we navigate to /foo/1-2-3, the foo state's onEnter logs [1, 2, 3].

example

$urlMatcherFactoryProvider.type('intarray', {
  // Take an array of ints [1,2,3] and return a string "1-2-3"
  encode: (array) => array.join("-"),

  // Take an string "1-2-3" and return an array of ints [1,2,3]
  decode: (str) => str.split("-").map(x => parseInt(x, 10)),

  // Match the encoded string in the URL
  pattern: new RegExp("[0-9]+(?:-[0-9]+)*")

  // Ensure that the (decoded) object is an array, and that all its elements are numbers
  is: (obj) => Array.isArray(obj) &&
      obj.reduce((acc, item) => acc && typeof item === 'number', true),

  // Compare two arrays of integers
  equals: (array1, array2) => array1.length === array2.length &&
      array1.reduce((acc, item, idx) => acc && item === array2[idx], true);
});

$stateProvider.state('foo', {
  url: "/foo/{fooIds:intarray}",
  onEnter: function($transition$) {
    console.log($transition$.fooIds); // Logs "[1, 2, 3]"
  }
});

This example decodes an integer from the URL. It uses the integer as an index to look up an item from a static list. That item from the list is the decoded parameter value.

example

var list = ['John', 'Paul', 'George', 'Ringo'];

$urlMatcherFactoryProvider.type('listItem', {
  encode: function(item) {
    // Represent the list item in the URL using its corresponding index
    return list.indexOf(item);
  },
  decode: function(item) {
    // Look up the list item by index
    return list[parseInt(item, 10)];
  },
  is: function(item) {
    // Ensure the item is valid by checking to see that it appears
    // in the list
    return list.indexOf(item) > -1;
  }
});

$stateProvider.state('list', {
  url: "/list/{item:listItem}",
  controller: function($scope, $stateParams) {
    console.log($stateParams.item);
  }
});

// ...

// Changes URL to '/list/3', logs "Ringo" to the console
$state.go('list', { item: "Ringo" });

See: UrlMatcherFactory.type