$stateProvider (service in module ui.router.state )

Methods

• decorator(name, func)

  Allows you to extend (carefully) or override (at your own peril) the stateBuilder object used internally by $stateProvider. This can be used to add custom functionality to ui-router, for example inferring templateUrl based on the state name.

  When passing only a name, it returns the current (original or decorated) builder function that matches name.

  The builder functions that can be decorated are listed below. Though not all necessarily have a good use case for decoration, that is up to you to decide.

  In addition, users can attach custom decorators, which will generate new properties within the state's internal definition. There is currently no clear use-case for this beyond accessing internal states (i.e. $state.$current), however, expect this to become increasingly relevant as we introduce additional meta-programming features.

  Warning: Decorators should not be interdependent because the order of execution of the builder functions in nondeterministic. Builder functions should only be dependent on the state definition object and super function.

  Existing builder functions and current return values:

  • parent - {object} - returns the parent state object.
  • data - {object} - returns state data, including any inherited data that is not overridden by own values (if any).
  • url - {object} - returns a UrlMatcher or null.
  • navigable - returns closest ancestor state that has a URL (aka is navigable).
  • params - {object} - returns an array of state params that are ensured to be a super-set of parent's params.
  • views - {object} - returns a views object where each key is an absolute view name (i.e. "viewName@stateName") and each value is the config object (template, controller) for the view. Even when you don't use the views object explicitly on a state config, one is still created for you internally. So by decorating this builder function you have access to decorating template and controller properties.
  • ownParams - {object} - returns an array of params that belong to the state, not including any params defined by ancestor states.
  • path - {string} - returns the full path from the root down to this state. Needed for state activation.
  • includes - {object} - returns an object that includes every state that would pass a '$state.includes()' test.

  Parameters

  • name – {string} –

    The name of the builder function to decorate.

  • func – {object} –

    A function that is responsible for decorating the original builder function. The function receives two parameters:

    • {object} - state - The state config object.
    • {object} - super - The original builder function.

  Returns

  {object} –

  $stateProvider - $stateProvider instance

  Example

  // Override the internal 'views' builder with a function that takes the state
  // definition, and a reference to the internal function being overridden:
  $stateProvider.decorator('views', function ($state, parent) {
    var result = {},
        views = parent(state);
  
    angular.forEach(view, function (config, name) {
      var autoName = (state.name + '.' + name).replace('.', '/');
      config.templateUrl = config.templateUrl || '/partials/' + autoName + '.html';
      result[name] = config;
    });
    return result;
  });
  
  $stateProvider.state('home', {
    views: {
      'contact.list': { controller: 'ListController' },
      'contact.item': { controller: 'ItemController' }
    }
  });
  
  // ...
  
  $state.go('home');
  // Auto-populates list and item views with /partials/home/contact/list.html,
  // and /partials/home/contact/item.html, respectively.
  

• state(name, definition)

  Registers a state configuration under a given state name. The stateConfig object has the following acceptable properties.

  • [template, templateUrl, templateProvider] - There are three ways to setup your templates.

    • {string|object} - template - String HTML content, or function that returns an HTML string.
    • {string} - templateUrl - String URL path to template file OR function, that returns URL path string.
    • {object} - templateProvider - Provider function that returns HTML content string.

  • [controller, controllerProvider] - A controller paired to the state. You can either use a controller, or a controller provider.

    • {string|object} - controller - Controller function or controller name.
    • {object} - controllerProvider - Injectable provider function that returns the actual controller or string.

  • {object} - resolve - A map of dependencies which should be injected into the controller.

  • {string} - url - A url with optional parameters. When a state is navigated or transitioned to, the $stateParams service will be populated with any parameters that were passed.

  • {object} - params - An array of parameter names or regular expressions. Only use this within a state if you are not using url. Otherwise you can specify your parameters within the url. When a state is navigated or transitioned to, the $stateParams service will be populated with any parameters that were passed.

  • {object} - views - Use the views property to set up multiple views. If you don't need multiple views within a single state this property is not needed. Tip: remember that often nested views are more useful and powerful than multiple sibling views.

  • {boolean} - abstract - An abstract state will never be directly activated, but can provide inherited properties to its common children states.

  • {object} - onEnter - Callback function for when a state is entered. Good way to trigger an action or dispatch an event, such as opening a dialog.

  • {object} - onExit - Callback function for when a state is exited. Good way to trigger an action or dispatch an event, such as opening a dialog.

  • {object} - data - Arbitrary data object, useful for custom configuration.

  Parameters

  • name – {string} –

    A unique state name, e.g. "home", "about", "contacts". To create a parent/child state use a dot, e.g. "about.sales", "home.newest".

  • definition – {object} –

    State configuratino object.

  Example

  // The state() method takes a unique stateName (String) and a stateConfig (Object)
  $stateProvider.state(stateName, stateConfig);
  
  // stateName can be a single top-level name (must be unique).
  $stateProvider.state("home", {});
  
  // Or it can be a nested state name. This state is a child of the above "home" state.
  $stateProvider.state("home.newest", {});
  
  // Nest states as deeply as needed.
  $stateProvider.state("home.newest.abc.xyz.inception", {});
  
  // state() returns $stateProvider, so you can chain state declarations.
  $stateProvider
    .state("home", {})
    .state("about", {})
    .state("contacts", {});