ui-router
Version:
State-based routing for Javascript
270 lines (257 loc) • 8.44 kB
text/typescript
/** @module params */ /** for typedoc */
import {Type} from "./type";
export interface RawParams {
[key: string]: any;
}
export type ParamsOrArray = (RawParams|RawParams[]);
/**
* Inside a [[StateDeclaration.params]]:
*
* A ParamDeclaration object defines how a single State Parameter should work.
*
* @example
* ```
*
* var mystate = {
* template: '<div ui-view/>',
* controller: function() {}
* url: '/mystate/:param1',
* params: {
* param1: "index", // <-- Default value for 'param1'
* // (shorthand ParamDeclaration)
*
* nonUrlParam: { // <-- ParamDeclaration for 'nonUrlParam'
* type: "int",
* array: true,
* value: []
* }
* }
* }
* ```
*/
export interface ParamDeclaration {
/**
* A property of [[ParamDeclaration]]:
*
* Specifies the default value for this parameter. This implicitly sets this parameter as optional.
*
* When UI-Router routes to a state and no value is specified for this parameter in the URL or transition,
* the default value will be used instead. If value is a function, it will be injected and invoked, and the
* return value used.
*
* Note: `value: undefined` is treated as though no default value was specified, while `value: null` is treated
* as "the default value is null".
*
* ```
* // define default values for param1 and param2
* params: {
* param1: {
* value: "defaultValue"
* },
* param2: {
* value: "param2Default;
* }
* }
* ```
*
* ### Shorthand Declaration
* If you only want to set the default value of the parameter, you may use a shorthand syntax.
* In the params map, instead mapping the param name to a full parameter configuration object, simply set map it
* to the default parameter value, e.g.:
* ```
* // define a parameter's default value
* params: {
* param1: {
* value: "defaultValue"
* },
* param2: {
* value: "param2Default;
* }
* }
*
* // shorthand default values
* params: {
* param1: "defaultValue",
* param2: "param2Default"
* }
* ```
*
* This defines a default value for the parameter. If the parameter value is `undefined`, this value will be used instead
*/
value?: any;
/**
* A property of [[ParamDeclaration]]:
*
* Specifies the [[Type]] of the parameter.
*
* Set this property to the name of parameter's type. The type may be either one of the
* built in types, or a custom type that has been registered with the [[$urlMatcherFactory]]
*/
type: (string|Type);
/**
* A property of [[ParamDeclaration]]:
*
* Explicitly specifies the array mode of a URL parameter
*
* - If `false`, the parameter value will be treated (encoded/decoded) as a single value
* - If `true`, the parameter value will be treated (encoded/decoded) as an array of values.
* - If `auto` (for query parameters only), if multiple values for a single parameter are present
* in the URL (e.g.: /foo?bar=1&bar=2&bar=3) then the values are mapped to an array (e.g.:
* `{ foo: [ '1', '2', '3' ] }`). However, if only one value is present (e.g.: /foo?bar=1)
* then the value is treated as single value (e.g.: { foo: '1' }).
*
* If you specified a [[type]] for the parameter, the value will be treated as an array
* of the specified Type.
*
* @example
* ```
*
* {
* name: 'foo',
* url: '/foo/{arrayParam:int}`,
* params: {
* arrayParam: { array: true }
* }
* }
*
* // After the transition, URL should be '/foo/1-2-3'
* $state.go("foo", { arrayParam: [ 1, 2, 3 ] });
* ```
*
* @default `false` for path parameters, such as `url: '/foo/:pathParam'`
* @default `auto` for query parameters, such as `url: '/foo?queryParam'`
* @default `true` if the parameter name ends in `[]`, such as `url: '/foo/{implicitArrayParam:int[]}'`
*/
array: boolean;
/**
* A property of [[ParamDeclaration]]:
*
* Configures how a default parameter value is represented in the URL when the current parameter value
* is the same as the default value.
*
* There are three squash settings:
*
* - `false`: The parameter's default value is not squashed. It is encoded and included in the URL
* - `true`: The parameter's default value is omitted from the URL. If the parameter is preceeded
* and followed by slashes in the state's url declaration, then one of those slashes are omitted.
* This can allow for cleaner looking URLs.
* - `"<arbitrary string>"`: The parameter's default value is replaced with an arbitrary
* placeholder of your choice.
*
* @example
* ```
*
* {
* name: 'mystate',
* url: '/mystate/:myparam',
* params: {
* myparam: 'defaultParamValue'
* squash: true
* }
* }
*
* // URL will be `/mystate/`
* $state.go('mystate', { myparam: 'defaultParamValue' });
*
* // URL will be `/mystate/someOtherValue`
* $state.go('mystate', { myparam: 'someOtherValue' });
* ```
*
* @example
* ```
*
* {
* name: 'mystate2',
* url: '/mystate2/:myparam2',
* params: {
* myparam2: 'defaultParamValue'
* squash: "~"
* }
* }
*
* // URL will be `/mystate/~`
* $state.go('mystate', { myparam2: 'defaultParamValue' });
*
* // URL will be `/mystate/someOtherValue`
* $state.go('mystate', { myparam2: 'someOtherValue' });
* ```
*
* If squash is not set, it uses the configured default squash policy. (See [[defaultSquashPolicy]]())
*/
squash: (boolean|string);
/**
* @hidden
* @internalapi
*
* An array of [[Replace]] objects.
*
* When creating a Transition, defines how to handle certain special values, such as `undefined`, `null`,
* or empty string `""`. If the transition is started, and the parameter value is equal to one of the "to"
* values, then the parameter value is replaced with the "from" value.
*
* @example
* ```
*
* replace: [
* { from: undefined, to: null },
* { from: "", to: null }
* ]
*/
replace: Replace[];
/**
* @hidden
* @internalapi
*
* This is not part of the declaration; it is a calculated value depending on if a default value was specified or not.
*/
isOptional: boolean;
/** @todo document this one too */
dynamic: boolean;
}
export interface Replace {
from: string;
to: string;
}
/**
* Defines the behavior of a custom [[Type]].
* See: [[UrlMatcherFactory.type]]
*/
export interface TypeDefinition {
/**
* Detects whether a value is of a particular type. Accepts a native (decoded) value
* and determines whether it matches the current `Type` object.
*
* @param val The value to check.
* @param key 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 `Type` objects.
* @returns `true` if the value matches the type, otherwise `false`.
*/
is(val: any, key?: string): boolean;
/**
* 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 coerced to a string.
*
* @param val The value to encode.
* @param key The name of the parameter in which `val` is stored. Can be used for meta-programming of `Type` objects.
* @returns a string representation of `val` that can be encoded in a URL.
*/
encode(val: any, key?: string): (string|string[]);
/**
* Converts a parameter value (from URL string or transition param) to a custom/native value.
*
* @param val The URL parameter value to decode.
* @param key The name of the parameter in which `val` is stored. Can be used for meta-programming of `Type` objects.
* @returns a custom representation of the URL parameter value.
*/
decode(val: string, key?: string): any;
/**
* Determines whether two decoded values are equivalent.
*
* @param a A value to compare against.
* @param b A value to compare against.
* @returns `true` if the values are equivalent/equal, otherwise `false`.
*/
equals(a: any, b: any): boolean;
}