@types/ember__routing
Version:
TypeScript definitions for @ember/routing
532 lines (501 loc) • 20.3 kB
TypeScript
import EmberObject from "@ember/object";
import ActionHandler from "@ember/object/-private/action-handler";
// eslint-disable-next-line @definitelytyped/no-self-import
import Evented from "@ember/object/evented";
// eslint-disable-next-line @definitelytyped/no-self-import
import Transition from "@ember/routing/transition";
// eslint-disable-next-line @definitelytyped/no-self-import
import Controller from "@ember/controller";
// eslint-disable-next-line @definitelytyped/no-self-import
import { RouteQueryParam } from "@ember/routing/types";
// eslint-disable-next-line @definitelytyped/strict-export-declare-modifiers
type RouteModel = object | string | number;
/**
* The `Ember.Route` class is used to define individual routes. Refer to
* the [routing guide](http://emberjs.com/guides/routing/) for documentation.
*/
export default class Route<Model = unknown, Params extends object = object> extends EmberObject {
// methods
/**
* This hook is called after this route's model has resolved. It follows
* identical async/promise semantics to `beforeModel` but is provided the
* route's resolved model in addition to the `transition`, and is therefore
* suited to performing logic that can only take place after the model has
* already resolved.
*
* @returns if the value returned from this hook is a promise, the
* transition will pause until the transition resolves. Otherwise,
* non-promise return values are not utilized in any way.
*/
afterModel(resolvedModel: Model, transition: Transition): Promise<unknown> | void;
/**
* This hook is the first of the route entry validation hooks called when an
* attempt is made to transition into a route or one of its children. It is
* called before `model` and `afterModel`, and is appropriate for cases
* when:
*
* 1. A decision can be made to redirect elsewhere without needing to
* resolve the model first.
* 2. Any async operations need to occur first before the model is attempted
* to be resolved.
*
* This hook is provided the current `transition` attempt as a parameter,
* which can be used to `.abort()` the transition, save it for a later
* `.retry()`, or retrieve values set on it from a previous hook. You can
* also just call `this.transitionTo` to another route to implicitly abort
* the `transition`. You can return a promise from this hook to pause the
* transition until the promise resolves (or rejects). This could be useful,
* for instance, for retrieving async code from the server that is required
* to enter a route.
*
* @returns if the value returned from this hook is a promise, the
* transition will pause until the transition resolves. Otherwise,
* non-promise return values are not utilized in any way.
*/
beforeModel(transition: Transition): Promise<unknown> | void;
/**
* Returns the controller of the current route, or a parent (or any
* ancestor) route in a route hierarchy.
*
* The controller instance must already have been created, either through
* entering the associated route or using `generateController`.
*
* @param name the name of the route or controller
*/
controllerFor(name: string): Controller;
/**
* A hook you can implement to convert the URL into the model for
* this route.
*/
model(params: Params, transition: Transition): Model | PromiseLike<Model>;
/**
* Returns the model of a parent (or any ancestor) route
* in a route hierarchy. During a transition, all routes
* must resolve a model object, and if a route
* needs access to a parent route's model in order to
* resolve a model (or just reuse the model from a parent),
* it can call `this.modelFor(theNameOfParentRoute)` to
* retrieve it.
*/
modelFor(name: string): unknown;
/**
* Retrieves parameters, for current route using the state.params
* variable and getQueryParamsFor, using the supplied routeName.
*/
paramsFor(name: string): object;
/**
* A hook you can implement to optionally redirect to another route.
*
* If you call `this.transitionTo` from inside of this hook, this route
* will not be entered in favor of the other hook.
*
* `redirect` and `afterModel` behave very similarly and are
* called almost at the same time, but they have an important
* distinction in the case that, from one of these hooks, a
* redirect into a child route of this route occurs: redirects
* from `afterModel` essentially invalidate the current attempt
* to enter this route, and will result in this route's `beforeModel`,
* `model`, and `afterModel` hooks being fired again within
* the new, redirecting transition. Redirects that occur within
* the `redirect` hook, on the other hand, will _not_ cause
* these hooks to be fired again the second time around; in
* other words, by the time the `redirect` hook has been called,
* both the resolved model and attempted entry into this route
* are considered to be fully validated.
*/
redirect(model: Model, transition: Transition): void;
/**
* Refresh the model on this route and any child routes, firing the
* `beforeModel`, `model`, and `afterModel` hooks in a similar fashion
* to how routes are entered when transitioning in from other route.
* The current route params (e.g. `article_id`) will be passed in
* to the respective model hooks, and if a different model is returned,
* `setupController` and associated route hooks will re-fire as well.
* An example usage of this method is re-querying the server for the
* latest information using the same parameters as when the route
* was first entered.
* Note that this will cause `model` hooks to fire even on routes
* that were provided a model object when the route was initially
* entered.
*/
refresh(): Transition;
/**
* Transition into another route while replacing the current URL, if possible.
* This will replace the current history entry instead of adding a new one.
* Beside that, it is identical to `transitionTo` in all other respects. See
* 'transitionTo' for additional information regarding multiple models.
*
* @param name the name of the route or a URL
* @param models the model(s) or identifier(s) to be used while
* transitioning to the route.
* @param options optional hash with a queryParams property
* containing a mapping of query parameters. May be supplied
* as the only parameter to trigger a query-parameter-only
* transition.
* @returns the Transition object associated with this attempted
* transition
* @deprecated until 5.0. Inject the router service and use its methods.
*/
replaceWith(name: string, ...args: unknown[]): Transition;
/**
* A hook you can use to reset controller values either when the model
* changes or the route is exiting.
*/
resetController(controller: Controller, isExiting: boolean, transition: Transition): void;
/**
* Sends an action to the router, which will delegate it to the currently active
* route hierarchy per the bubbling rules explained under actions.
*/
send(name: string, ...args: unknown[]): void;
/**
* A hook you can implement to convert the route's model into parameters
* for the URL.
*
* The default `serialize` method will insert the model's `id` into the
* route's dynamic segment (in this case, `:post_id`) if the segment contains '_id'.
* If the route has multiple dynamic segments or does not contain '_id', `serialize`
* will return `Ember.getProperties(model, params)`
* This method is called when `transitionTo` is called with a context
* in order to populate the URL.
*/
serialize(model: Model, params: string[]): string | object;
/**
* A hook you can use to setup the controller for the current route.
* This method is called with the controller for the current route and the
* model supplied by the `model` hook.
* By default, the `setupController` hook sets the `model` property of
* the controller to the `model`.
* If you implement the `setupController` hook in your Route, it will
* prevent this default behavior. If you want to preserve that behavior
* when implementing your `setupController` function, make sure to call
* `_super`
*/
setupController(controller: Controller, model: Model, transition: Transition): void;
/**
* Transition the application into another route. The route may
* be either a single route or route path:
*
* ```javascript
* this.transitionTo('blogPosts');
* this.transitionTo('blogPosts.recentEntries');
* ```
*
* Optionally supply a model for the route in question. The model
* will be serialized into the URL using the `serialize` hook of
* the route:
*
* ```javascript
* this.transitionTo('blogPost', aPost);
* ```
*
* If a literal is passed (such as a number or a string), it will
* be treated as an identifier instead. In this case, the `model`
* hook of the route will be triggered:
*
* ```javascript
* this.transitionTo('blogPost', 1);
* ```
*
* Multiple models will be applied last to first recursively up the
* route tree.
*
* ```app/routes.js
* // ...
*
* Router.map(function() {
* this.route('blogPost', { path:':blogPostId' }, function() {
* this.route('blogComment', { path: ':blogCommentId' });
* });
* });
*
* export default Router;
* ```
*
* ```javascript
* this.transitionTo('blogComment', aPost, aComment);
* this.transitionTo('blogComment', 1, 13);
* ```
*
* It is also possible to pass a URL (a string that starts with a
* `/`).
*
* ```javascript
* this.transitionTo('/');
* this.transitionTo('/blog/post/1/comment/13');
* this.transitionTo('/blog/posts?sort=title');
* ```
*
* An options hash with a `queryParams` property may be provided as
* the final argument to add query parameters to the destination URL.
*
* ```javascript
* this.transitionTo('blogPost', 1, {
* queryParams: { showComments: 'true' }
* });
*
* // if you just want to transition the query parameters without changing the route
* this.transitionTo({ queryParams: { sort: 'date' } });
* ```
*
* See also [replaceWith](#method_replaceWith).
*
* Simple Transition Example
*
* ```app/routes.js
* // ...
*
* Router.map(function() {
* this.route('index');
* this.route('secret');
* this.route('fourOhFour', { path: '*:' });
* });
*
* export default Router;
* ```
*
* ```app/routes/index.js
* import Route from '@ember/routing/route';
* import { action } from '@ember/object';
*
* export default class IndexRoute extends Route {
* @action
* moveToSecret(context) {
* if (authorized()) {
* this.transitionTo('secret', context);
* } else {
* this.transitionTo('fourOhFour');
* }
* }
* }
* ```
*
* Transition to a nested route
*
* ```app/router.js
* // ...
*
* Router.map(function() {
* this.route('articles', { path: '/articles' }, function() {
* this.route('new');
* });
* });
*
* export default Router;
* ```
*
* ```app/routes/index.js
* import Route from '@ember/routing/route';
* import { action } from '@ember/object';
*
* export default class IndexRoute extends Route {
* @action
* transitionToNewArticle() {
* this.transitionTo('articles.new');
* }
* }
* ```
*
* Multiple Models Example
*
* ```app/router.js
* // ...
*
* Router.map(function() {
* this.route('index');
*
* this.route('breakfast', { path: ':breakfastId' }, function() {
* this.route('cereal', { path: ':cerealId' });
* });
* });
*
* export default Router;
* ```
*
* ```app/routes/index.js
* import Route from '@ember/routing/route';
* import { action } from '@ember/object';
*
* export default class IndexRoute extends Route {
* @action
* moveToChocolateCereal() {
* let cereal = { cerealId: 'ChocolateYumminess' };
* let breakfast = { breakfastId: 'CerealAndMilk' };
*
* this.transitionTo('breakfast.cereal', breakfast, cereal);
* }
* }
* ```
*
* Nested Route with Query String Example
*
* ```app/routes.js
* // ...
*
* Router.map(function() {
* this.route('fruits', function() {
* this.route('apples');
* });
* });
*
* export default Router;
* ```
*
* ```app/routes/index.js
* import Route from '@ember/routing/route';
*
* export default class IndexRoute extends Route {
* @action
* transitionToApples() {
* this.transitionTo('fruits.apples', { queryParams: { color: 'red' } });
* }
* }
* ```
*
* @param name the name of the route or a URL.
* @param models the model(s) or identifier(s) to be used while
* transitioning to the route.
* @param options optional hash with a queryParams property
* containing a mapping of query parameters. May be supplied
* as the only parameter to trigger a query-parameter-only
* transition.
* @returns the Transition object associated with this attempted
* transition
* @deprecated until 5.0. Inject the router service and use its methods.
*/
transitionTo(name: string, options?: { queryParams: object }): Transition;
transitionTo(name: string, modelsA: RouteModel, options?: { queryParams: object }): Transition;
transitionTo(name: string, modelsA: RouteModel, modelsB: RouteModel, options?: { queryParams: object }): Transition;
transitionTo(
name: string,
modelsA: RouteModel,
modelsB: RouteModel,
modelsC: RouteModel,
options?: { queryParams: object },
): Transition;
transitionTo(
name: string,
modelsA: RouteModel,
modelsB: RouteModel,
modelsC: RouteModel,
modelsD: RouteModel,
options?: { queryParams: object },
): Transition;
transitionTo(options: { queryParams: object }): Transition;
// https://emberjs.com/api/ember/release/classes/Route/methods/intermediateTransitionTo?anchor=intermediateTransitionTo
/**
* Perform a synchronous transition into another route without attempting to resolve promises,
* update the URL, or abort any currently active asynchronous transitions
* (i.e. regular transitions caused by transitionTo or URL changes).
*
* @param name the name of the route or a URL
* @param models the model(s) or identifier(s) to be used while
* transitioning to the route.
* @returns the Transition object associated with this attempted transition
*/
intermediateTransitionTo(name: string, ...models: unknown[]): Transition;
// properties
/**
* The controller associated with this route.
*/
controller: Controller;
/**
* The name of the controller to associate with this route.
* By default, Ember will lookup a route's controller that matches the name
* of the route (i.e. `App.PostController` for `App.PostRoute`). However,
* if you would like to define a specific controller to use, you can do so
* using this property.
* This is useful in many ways, as the controller specified will be:
* * p assed to the `setupController` method.
* * used as the controller for the view being rendered by the route.
* * returned from a call to `controllerFor` for the route.
*/
controllerName: string;
/**
* The name of the route, dot-delimited, including the engine prefix if applicable.
*/
fullRouteName: string;
/**
* Configuration hash for this route's queryParams.
*/
queryParams: { [key: string]: RouteQueryParam };
/**
* The name of the route, dot-delimited
*/
routeName: string;
/**
* The name of the template to use by default when rendering this routes
* template.
* This is similar with `viewName`, but is useful when you just want a custom
* template without a view.
*/
templateName: string;
// events
/**
* This hook is executed when the router enters the route. It is not executed
* when the model for the route changes.
*/
activate(transition: Transition): void;
/**
* This hook is executed when the router completely exits this route. It is
* not executed when the model for the route changes.
*/
deactivate(transition: Transition): void;
/**
* The didTransition action is fired after a transition has successfully been
* completed. This occurs after the normal model hooks (beforeModel, model,
* afterModel, setupController) have resolved. The didTransition action has
* no arguments, however, it can be useful for tracking page views or resetting
* state on the controller.
*/
didTransition(): void;
/**
* When attempting to transition into a route, any of the hooks may return a promise
* that rejects, at which point an error action will be fired on the partially-entered
* routes, allowing for per-route error handling logic, or shared error handling logic
* defined on a parent route.
*/
error(error: unknown, transition: Transition): void;
/**
* The loading action is fired on the route when a route's model hook returns a
* promise that is not already resolved. The current Transition object is the first
* parameter and the route that triggered the loading event is the second parameter.
*/
loading(transition: Transition, route: Route): void;
/**
* The willTransition action is fired at the beginning of any attempted transition
* with a Transition object as the sole argument. This action can be used for aborting,
* redirecting, or decorating the transition from the currently active routes.
*/
willTransition(transition: Transition): void;
/**
* Allows you to produce custom metadata for the route.
* The return value of this method will be attached to
* its corresponding RouteInfoWithAttributes object.
* Example
* ```app/routes/posts/index.js
* import Route from '@ember/routing/route';
* export default class PostsIndexRoute extends Route {
* buildRouteInfoMetadata() {
* return { title: 'Posts Page' }
* }
* }
* ```
* ```app/routes/application.js
* import Route from '@ember/routing/route';
* import { inject as service } from '@ember/service';
* export default class ApplicationRoute extends Route {
* @service router
* constructor() {
* super(...arguments);
* this.router.on('routeDidChange', transition => {
* document.title = transition.to.metadata.title;
* // would update document's title to "Posts Page"
* });
* }
* }
* ```
*/
buildRouteInfoMetadata(): unknown;
}
// eslint-disable-next-line @typescript-eslint/no-empty-interface -- used for declaration merge
export default interface Route<Model = unknown, Params extends object = object> extends ActionHandler, Evented {}