UrlRulesApi | angular-ui-router
Options
Menu

Interface UrlRulesApi

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.

Hierarchy

  • UrlRulesApi

Implemented by

Index

Methods

  • Defines the path or behavior to use when no url can be matched.

    • If a string, it is treated as a url redirect

    Example:

    When no other url rule matches, redirect to /index

    .otherwise('/index');
    
    • If a function, the function receives the current url (UrlParts) and the UIRouter object. If the function returns a string, the url is redirected to the return value.

    Example:

    When no other url rule matches, redirect to /index

    .otherwise(() => '/index');
    

    Example:

    When no other url rule matches, go to home state

    .otherwise((url, router) => {
      router.stateService.go('home');
      return;
    }
    

    Parameters

    Returns void


  • removeRule(rule: UrlRule): void
  • Remove a rule previously registered

  • rule(rule: UrlRule): Function
  • Manually adds a URL Rule.

  • rules(): UrlRule[]
  • Gets all registered rules

  • sort(compareFn?: function): any
  • Defines URL Rule priorities

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

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

    Parameters

    • compareFn: Optional  function
      :

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

    Returns any


  • when(matcher: string | RegExp | UrlMatcher, handler: string | UrlRuleHandlerFn, options?: object): UrlRule
  • Registers a matcher and handler for custom URLs handling.

  • Registers a matcher and handler for custom URLs handling.

    The matcher can be:

    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]);
    

    Parameters

    • matcher string | RegExp | UrlMatcher
      :

      A pattern string to match, compiled as a UrlMatcher, or a RegExp.

    • handler string | UrlRuleHandlerFn
      :

      The path to redirect to, or a function that returns the path.

    • options: Optional  object
      :

      { priority: number }

      • priority: number

    Returns UrlRule

    :

    the registered UrlRule

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


Generated using TypeDoc