Class UrlRules

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.

.initial({ state: 'home' });

Example:

Start app at /home (by url)

.initial('/home');

Example:

When no other url rule matches, go to home state

.initial((matchValue, url, router) => {
  console.log('initial state');
  return { state: 'home' };
})

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

.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.

.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

.otherwise((matchValue, urlParts, router) => {
  router.stateService.go('home');
});

Example:

When no other url rule matches, go to home state

.otherwise((matchValue, urlParts, router) => {
  return { state: 'home' };
});

Usually, a url rule is added using StateDeclaration.url or when. This api can be used directly for more control (to register a BaseUrlRule, for example). Rules can be created using urlRuleFactory, or created manually as simple objects.

A rule should have a match function which returns truthy if the rule matched. It should also have a handler function which is invoked if the rule is the best match.

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.

function compareFn(a, b) {
  return a.$id - b.$id;
}

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.

.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.

.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 UrlMatchers, 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.

.when(new RegExp("^/foo/(.*)$"), match => "/bar/" + match[1]);

Note: the handler may also invoke arbitrary code, such as $state.go()