ui-router-core
Version:
UI-Router Core: Framework agnostic, State-based routing for JavaScript Single Page Apps
514 lines (513 loc) • 18.6 kB
TypeScript
/**
* # URL subsystem
*
* Contains code related to managing the URL
*
* The primary API is found in [[UrlService]], [[UrlService.config]], and [[UrlService.rules]].
*
* @preferred
* @coreapi
* @module url
*/ /** */
import { LocationConfig } from "../common/coreservices";
import { ParamType } from "../params/paramType";
import { Param } from "../params/param";
import { UIRouter } from "../router";
import { TargetState } from "../state/targetState";
import { TargetStateDef } from "../state/interface";
import { UrlMatcher } from "./urlMatcher";
import { StateObject } from "../state/stateObject";
import { ParamTypeDefinition } from "../params/interface";
/** @internalapi */
export interface ParamFactory {
/** Creates a new [[Param]] from a CONFIG block */
fromConfig(id: string, type: ParamType, config: any): Param;
/** Creates a new [[Param]] from a url PATH */
fromPath(id: string, type: ParamType, config: any): Param;
/** Creates a new [[Param]] from a url SEARCH */
fromSearch(id: string, type: ParamType, config: any): Param;
}
/**
* An API to customize the URL behavior and retrieve URL configuration
*
*
* This API can customize the behavior of the URL.
* This includes optional trailing slashes ([[strictMode]]), case sensitivity ([[caseInsensitive]]),
* and custom parameter encoding (custom [[type]]).
*
* It also has information about the location (url) configuration such as [[port]] and [[baseHref]].
* This information can be used to build absolute URLs, such as
* `https://example.com:443/basepath/state/substate?param1=a#hashvalue`;
*
* This API is found on [[UrlService.config]].
*/
export interface UrlConfigApi extends LocationConfig, UrlMatcherConfig {
}
export interface UrlMatcherConfig {
/**
* Defines whether URL matching should be case sensitive (the default behavior), or not.
*
* #### Example:
* ```js
* // Allow case insensitive url matches
* urlService.config.caseInsensitive(true);
* ```
*
* @param value `false` to match URL in a case sensitive manner; otherwise `true`;
* @returns the current value of caseInsensitive
*/
caseInsensitive(value?: boolean): boolean;
/**
* Defines whether URLs should match trailing slashes, or not (the default behavior).
*
* #### Example:
* ```js
* // Allow optional trailing slashes
* urlService.config.strictMode(false);
* ```
*
* @param value `false` to match trailing slashes in URLs, otherwise `true`.
* @returns the current value of strictMode
*/
strictMode(value?: boolean): boolean;
/**
* Sets the default behavior when generating or matching URLs with default parameter values.
*
* #### Example:
* ```js
* // Remove default parameter values from the url
* urlService.config.defaultSquashPolicy(true);
* ```
*
* @param value A string that defines the default parameter URL squashing behavior.
* - `nosquash`: When generating an href with a default parameter value, do not squash the parameter value from the URL
* - `slash`: When generating an href with a default parameter value, squash (remove) the parameter value, and, if the
* parameter is surrounded by slashes, squash (remove) one slash from the URL
* - any other string, e.g. "~": When generating an href with a default parameter value, squash (remove)
* the parameter value from the URL and replace it with this string.
* @returns the current value of defaultSquashPolicy
*/
defaultSquashPolicy(value?: (boolean | string)): (boolean | string);
/**
* Creates and registers a custom [[ParamTypeDefinition]] object
*
* A custom parameter type can be used to generate URLs with typed parameters or custom encoding/decoding.
*
* #### Note: Register custom types *before using them* in a state definition.
*
* #### Example:
* ```js
* // Encode object parameter as JSON string
* urlService.config.type('myjson', {
* encode: (obj) => JSON.stringify(obj),
* decode: (str) => JSON.parse(str),
* is: (val) => typeof(val) === 'object',
* pattern: /[^/]+/,
* equals: (a, b) => _.isEqual(a, b),
* });
* ```
*
* @param name The type name.
* @param type The type definition. See [[ParamTypeDefinition]] for examples and information.
*
* @returns if only the `name` parameter was specified: the currently registered [[ParamType]] object, or undefined
*/
type(name: string, type?: ParamTypeDefinition): ParamType;
}
/** @internalapi */
export interface UrlSyncApi {
/**
* Checks the URL for a matching [[UrlRule]]
*
* Checks the current URL for a matching url rule, then invokes that rule's handler.
* This method is called internally any time the URL has changed.
*
* This effectively activates the state which matches the current URL.
*
* #### Example:
* ```js
* urlService.deferIntercept();
*
* $http.get('/states.json').then(function(resp) {
* resp.data.forEach(state => $stateRegistry.register(state));
* urlService.listen();
* // Find the matching URL and invoke the handler.
* urlService.sync();
* });
* ```
*/
sync(evt?: any): void;
/**
* Starts or stops listening for URL changes
*
* Call this sometime after calling [[deferIntercept]] to start monitoring the url.
* This causes [[UrlRouter]] to start listening for changes to the URL, if it wasn't already listening.
*
* If called with `false`, will stop listening. Call listen() again to start listening
*
* #### Example:
* ```js
* urlService.deferIntercept();
*
* $http.get('/states.json').then(function(resp) {
* resp.data.forEach(state => $stateRegistry.register(state));
* // Start responding to URL changes
* urlService.listen();
* urlService.sync();
* });
* ```
*/
listen(enabled?: boolean): Function;
/**
* Disables monitoring of the URL.
*
* Call this method before UI-Router has bootstrapped.
* It will stop UI-Router from performing the initial url sync.
*
* This can be useful to perform some asynchronous initialization before the router starts.
* Once the initialization is complete, call [[listen]] to tell UI-Router to start watching and synchronizing the URL.
*
* #### Example:
* ```js
* // Prevent $urlRouter from automatically intercepting URL changes when it starts;
* urlService.deferIntercept();
*
* $http.get('/states.json').then(function(resp) {
* resp.data.forEach(state => $stateRegistry.register(state));
* urlService.listen();
* urlService.sync();
* });
* ```
*
* @param defer Indicates whether to defer location change interception.
* Passing no parameter is equivalent to `true`.
*/
deferIntercept(defer?: boolean): any;
}
/**
* API for managing URL rules
*
* This API can be used to create and manage URL rules.
* URL rules are a mechanism to respond to specific URL patterns.
*
* The most commonly used methods are [[otherwise]] and [[when]].
*/
export interface UrlRulesApi {
/**
* Defines URL Rule priorities
*
* More than one rule ([[UrlRule]]) might match a given URL.
* This `compareFn` is used to sort the rules by priority.
* Higher priority rules should sort earlier.
*
* The [[defaultRuleSortFn]] is used by default.
*
* You only need to call this function once.
* The `compareFn` will be used to sort the rules as each is registered.
*
* If called without any parameter, it will re-sort the rules.
*
* ---
*
* Url rules may come from multiple sources: states's urls ([[StateDeclaration.url]]), [[when]], and [[rule]].
* Each rule has a (user-provided) [[UrlRule.priority]], a [[UrlRule.type]], and a [[UrlRule.$id]]
* The `$id` is is the order in which the rule was registered.
*
* The sort function should use these data, or data found on a specific type
* of [[UrlRule]] (such as [[StateRule.state]]), to order the rules as desired.
*
* #### Example:
* This compare function prioritizes rules by the order in which the rules were registered.
* A rule registered earlier has higher priority.
*
* ```js
* function compareFn(a, b) {
* return a.$id - b.$id;
* }
* ```
*
* @param compareFn a function that compares to [[UrlRule]] objects.
* The `compareFn` should abide by the `Array.sort` compare function rules.
* Given two rules, `a` and `b`, return a negative number if `a` should be higher priority.
* Return a positive number if `b` should be higher priority.
* Return `0` if the rules are identical.
*
* See the [mozilla reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Description)
* for details.
*/
sort(compareFn?: (a: UrlRule, b: UrlRule) => number): any;
/**
* Registers a `matcher` and `handler` for custom URLs handling.
*
* The `matcher` can be:
*
* - a [[UrlMatcher]]: See: [[UrlMatcherFactory.compile]]
* - a `string`: The string is compiled to a [[UrlMatcher]]
* - a `RegExp`: The regexp is used to match the url.
*
* The `handler` can be:
*
* - a string: The url is redirected to the value of the string.
* - a function: The url is redirected to the return value of the function.
*
* ---
*
* When the `handler` is a `string` and the `matcher` is a `UrlMatcher` (or string), the redirect
* string is interpolated with parameter values.
*
* #### Example:
* When the URL is `/foo/123` the rule will redirect to `/bar/123`.
* ```js
* .when("/foo/:param1", "/bar/:param1")
* ```
*
* ---
*
* When the `handler` is a string and the `matcher` is a `RegExp`, the redirect string is
* interpolated with capture groups from the RegExp.
*
* #### Example:
* When the URL is `/foo/123` the rule will redirect to `/bar/123`.
* ```js
* .when(new RegExp("^/foo/(.*)$"), "/bar/$1");
* ```
*
* ---
*
* When the handler is a function, it receives the matched value, the current URL, and the `UIRouter` object (See [[UrlRuleHandlerFn]]).
* The "matched value" differs based on the `matcher`.
* For [[UrlMatcher]]s, it will be the matched state params.
* For `RegExp`, it will be the match array from `regexp.exec()`.
*
* If the handler returns a string, the URL is redirected to the string.
*
* #### Example:
* When the URL is `/foo/123` the rule will redirect to `/bar/123`.
* ```js
* .when(new RegExp("^/foo/(.*)$"), match => "/bar/" + match[1]);
* ```
*
* Note: the `handler` may also invoke arbitrary code, such as `$state.go()`
*
* @param matcher A pattern `string` to match, compiled as a [[UrlMatcher]], or a `RegExp`.
* @param handler The path to redirect to, or a function that returns the path.
* @param options `{ priority: number }`
*
* @return the registered [[UrlRule]]
*/
when(matcher: (RegExp | UrlMatcher | string), handler: string | UrlRuleHandlerFn, options?: {
priority: number;
}): UrlRule;
/**
* Defines the state, url, or behavior to use when no other rule matches the URL.
*
* This rule is matched when *no other rule* matches.
* It is generally used to handle unknown URLs (similar to "404" behavior, but on the client side).
*
* - If `handler` a string, it is treated as a url redirect
*
* #### Example:
* When no other url rule matches, redirect to `/index`
* ```js
* .otherwise('/index');
* ```
*
* - If `handler` is an object with a `state` property, the state is activated.
*
* #### Example:
* When no other url rule matches, redirect to `home` and provide a `dashboard` parameter value.
* ```js
* .otherwise({ state: 'home', params: { dashboard: 'default' } });
* ```
*
* - If `handler` is a function, the function receives the current url ([[UrlParts]]) and the [[UIRouter]] object.
* The function can perform actions, and/or return a value.
*
* #### Example:
* When no other url rule matches, manually trigger a transition to the `home` state
* ```js
* .otherwise((urlParts, router) => {
* router.stateService.go('home');
* });
* ```
*
* #### Example:
* When no other url rule matches, go to `home` state
* ```js
* .otherwise((urlParts, router) => {
* return { state: 'home' };
* });
* ```
*
* @param handler The url path to redirect to, or a function which returns the url path (or performs custom logic).
*/
otherwise(handler: string | UrlRuleHandlerFn | TargetState | TargetStateDef): void;
/**
* Defines the initial state, path, or behavior to use when the app starts.
*
* This rule defines the initial/starting state for the application.
*
* This rule is triggered the first time the URL is checked (when the app initially loads).
* The rule is triggered only when the url matches either `""` or `"/"`.
*
* Note: The rule is intended to be used when the root of the application is directly linked to.
* When the URL is *not* `""` or `"/"` and doesn't match other rules, the [[otherwise]] rule is triggered.
* This allows 404-like behavior when an unknown URL is deep-linked.
*
* #### Example:
* Start app at `home` state.
* ```js
* .initial({ state: 'home' });
* ```
*
* #### Example:
* Start app at `/home` (by url)
* ```js
* .initial('/home');
* ```
*
* #### Example:
* When no other url rule matches, go to `home` state
* ```js
* .initial((url, router) => {
* console.log('initial state');
* return { state: 'home' };
* })
* ```
*
* @param handler The initial state or url path, or a function which returns the state or url path (or performs custom logic).
*/
initial(handler: string | UrlRuleHandlerFn | TargetState | TargetStateDef, options?: {
priority: number;
}): void;
/**
* Gets all registered rules
*
* @returns an array of all the registered rules
*/
rules(): UrlRule[];
/**
* Manually adds a URL Rule.
*
* Usually, a url rule is added using [[StateDeclaration.url]] or [[when]].
* This api can be used directly for more control (to register [[BaseUrlRule]], for example).
* Rules can be created using [[UrlRouter.urlRuleFactory]], or create manually as simple objects.
*
* @return a function that deregisters the rule
*/
rule(rule: UrlRule): Function;
/**
* Remove a rule previously registered
*
* @param rule the matcher rule that was previously registered using [[rule]]
*/
removeRule(rule: UrlRule): void;
}
/**
* An object containing the three parts of a URL
*/
export interface UrlParts {
path: string;
search?: {
[key: string]: any;
};
hash?: string;
}
/**
* A UrlRule match result
*
* The result of UrlRouter.match()
*/
export interface MatchResult {
/** The matched value from a [[UrlRule]] */
match: any;
/** The rule that matched */
rule: UrlRule;
/** The match result weight */
weight: number;
}
/**
* A function that matches the URL for a [[UrlRule]]
*
* Implementations should match against the provided [[UrlParts]] and return the matched value (truthy) if the rule matches.
* If this rule is selected, the matched value is passed to the [[UrlRuleHandlerFn]].
*
* @return the matched value, either truthy or falsey
*/
export interface UrlRuleMatchFn {
(url?: UrlParts, router?: UIRouter): any;
}
/**
* Handler invoked when a rule is matched
*
* The matched value from the rule's [[UrlRuleMatchFn]] is passed as the first argument
* The handler should return a string (to redirect), a [[TargetState]]/[[TargetStateDef]], or void
*
* If the handler returns a string, the url is replaced with the string.
* If the handler returns a [[TargetState]], the target state is activated.
*/
export interface UrlRuleHandlerFn {
(matchValue?: any, url?: UrlParts, router?: UIRouter): (string | TargetState | TargetStateDef | void);
}
/** @internalapi */
export declare type UrlRuleType = "STATE" | "URLMATCHER" | "REGEXP" | "RAW" | "OTHER";
/**
* The interface for a URL Rule
*
* If you are creating a rule for use with [[UrlRulesApi.rule]], it should implement this interface.
*/
export interface UrlRule {
/**
* The rule's ID.
*
* IDs are auto-assigned when the rule is registered, in increasing order.
*/
$id: number;
/**
* The rule's priority (defaults to 0).
*
* This can be used to explicitly modify the rule's priority.
* Higher numbers are higher priority.
*/
priority: number;
/**
* The priority of a given match.
*
* Sometimes more than one UrlRule might have matched.
* This method is used to choose the best match.
*
* If multiple rules matched, each rule's `matchPriority` is called with the value from [[match]].
* The rule with the highest `matchPriority` has its [[handler]] called.
*/
matchPriority(match: any): number;
/** The type of the rule */
type: UrlRuleType;
/**
* This function should match the url and return the match details
*
* See [[UrlRuleMatchFn]] for details
*/
match: UrlRuleMatchFn;
/**
* This function is called if the rule matched, and was selected as the "best match".
* This function handles the rule match event.
*
* See [[UrlRuleHandlerFn]] for details
*/
handler: UrlRuleHandlerFn;
}
/** @internalapi */
export interface MatcherUrlRule extends UrlRule {
type: "URLMATCHER" | "STATE";
urlMatcher: UrlMatcher;
}
/** @internalapi */
export interface StateRule extends MatcherUrlRule {
type: "STATE";
state: StateObject;
}
/** @internalapi */
export interface RegExpRule extends UrlRule {
type: "REGEXP";
regexp: RegExp;
}