# Interface ParamTypeDefinition

Describes a custom [[ParamType]]

See: [[UrlMatcherFactory.type]]

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 <integer/date/string>
- custom object
- some internal 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: [[UrlConfig.type]]

interface ParamTypeDefinition {
dynamic?: boolean;
inherit?: boolean;
pattern?: RegExp;
raw?: boolean;
decode(val: string, key?: string): any;
encode(val: any, key?: string): string | string[];
equals(a: any, b: any): boolean;
is(val: any, key?: string): boolean;
}

- Defined in src/router/params/interface.ts:479

##### Index

### Properties

dynamic?
inherit?
pattern?
raw?

### Methods

decode
encode
equals
is

## Properties

### `Optional` dynamic

dynamic?: boolean

Dynamic flag

When `dynamic` is `true`, changes to the parameter value will not cause the state to be entered/exited.

Normally, if a parameter value changes, the state which declared that the parameter will be reloaded (entered/exited). When a parameter is `dynamic`, a transition still occurs, but it does not cause the state to exit/enter.

Default: `false`

- Defined in src/router/params/interface.ts:546

### `Optional` inherit

inherit?: boolean

Enables/disables inheriting of parameter values (of this type)

When a transition is run with [[TransitionOptions.inherit]] set to `true`, the current param values are inherited in the new transition. However, parameters whose type has `inherit: false` set will not be inherited.

The internal parameter type of `hash` has `inherit: false`. This is used to disable inheriting of the hash value (`#`) on subsequent transitions.

#### Example:

    $state.go('home', { '#': 'inboxAnchor' });
    ...
    // "#" is not inherited.
    // The value of the "#" parameter will be `null`
    // The url's hash will be cleared.
    $state.go('home.nest');

See also [[TransitionOptions.inherit]] and [[ParamDeclaration.inherit]]

- Defined in src/router/params/interface.ts:534

### `Optional` pattern

pattern?: RegExp

A regular expression that matches the encoded parameter type

This regular expression is used to match an encoded parameter value in the URL.

For example, if your type encodes as a dash-separated numbers, match that here: `new RegExp("[0-9]+(?:-[0-9]+)*")`.

There are some limitations to these regexps:

- No capturing groups are allowed (use non-capturing groups: `(?: )`)
- No pattern modifiers like case insensitive
- No start-of-string or end-of-string: `/^foo$/`

- Defined in src/router/params/interface.ts:494

### `Optional` raw

raw?: boolean

Disables url-encoding of parameter values

If a parameter type is declared `raw`, it will not be url-encoded. Custom encoding can still be applied in the [[encode]] function.

### Decoding warning

The decoding behavior of raw parameters is not defined. See: [[ParamDeclaration.raw]] for details

- Defined in src/router/params/interface.ts:507

## Methods

### decode

- decode(val: string, key?: string): any

  Decodes a parameter value string (from URL string or transition param) to a custom/native value.

  For example, if your type decodes to an array of ints, then decode the string as an array of ints here:

      decode: (str) => str.split("-").map(str => parseInt(str, 10))

  Note: in general, [[encode]] and [[decode]] should be symmetrical. That is, `encode(decode(str)) === str`

  #### Parameters

  - val: string

    The URL parameter value to decode.

  - `Optional` key: string

    The name of the parameter in which `val` is stored. Can be used for meta-programming of `ParamType` objects.

  #### Returns any

  a custom representation of the URL parameter value.

  - Defined in src/router/params/interface.ts:611

### encode

- encode(val: any, key?: string): string | string[]

  Encodes a custom/native type value to a string that can be embedded in a URL.

  Note that the return value does not need to be URL-safe (i.e. passed through `encodeURIComponent()`). It only needs to be a representation of `val` that has been encoded as a string.

  For example, if your custom type decodes to an array of ints, then encode the array of ints to a string here:

      encode: (intarray) => intarray.join("-")

  Note: in general, [[encode]] and [[decode]] should be symmetrical. That is, `encode(decode(str)) === str`

  #### Parameters

  - val: any

    The value to encode.

  - `Optional` key: string

    The name of the parameter in which `val` is stored. Can be used for meta-programming of `ParamType` objects.

  #### Returns string | string[]

  a string representation of `val` that can be encoded in a URL.

  - Defined in src/router/params/interface.ts:595

### equals

- equals(a: any, b: any): boolean

  Determines whether two decoded values are equivalent.

  For example, if your type decodes to an array of ints, then check if the arrays are equal:

      equals: (a, b) => a.length === b.length && a.reduce((acc, x, idx) => acc && x === b[idx], true)

  #### Parameters

  - a: any

    A value to compare against.

  - b: any

    A value to compare against.

  #### Returns boolean

  `true` if the values are equivalent/equal, otherwise `false`.

  - Defined in src/router/params/interface.ts:625

### is

- is(val: any, key?: string): boolean

  Tests if some object type is compatible with this parameter type

  Detects whether some value is of this particular type. Accepts a decoded value and determines whether it matches this `ParamType` object.

  If your custom type encodes the parameter to a specific type, check for that type here. For example, if your custom type decodes the URL parameter value as an array of ints, return true if the input is an array of ints:

      is: (val) => Array.isArray(val) && array.reduce((acc, x) => acc && parseInt(val, 10) === val, true)

  If your type decodes the URL parameter value to a custom string, check that the string matches the pattern (don't use an arrow fn if you need `this`): `function (val) { return !!this.pattern.exec(val) }`

  Note: This method is not used to check if the URL matches. It's used to check if a decoded value is this type. Use [[pattern]] to check the encoded value in the URL.

  #### Parameters

  - val: any

    The value to check.

  - `Optional` key: string

    If the type check is happening in the context of a specific [[UrlMatcher]] object, this is the name of the parameter in which `val` is stored. Can be used for meta-programming of `ParamType` objects.

  #### Returns boolean

  `true` if the value matches the type, otherwise `false`.

  - Defined in src/router/params/interface.ts:575