Ng1.ng1statedeclaration

The StateDeclaration object is used to define a state or nested state. It should be registered with the StateRegistry.

example


// StateDeclaration object
var foldersState = {
  name: 'folders',
  url: '/folders',
  resolve: {
    allfolders: function(FolderService) {
      return FolderService.list();
    }
  },
  template: "<ul><li ng-repeat='folder in allfolders'></li></ul>",
  controller: function(allfolders, $scope) {
    $scope.allfolders = allfolders;
  }
}

Since this interface extends Ng1ViewDeclaration, any view declaration properties can be set directly on the state declaration and they will be applied to the view with the name $default. For example:

var state = {
  name: 'foo',
  url: '/foo',
  template: '<h1>foo</h1>',
  controller: 'FooController'
}

is simply syntactic sugar for:

var state = {
  name: 'foo',
  url: '/foo',
  views: {
    $default: {
      template: '<h1>foo</h1>',
      controller: 'FooController
    }
  }
}

If a state definition contains a views: object, any view properties set directly on the state are ignored. Thus, this is an invalid state defintion:

var state = {
  name: 'foo',
  url: '/foo',
  controller: 'FooController, // invalid because views: exists
  views: {
    header: {
      template: '<h1>header</h1>'
    }
  }
}

Hierarchy

StateDeclaration
Ng1ViewDeclaration
- Ng1StateDeclaration

Index

Properties

abstract: boolean

abstract state indicator

An abstract state can never be directly activated. Use an abstract state to provide inherited properties (url, resolve, data, etc) to children states.

bindings: object

An object which maps resolves to component bindings.

A property of Ng1StateDeclaration or Ng1ViewDeclaration:

When using a component declaration (component: 'myComponent'), each input binding for the component is supplied data from a resolve of the same name, by default. You may supply data from a different resolve name by mapping it here.

Each key in this object is the name of one of the component's input bindings. Each value is the name of the resolve that should be provided to that binding.

Any component bindings that are omitted from this map get the default behavior of mapping to a resolve of the same name.

example


$stateProvider.state('foo', {
  resolve: {
    foo: function(FooService) { return FooService.get(); },
    bar: function(BarService) { return BarService.get(); }
  },
  component: 'Baz',
  // The component's `baz` binding gets data from the `bar` resolve
  // The component's `foo` binding gets data from the `foo` resolve (default behavior)
  bindings: {
    baz: 'bar'
  }
});

app.component('Baz', {
  templateUrl: 'baz.html',
  controller: 'BazController',
  bindings: {
    foo: '<', // foo binding
    baz: '<'  // baz binding
  }
});

Type declaration

[key: string]: string

component: string

The name of the component to use for this view.

A property of Ng1StateDeclaration or Ng1ViewDeclaration:

The name of an angular 1.5+ .component() (or directive with bindToController and/or scope declaration) which will be used for this view.

Resolve data can be provided to the component via the component's bindings object (for 1.3+ directives, the bindToController is used; for other directives, the scope declaration is used). For each binding declared on the component, any resolve with the same name is set on the component's controller instance. The binding is provided to the component as a one-time-binding. In general, components should likewise declare their input bindings as one-way ("<").

Note: inside a "views:" block, a bare string "foo" is shorthand for { component: "foo" }

Note: Mapping from resolve names to component inputs may be specified using bindings.

example


.state('profile', {
  // Use the <my-profile></my-profile> component for the Unnamed view
  component: 'MyProfile',
}

.state('messages', {
  // use the <nav-bar></nav-bar> component for the view named 'header'
  // use the <message-list></message-list> component for the view named 'content'
  views: {
    header: { component: 'NavBar' },
    content: { component: 'MessageList' }
  }
}

.state('contacts', {
  // Inside a "views:" block, a bare string "NavBar" is shorthand for { component: "NavBar" }
  // use the <nav-bar></nav-bar> component for the view named 'header'
  // use the <contact-list></contact-list> component for the view named 'content'
  views: {
    header: 'NavBar',
    content: 'ContactList'
  }
}

Note: When using component to define a view, you may not use any of: template, templateUrl, templateProvider, controller, controllerProvider, controllerAs.

See also: Todd Motto's angular 1.3 and 1.4 backport of .component()

controller: Function | string

The view's controller function or name

A property of Ng1StateDeclaration or Ng1ViewDeclaration:

The controller function, or the name of a registered controller. The controller function will be used to control the contents of the ui-view directive.

If specified as a string, controllerAs can be declared here, i.e., "FooController as foo" instead of in a separate controllerAs property.

See: Ng1Controller for information about component-level router hooks.

controllerAs: string

A controller alias name.

A property of Ng1StateDeclaration or Ng1ViewDeclaration:

If present, the controller will be published to scope under the controllerAs name. See: https://docs.angularjs.org/api/ng/directive/ngController

controllerProvider: Function

Dynamic controller provider function.

A property of Ng1StateDeclaration or Ng1ViewDeclaration:

This is an injectable provider function which returns the actual controller function, or the name of a registered controller. The provider will invoked during a Transition in which the view's state is entered. The provider is called after the resolve data is fetched.

example


controllerProvider: function(MyResolveData, $transition$) {
  if (MyResolveData.foo) {
    return "FooCtrl"
  } else if ($transition$.to().name === 'bar') {
    return "BarCtrl";
  } else {
    return function($scope) {
      $scope.baz = "Qux";
    }
  }
}

data: any

An inherited property to store state data

This is a spot for you to store inherited state metadata. Child states' data object will prototypically inherit from the parent state .

This is a good spot to put metadata such as requiresAuth.

name: string

The state name

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

Note: States require unique names. If you omit this property, you must provide the state name when you register it with the [[$stateProvider]].

onEnter: Function

A Transition Hook called with the state is being entered. See: IHookRegistry.onEnter

onExit: Function

A Transition Hook called with the state is being exited. See: IHookRegistry.onExit

onRetain: Function

A Transition Hook called with the state is being retained. See: IHookRegistry.onRetain

params: object

Params configuration

An object which optionally configures parameters declared in the url, or defines additional non-url parameters. For each parameter being configured, add a ParamDeclaration keyed to the name of the parameter.

example


params: {
  param1: {
   type: "int",
   array: true,
   value: []
  },
  param2: {
    value: "index"
  }
}

Type declaration

[key: string]: any

parent: string | StateDeclaration

The parent state

Normally, a state's parent is implied from the state's name, e.g., "parentstate.childstate".

Alternatively, you can explicitly set the parent state using this property. This allows shorter state names, e.g., <a ui-sref="childstate">Child</a> instead of `Child

When using this property, the state's name should not have any dots in it.

example


var parentstate = {
  name: 'parentstate'
}
var childstate = {
  name: 'childstate',
  parent: 'parentstate'
  // or use a JS var which is the parent StateDeclaration, i.e.:
  // parent: parentstate
}

reloadOnSearch: boolean

Makes all search/query parameters dynamic

deprecated: use ParamDeclaration.dynamic

resolve: object

Resolve - a mechanism to fetch data, which participates in the transition lifecycle

An object which defines dynamic dependencies/data that can then be injected into this state (or its children) during a Transition.

Define a new dependency by adding a key/value to the resolve property of the StateDeclaration.

The key (string) is the name of the dependency.
The value (function) is an injectable function which returns the dependency, or a promise for the dependency.

example


resolve: {
  // If you inject `myStateDependency` into a controller, you'll get "abc"
  myStateDependency: function() {
    return "abc";
  },
  myAsyncData: function($http) {
    // Return a promise (async) for the data
    return $http.get("/api/v1/data");
  }
}

Lifecycle

Since a resolve function can return a promise, the router will delay entering the state until the promises are ready. If any of the promises are rejected, the Transition is aborted with an Error.

By default, resolves for a state are fetched just before that state is entered. Note that only states which are being entered have their resolves fetched. States that are "retained" do not have their resolves re-fetched. If you are currently in a parent state A and are transitioning to a child state A.B, the previously resolved data for state A can be injected into A.B without delay.

Any resolved data for A.B is retained until A.B is exited, e.g., by transitioning back to the parent state A.

Because of this, resolves are a great place to fetch your application's primary data.

Injecting resolves into other things

During a transition, Resolve data can be injected into:

Transition Hooks, e.g., $transitions.onStart/onEnter
ui-view Controllers
TemplateProviders and ControllerProviders
Other resolves

Injecting other things into resolves

Since resolve functions are injected, a common pattern is to inject a custom service such as UserService and delegate to a custom service method, such as UserService.list();

A resolve function can inject some special values:

$transition$ : The current Transition object; information and API about the current transition, such as "to" and "from" State Parameters and transition options.
Other resolves: This resolve can depend on another resolve, either from the same state, or from any parent state.
$stateParams: (deprecated) The parameters for the current state (Note: these parameter values are

example


resolve: {
  // Define a resolve 'allusers' which delegates to the UserService
  allusers: function(UserService) {
    return UserService.list(); // list() returns a promise (async) for all the users
  },
  // Define a resolve 'user' which depends on the allusers resolve.
  // This resolve function is not called until 'allusers' is ready.
  user: function(allusers, $transition$) {
    return _.find(allusers, $transition$.params().userId);
  }
}

Type declaration

[key: string]: Function

resolveAs: string

The scope variable name to use for resolve data.

A property of Ng1StateDeclaration or Ng1ViewDeclaration:

When a view is activated, the resolved data for the state which the view belongs to is put on the scope. This property sets the name of the scope variable to use for the resolved data.

Defaults to $resolve.

resolvePolicy: string | Object

Sets the resolve policy for the state

This can be either "EAGER" or "LAZY". When "EAGER", the state's resolves are fetched before any states are entered. When "LAZY", the resolves are fetched when the state is being entered.

The default is "LAZY".

template: Function | string

The HTML template for the view.

A property of Ng1StateDeclaration or Ng1ViewDeclaration:

HTML template as a string, or a function which returns an html template as a string. This template will be used to render the corresponding ui-view directive.

This property takes precedence over templateUrl.

If template is a function, it will be called with the Transition parameters as the first argument.

example


template: "<h1>inline template definition</h1><div ui-view></div>"

example


template: function(params) {
  return "<h1>generated template</h1>";
}

templateProvider: IInjectable

Injected function which returns the HTML template.

A property of Ng1StateDeclaration or Ng1ViewDeclaration:

Injected function which returns the HTML template. The template will be used to render the corresponding ui-view directive.

example


templateProvider: function(MyTemplateService, $transition$) {
  return MyTemplateService.getTemplate($transition$.params().pageId);
}

templateUrl: string | Function

The URL for the HTML template for the view.

A property of Ng1StateDeclaration or Ng1ViewDeclaration:

A path or a function that returns a path to an html template. The template will be fetched and used to render the corresponding ui-view directive.

If templateUrl is a function, it will be called with the Transition parameters as the first argument.

example


templateUrl: "/templates/home.html"

example


templateUrl: function(params) {
  return myTemplates[params.pageId];
}

url: string

The url fragment for the state

A URL fragment (with optional parameters) which is used to match the browser location with this state.

This fragment will be appended to the parent state's URL in order to build up the overall URL for this state. See UrlMatcher for details on acceptable patterns.

examples


url: "/home"
// Define a parameter named 'userid'
url: "/users/:userid"
// param 'bookid' has a custom regexp
url: "/books/{bookid:[a-zA-Z_-]}"
// param 'categoryid' is of type 'int'
url: "/books/{categoryid:int}"
// two parameters for this state
url: "/books/{publishername:string}/{categoryid:int}"
// Query parameters
url: "/messages?before&after"
// Query parameters of type 'date'
url: "/messages?{before:date}&{after:date}"
// Path and query parameters
url: "/messages/:mailboxid?{before:date}&{after:date}"

views: object

An optional object which defines multiple named views.

Each key is the name of a view, and each value is a Ng1ViewDeclaration. Unnamed views are internally renamed to $default.

A view's name is used to match an active <ui-view> directive in the DOM. When the state is entered, the state's views are activated and matched with active <ui-view> directives:

The view's name is processed into a ui-view target:
- ui-view address: an address to a ui-view
- state anchor: the state to anchor the address to
Examples:

Targets three named ui-views in the parent state's template

example


views: {
  header: {
    controller: "headerCtrl",
    templateUrl: "header.html"
  },
  body: {
    controller: "bodyCtrl",
    templateUrl: "body.html"
  },
  footer: "footerComponent"
}

example


// Targets named ui-view="header" in the template of the ancestor state 'top'
// and the named `ui-view="body" from the parent state's template.
views: {
  'header@top': {
    controller: "msgHeaderCtrl",
    templateUrl: "msgHeader.html"
  },
  'body': {
    controller: "messagesCtrl",
    templateUrl: "messages.html"
  }
}

View targeting details

There are a few styles of view addressing/targeting. The most common is a simple ui-view name

Simple ui-view name

Addresses without an @ are anchored to the parent state.

example


// target the `<div ui-view='foo'></div>` created in the parent state's view
views: { foo: {...} }

View name anchored to a state

You can anchor the ui-view name to a specific state by including an @

example


// target the `<div ui-view='foo'></div>` which was created in a
// view owned by the state `bar.baz`
views: { 'foo@bar.baz': {...} }

Absolute addressing

You can address a ui-view absolutely, using dotted notation, by prefixing the address with a !. Dotted addresses map to the hierarchy of ui-views active in the DOM:

example


// absolutely target the `<div ui-view='nested'></div>`... which was created
// in the unnamed/$default root `<ui-view></ui-view>`
views: { '!$default.nested': {...} }

Relative addressing

Absolute addressing is actually relative addressing, only anchored to the unnamed root state. You can also use relative addressing anchored to any state, in order to target a target deeply nested ui-views:

example



// target the `<div ui-view='bar'></div>`... which was created inside the
// `<div ui-view='bar'></div>`... which was created inside the parent state's template.
views: { 'foo.bar': {...} }

example

```js

// target the <div ui-view='bar'></div>... which was created in // <div ui-view='foo'></div>... which was created in a template crom the state baz.qux views: { 'foo.bar@baz.qux': {...} }

State template+controller and `views:` incompatiblity

If a state has a views object, any state-level view properties (Ng1ViewDeclaration) are ignored. Therefore, if any view for a state is declared in the views object, then all of the state's views must be defined in the views object. The state declaration must not have any of the following fields:

component
bindings
resolveAs
template
templateUrl
templateProvider
controller
controllerAs
controllerProvider

Type declaration

[key: string]: Ng1ViewDeclaration

Hierarchy

Index

Properties

Properties

Type declaration

[key: string]: string

Type declaration

[key: string]: any

Lifecycle

Injecting resolves into other things

Injecting other things into resolves

Type declaration

[key: string]: Function

View targeting details

Simple ui-view name

View name anchored to a state

Absolute addressing

Relative addressing

State template+controller and views: incompatiblity

Type declaration

[key: string]: Ng1ViewDeclaration

State template+controller and `views:` incompatiblity