From 6603da54e7ebedd72dd894215c433edc78405dd9 Mon Sep 17 00:00:00 2001 From: EisenbergEffect Date: Tue, 22 Oct 2013 23:26:50 -0400 Subject: [PATCH] Updating the Durandal definition to 2.0.1. This is the official TypeScript definition file for Durandal 2.0.1. --- durandal/durandal.d.ts | 1229 +++++++++++++++++++--------------------- 1 file changed, 585 insertions(+), 644 deletions(-) diff --git a/durandal/durandal.d.ts b/durandal/durandal.d.ts index 89417e3e5..c2567f62c 100644 --- a/durandal/durandal.d.ts +++ b/durandal/durandal.d.ts @@ -1,5 +1,5 @@ /** - * Durandal 2.0.0 Copyright (c) 2012 Blue Spire Consulting, Inc. All Rights Reserved. + * Durandal 2.0.1 Copyright (c) 2012 Blue Spire Consulting, Inc. All Rights Reserved. * Available via the MIT license. * see: http://durandaljs.com or https://github.com/BlueSpire/Durandal for details. */ @@ -116,7 +116,7 @@ declare module 'durandal/system' { * @param {object} extension* Uses to extend the target object. */ export function extend(obj: any, ...extensions: any[]): any; - + /** * Uses a setTimeout to wait the specified milliseconds. * @param {number} milliseconds The number of milliseconds to wait. @@ -226,7 +226,7 @@ declare module 'durandal/viewEngine' { * @returns {boolean} True if the url is a view url, false otherwise. */ export function isViewUrl(url: string):boolean; - + /** * Converts a view url into a view id. * @param {string} url The url to convert. @@ -285,62 +285,8 @@ declare module 'durandal/viewEngine' { * @requires system */ declare module 'durandal/events' { - import ts = require('durandal/typescript'); - - /** - * Creates an object with eventing capabilities. - * @class Events - */ - class Events { - constructor(); - - /** - * Creates a subscription or registers a callback for the specified event. - * @param {string} events One or more events, separated by white space. - * @returns {Subscription} A subscription is returned. - */ - on(events: string): ts.EventSubscription; - - /** - * Creates a subscription or registers a callback for the specified event. - * @param {string} events One or more events, separated by white space. - * @param {function} [callback] The callback function to invoke when the event is triggered. - * @param {object} [context] An object to use as `this` when invoking the `callback`. - * @returns {Events} The events object is returned for chaining. - */ - on(events: string, callback: Function, context?: any): Events; - - /** - * Removes the callbacks for the specified events. - * @param {string} [events] One or more events, separated by white space to turn off. If no events are specified, then the callbacks will be removed. - * @param {function} [callback] The callback function to remove. If `callback` is not provided, all callbacks for the specified events will be removed. - * @param {object} [context] The object that was used as `this`. Callbacks with this context will be removed. - * @chainable - */ - off(events: string, callback: Function, context?: any): Events; - - /** - * Triggers the specified events. - * @param {string} [events] One or more events, separated by white space to trigger. - * @chainable - */ - trigger(events: string, ...eventArgs: any[]): Events; - - /** - * Creates a function that will trigger the specified events when called. Simplifies proxying jQuery (or other) events through to the events object. - * @param {string} events One or more events, separated by white space to trigger by invoking the returned function. - * @returns {function} Calling the function will invoke the previously specified events on the events object. - */ - proxy(events: string): Function; - - /** - * Adds eventing capabilities to the specified object. - * @param {object} targetObject The object to add eventing capabilities to. - */ - static includeIn(targetObject: any): void; - } - - export = Events; + var theModule: DurandalEventModule; + export = theModule; } /** @@ -389,7 +335,7 @@ declare module 'durandal/binder' { * @param {object} [obj] The data to bind to, causing the creation of a child binding context if present. */ export function bindContext(bindingContext: KnockoutBindingContext, view: HTMLElement, obj?: any): BindingInstruction; - + /** * Binds the view, preserving the existing binding context. Optionally, a new context can be created, parented to the previous context. * @param {object} obj The data to bind to. @@ -407,136 +353,12 @@ declare module 'durandal/binder' { * @requires knockout */ declare module 'durandal/activator' { - interface ActivatorSettings { - /** - * The default value passed to an object's deactivate function as its close parameter. - * @default true - */ - closeOnDeactivate: boolean; - - /** - * Lower-cased words which represent a truthy value. - * @default ['yes', 'ok', 'true'] - */ - affirmations: string[]; - - /** - * Interprets the response of a `canActivate` or `canDeactivate` call using the known affirmative values in the `affirmations` array. - * @param {object} value - * @returns {boolean} - */ - interpretResponse(value: any): boolean; - - /** - * Determines whether or not the current item and the new item are the same. - * @param {object} currentItem - * @param {object} newItem - * @param {object} currentActivationData - * @param {object} newActivationData - * @returns {boolean} - */ - areSameItem(currentItem: any, newItem: any, currentActivationData: any, newActivationData: any): boolean; - - /** - * Called immediately before the new item is activated. - * @param {object} newItem - */ - beforeActivate(newItem: any): any; - - /** - * Called immediately after the old item is deactivated. - * @param {object} oldItem The previous item. - * @param {boolean} close Whether or not the previous item was closed. - * @param {function} setter The activate item setter function. - */ - afterDeactivate(oldItem: any, close: boolean, setter: Function): void; - } - - interface Activator extends KnockoutComputed { - /** - * The settings for this activator. - */ - settings: ActivatorSettings; - - /** - * An observable which indicates whether or not the activator is currently in the process of activating an instance. - * @returns {boolean} - */ - isActivating: KnockoutObservable; - - /** - * Determines whether or not the specified item can be deactivated. - * @param {object} item The item to check. - * @param {boolean} close Whether or not to check if close is possible. - * @returns {promise} - */ - canDeactivateItem(item: T, close: boolean): JQueryPromise; - - /** - * Deactivates the specified item. - * @param {object} item The item to deactivate. - * @param {boolean} close Whether or not to close the item. - * @returns {promise} - */ - deactivateItem(item: T, close: boolean): JQueryPromise; - - /** - * Determines whether or not the specified item can be activated. - * @param {object} item The item to check. - * @param {object} activationData Data associated with the activation. - * @returns {promise} - */ - canActivateItem(newItem: T, activationData?: any): JQueryPromise; - - /** - * Activates the specified item. - * @param {object} newItem The item to activate. - * @param {object} newActivationData Data associated with the activation. - * @returns {promise} - */ - activateItem(newItem: T, activationData?: any): JQueryPromise; - - /** - * Determines whether or not the activator, in its current state, can be activated. - * @returns {promise} - */ - canActivate(): JQueryPromise; - - /** - * Activates the activator, in its current state. - * @returns {promise} - */ - activate(): JQueryPromise; - - /** - * Determines whether or not the activator, in its current state, can be deactivated. - * @returns {promise} - */ - canDeactivate(close: boolean): JQueryPromise; - - /** - * Deactivates the activator, in its current state. - * @returns {promise} - */ - deactivate(close: boolean): JQueryPromise; - - /** - * Adds canActivate, activate, canDeactivate and deactivate functions to the provided model which pass through to the corresponding functions on the activator. - */ - includeIn(includeIn: any): void; - - /** - * Sets up a collection representing a pool of objects which the activator will activate. See below for details. Activators without an item bool always close their values on deactivate. Activators with an items pool only deactivate, but do not close them. - */ - forItems(items): Activator; - } - /** * The default settings used by activators. * @property {ActivatorSettings} defaults */ - export var defaults: ActivatorSettings; - + export var defaults: DurandalActivatorSettings; + /** * Creates a new activator. * @method create @@ -544,7 +366,7 @@ declare module 'durandal/activator' { * @param {ActivatorSettings} [settings] Per activator overrides of the default activator settings. * @returns {Activator} The created activator. */ - export function create(initialActiveItem?: T, settings?: ActivatorSettings): Activator; + export function create(initialActiveItem?: T, settings?: DurandalActivatorSettings): DurandalActivator; /** * Determines whether or not the provided object is an activator or not. @@ -568,7 +390,7 @@ declare module 'durandal/viewLocator' { * @param {string} [areasPath] Partial views are mapped to the "views" folder if not specified. Use this parameter to change their location. */ export function useConvention(modulesPath?: string, viewsPath?: string, areasPath?: string): void; - + /** * Maps an object instance to a view instance. * @param {object} obj The object to locate the view for. @@ -577,7 +399,7 @@ declare module 'durandal/viewLocator' { * @returns {Promise} A promise of the view. */ export function locateViewForObject(obj: any, area:string, elementsToSearch?: HTMLElement[]): JQueryPromise; - + /** * Converts a module id into a view id. By default the ids are the same. * @param {string} moduleId The module id. @@ -599,7 +421,7 @@ declare module 'durandal/viewLocator' { * @returns {string} The translated view id. */ export function translateViewIdToArea(viewId: string, area: string): string; - + /** * Locates the specified view. * @param {string|DOMElement} view A view. It will be immediately returned. @@ -608,7 +430,7 @@ declare module 'durandal/viewLocator' { * @returns {Promise} A promise of the view. */ export function locateView(view: HTMLElement, area?: string, elementsToSearch?: HTMLElement[]): JQueryPromise; - + /** * Locates the specified view. * @param {string|DOMElement} viewUrlOrId A view url or view id to locate. @@ -725,100 +547,8 @@ declare module 'durandal/composition' { * @requires jquery */ declare module 'durandal/app' { - import Events = require('durandal/events'); - import ts = require('durandal/typescript'); - - /** - * The title of your application. - */ - export var title: string; - - /** - * Shows a dialog via the dialog plugin. - * @param {object|string} obj The object (or moduleId) to display as a dialog. - * @param {object} [activationData] The data that should be passed to the object upon activation. - * @param {string} [context] The name of the dialog context to use. Uses the default context if none is specified. - * @returns {Promise} A promise that resolves when the dialog is closed and returns any data passed at the time of closing. - */ - export function showDialog(obj: any, activationData?: any, context?: string):JQueryPromise; - - /** - * Shows a message box via the dialog plugin. - * @param {string} message The message to display in the dialog. - * @param {string} [title] The title message. - * @param {string[]} [options] The options to provide to the user. - * @returns {Promise} A promise that resolves when the message box is closed and returns the selected option. - */ - export function showMessage(message: string, title?: string, options?: string[]): JQueryPromise; - - /** - * Configures one or more plugins to be loaded and installed into the application. - * @method configurePlugins - * @param {object} config Keys are plugin names. Values can be truthy, to simply install the plugin, or a configuration object to pass to the plugin. - * @param {string} [baseUrl] The base url to load the plugins from. - */ - export function configurePlugins(config: Object, baseUrl?: string): void; - - /** - * Starts the application. - * @returns {promise} - */ - export function start(): JQueryPromise; - - /** - * Sets the root module/view for the application. - * @param {string} root The root view or module. - * @param {string} [transition] The transition to use from the previous root (or splash screen) into the new root. - * @param {string} [applicationHost] The application host element id. By default the id 'applicationHost' will be used. - */ - export function setRoot(root: any, transition?: string, applicationHost?: string): void; - - /** - * Sets the root module/view for the application. - * @param {string} root The root view or module. - * @param {string} [transition] The transition to use from the previous root (or splash screen) into the new root. - * @param {string} [applicationHost] The application host element. By default the id 'applicationHost' will be used. - */ - export function setRoot(root: any, transition?: string, applicationHost?: HTMLElement): void; - - /** - * Creates a subscription or registers a callback for the specified event. - * @param {string} events One or more events, separated by white space. - * @returns {Subscription} A subscription is returned. - */ - export function on(events: string): ts.EventSubscription; - - /** - * Creates a subscription or registers a callback for the specified event. - * @param {string} events One or more events, separated by white space. - * @param {function} [callback] The callback function to invoke when the event is triggered. - * @param {object} [context] An object to use as `this` when invoking the `callback`. - * @returns {Events} The events object is returned for chaining. - */ - export function on(events: string, callback: Function, context?: any): Events; - - /** - * Removes the callbacks for the specified events. - * @param {string} [events] One or more events, separated by white space to turn off. If no events are specified, then the callbacks will be removed. - * @param {function} [callback] The callback function to remove. If `callback` is not provided, all callbacks for the specified events will be removed. - * @param {object} [context] The object that was used as `this`. Callbacks with this context will be removed. - * @chainable - */ - export function off(events: string, callback: Function, context?: any): Events; - - /** - * Triggers the specified events. - * @param {string} [events] One or more events, separated by white space to trigger. - * @chainable - */ - export function trigger(events: string, ...eventArgs:any[]): Events; - - /** - * Creates a function that will trigger the specified events when called. Simplifies proxying jQuery (or other) events through to the events object. - * @param {string} events One or more events, separated by white space to trigger by invoking the returned function. - * @returns {function} Calling the function will invoke the previously specified events on the events object. - */ - export function proxy(events: string): Function; + var theModule: DurandalAppModule; + export = theModule; } /** @@ -832,7 +562,6 @@ declare module 'durandal/app' { * @requires knockout */ declare module 'plugins/dialog' { - import activator = require('durandal/activator'); import composition = require('durandal/composition'); /** @@ -907,7 +636,7 @@ declare module 'plugins/dialog' { interface Dialog { owner: any; context: DialogContext; - activator: activator.Activator; + activator: DurandalActivator; close(): JQueryPromise; settings: composition.CompositionContext; } @@ -947,7 +676,7 @@ declare module 'plugins/dialog' { * @param {DialogContext} dialogContext The context to add. */ export function addContext(name: string, modalContext: DialogContext): void; - + /** * Gets the dialog model that is associated with the specified object. * @param {object} obj The object for whom to retrieve the dialog. @@ -958,9 +687,9 @@ declare module 'plugins/dialog' { /** * Closes the dialog associated with the specified object. * @param {object} obj The object whose dialog should be closed. - * @param {object} result* The results to return back to the dialog caller after closing. + * @param {object} results* The results to return back to the dialog caller after closing. */ - export function close(obj: any, ...result: any[]): void; + export function close(obj: any, ...results: any[]): void; /** * Shows a dialog. @@ -993,41 +722,6 @@ declare module 'plugins/dialog' { * @requires jquery */ declare module 'plugins/history' { - interface HistoryOptions { - /** - * The function that will be called back when the fragment changes. - */ - routeHandler: (fragment: string) => void; - - /** - * The url root used to extract the fragment when using push state. - */ - root?: string; - - /** - * Use hash change when present. - * @default true - */ - hashChange?: boolean; - - /** - * Use push state when present. - * @default false - */ - pushState?: boolean; - - /** - * Prevents loading of the current url when activating history. - * @default false - */ - silent?: boolean; - } - - interface NavigationOptions { - trigger: boolean; - replace: boolean; - } - /** * The setTimeout interval used when the browser does not support hash change events. * @default 50 @@ -1059,7 +753,7 @@ declare module 'plugins/history' { * @param {HistoryOptions} options. * @returns {boolean|undefined} Returns true/false from loading the url unless the silent option was selected. */ - export function activate(options: HistoryOptions): boolean; + export function activate(options: DurandalHistoryOptions): boolean; /** * Disable history, perhaps temporarily. Not useful in a real app, but possibly useful for unit testing Routers. @@ -1102,7 +796,7 @@ declare module 'plugins/history' { * @param {object|boolean} options An options object with optional trigger and replace flags. You can also pass a boolean directly to set the trigger option. Trigger is `true` by default. * @return {boolean} Returns true/false from loading the url. */ - export function navigate(fragment: string, options: NavigationOptions): boolean; + export function navigate(fragment: string, options: DurandalNavigationOptions): boolean; /** * Navigates back in the browser history. @@ -1121,7 +815,7 @@ declare module 'plugins/http' { * @default callback */ export var callbackParam: string; - + /** * Makes an HTTP GET request. * @param {string} url The url to send the get request to. @@ -1138,7 +832,7 @@ declare module 'plugins/http' { * @returns {Promise} A promise of the response data. */ export function jsonp(url: string, query?: Object, callbackParam?: string): JQueryPromise; - + /** * Makes an HTTP POST request. * @param {string} url The url to send the post request to. @@ -1395,324 +1089,571 @@ declare module 'plugins/widget' { * @requires jquery */ declare module 'plugins/router' { - import activator = require('durandal/activator'); - import Events = require('durandal/events'); - import ts = require('durandal/typescript'); - - var RootRouter: ts.RootRouter; - - export = RootRouter; + var theModule: DurandalRootRouter; + export = theModule; } -/** - * Interface definitions used by other modules which were not possible to define within those modules due to TypeScript limitations. - */ -declare module 'durandal/typescript' { - import activator = require('durandal/activator'); - import history = require('plugins/history'); +interface DurandalEventSubscription { + /** + * Attaches a callback to the event subscription. + * @param {function} callback The callback function to invoke when the event is triggered. + * @param {object} [context] An object to use as `this` when invoking the `callback`. + * @chainable + */ + then(thenCallback: Function, context?: any): DurandalEventSubscription; /** - * Represents an event subscription. - * @class - */ - export interface EventSubscription { - /** - * Attaches a callback to the event subscription. - * @param {function} callback The callback function to invoke when the event is triggered. - * @param {object} [context] An object to use as `this` when invoking the `callback`. - * @chainable - */ - then(thenCallback: Function, context?: any): EventSubscription; + * Attaches a callback to the event subscription. + * @param {function} [callback] The callback function to invoke when the event is triggered. If `callback` is not provided, the previous callback will be re-activated. + * @param {object} [context] An object to use as `this` when invoking the `callback`. + * @chainable + */ + on(thenCallback: Function, context?: any): DurandalEventSubscription; - /** - * Attaches a callback to the event subscription. - * @param {function} [callback] The callback function to invoke when the event is triggered. If `callback` is not provided, the previous callback will be re-activated. - * @param {object} [context] An object to use as `this` when invoking the `callback`. - * @chainable - */ - on(thenCallback: Function, context?: any): EventSubscription; - - /** - * Cancels the subscription. - * @chainable - */ - off(): EventSubscription; - } - - export interface RouteConfiguration { - title?: string; - moduleId?: string; - hash?: string; - routePattern?: RegExp; - isActive?: KnockoutComputed; - } - - export interface RouteInstruction { - fragment: string; - queryString: string; - config: RouteConfiguration; - params: any[]; - queryParams: Object; - } - - export interface RelativeRouteSettings { - moduleId?: string; - route?: string; - fromParent?: boolean; - } - - export interface Router { - /** - * The route handlers that are registered. Each handler consists of a `routePattern` and a `callback`. - */ - handlers: { routePattern: RegExp; callback: (fragment: string) => void; }[]; - - /** - * The route configs that are registered. - */ - routes: RouteConfiguration[]; - - /** - * The active item/screen based on the current navigation state. - */ - activeItem: activator.Activator; - - /** - * The route configurations that have been designated as displayable in a nav ui (nav:true). - */ - navigationModel: KnockoutObservableArray; - - /** - * Indicates that the router (or a child router) is currently in the process of navigating. - */ - isNavigating: KnockoutComputed; - - /** - * An observable surfacing the active routing instruction that is currently being processed or has recently finished processing. - * The instruction object has `config`, `fragment`, `queryString`, `params` and `queryParams` properties. - */ - activeInstruction: KnockoutObservable; - - /** - * Parses a query string into an object. - * @param {string} queryString The query string to parse. - * @returns {object} An object keyed according to the query string parameters. - */ - parseQueryString(queryString: string): Object; - - /** - * Add a route to be tested when the url fragment changes. - * @param {RegEx} routePattern The route pattern to test against. - * @param {function} callback The callback to execute when the route pattern is matched. - */ - route(routePattern: RegExp, callback: (fragment: string) => void ): void; - - /** - * Attempt to load the specified URL fragment. If a route succeeds with a match, returns `true`. If no defined routes matches the fragment, returns `false`. - * @param {string} fragment The URL fragment to find a match for. - * @returns {boolean} True if a match was found, false otherwise. - */ - loadUrl(fragment: string): boolean; - - /** - * Updates the document title based on the activated module instance, the routing instruction and the app.title. - * @param {object} instance The activated module. - * @param {object} instruction The routing instruction associated with the action. It has a `config` property that references the original route mapping config. - */ - updateDocumentTitle(instance: Object, instruction: RouteInstruction): void; - - /** - * Save a fragment into the hash history, or replace the URL state if the - * 'replace' option is passed. You are responsible for properly URL-encoding - * the fragment in advance. - * The options object can contain `trigger: false` if you wish to not have the - * route callback be fired, or `replace: true`, if - * you wish to modify the current URL without adding an entry to the history. - * @param {string} fragment The url fragment to navigate to. - * @param {object|boolean} options An options object with optional trigger and replace flags. You can also pass a boolean directly to set the trigger option. Trigger is `true` by default. - * @return {boolean} Returns true/false from loading the url. - */ - navigate(fragment: string, trigger?: boolean): boolean; - - /** - * Save a fragment into the hash history, or replace the URL state if the - * 'replace' option is passed. You are responsible for properly URL-encoding - * the fragment in advance. - * The options object can contain `trigger: false` if you wish to not have the - * route callback be fired, or `replace: true`, if - * you wish to modify the current URL without adding an entry to the history. - * @param {string} fragment The url fragment to navigate to. - * @param {object|boolean} options An options object with optional trigger and replace flags. You can also pass a boolean directly to set the trigger option. Trigger is `true` by default. - * @return {boolean} Returns true/false from loading the url. - */ - navigate(fragment: string, options: history.NavigationOptions): boolean; - - /** - * Navigates back in the browser history. - */ - navigateBack(): void; - - /** - * Converts a route to a hash suitable for binding to a link's href. - * @param {string} route - * @returns {string} The hash. - */ - convertRouteToHash(route: string): string; - - /** - * Converts a route to a module id. This is only called if no module id is supplied as part of the route mapping. - * @param {string} route - * @returns {string} The module id. - */ - convertRouteToModuleId(route: string): string; - - /** - * Converts a route to a displayable title. This is only called if no title is specified as part of the route mapping. - * @method convertRouteToTitle - * @param {string} route - * @returns {string} The title. - */ - convertRouteToTitle(route: string): string; - - /** - * Maps route patterns to modules. - * @param {string} route A route. - * @chainable - */ - map(route: string): Router; - - /** - * Maps route patterns to modules. - * @param {string} route A route pattern. - * @param {string} moduleId The module id to map the route to. - * @chainable - */ - map(route: string, moduleId: string): Router; - - /** - * Maps route patterns to modules. - * @param {RegExp} route A route pattern. - * @param {string} moduleId The module id to map the route to. - * @chainable - */ - map(route: RegExp, moduleId: string): Router; - - /** - * Maps route patterns to modules. - * @param {string} route A route pattern. - * @param {RouteConfiguration} config The route's configuration. - * @chainable - */ - map(route: string, config: RouteConfiguration): Router; - - /** - * Maps route patterns to modules. - * @method map - * @param {RegExp} route A route pattern. - * @param {RouteConfiguration} config The route's configuration. - * @chainable - */ - map(route: RegExp, config: RouteConfiguration): Router; - - /** - * Maps route patterns to modules. - * @param {RouteConfiguration} config The route's configuration. - * @chainable - */ - map(config: RouteConfiguration): Router; - - /** - * Maps route patterns to modules. - * @param {RouteConfiguration[]} configs An array of route configurations. - * @chainable - */ - map(configs: RouteConfiguration[]): Router; - - /** - * Builds an observable array designed to bind a navigation UI to. The model will exist in the `navigationModel` property. - * @param {number} defaultOrder The default order to use for navigation visible routes that don't specify an order. The defualt is 100. - * @chainable - */ - buildNavigationModel(defaultOrder?: number): Router; - - /** - * Configures the router to map unknown routes to modules at the same path. - * @chainable - */ - mapUnknownRoutes(): Router; - - /** - * Configures the router use the specified module id for all unknown routes. - * @param {string} notFoundModuleId Represents the module id to route all unknown routes to. - * @param {string} [replaceRoute] Optionally provide a route to replace the url with. - * @chainable - */ - mapUnknownRoutes(notFoundModuleId: string, replaceRoute?: string): Router; - - /** - * Configures how the router will handle unknown routes. - * @param {function} callback Called back with the route instruction containing the route info. The function can then modify the instruction by adding a moduleId and the router will take over from there. - * @chainable - */ - mapUnknownRoutes(callback: (instruction: RouteInstruction) => void ): Router; - - /** - * Configures how the router will handle unknown routes. - * @param {RouteConfiguration} config The route configuration to use for unknown routes. - * @chainable - */ - mapUnknownRoutes(config: RouteConfiguration): Router; - - /** - * Resets the router by removing handlers, routes, event handlers and previously configured options. - * @chainable - */ - reset(): Router; - - /** - * Makes all configured routes and/or module ids relative to a certain base url. - * @param {string} settings The value is used as the base for routes and module ids. - * @chainable - */ - makeRelative(settings: string): Router; - - /** - * Makes all configured routes and/or module ids relative to a certain base url. - * @param {RelativeRouteSettings} settings If an object, you can specify `route` and `moduleId` separately. In place of specifying route, you can set `fromParent:true` to make routes automatically relative to the parent router's active route. - * @chainable - */ - makeRelative(settings: RelativeRouteSettings): Router; - - /** - * Creates a child router. - * @returns {Router} The child router. - */ - createChildRouter(): Router; - - /** - * Inspects routes and modules before activation. Can be used to protect access by cancelling navigation or redirecting. - * @param {object} instance The module instance that is about to be activated by the router. - * @param {object} instruction The route instruction. The instruction object has config, fragment, queryString, params and queryParams properties. - * @returns {Promise|Boolean|String} If a boolean, determines whether or not the route should activate or be cancelled. If a string, causes a redirect to the specified route. Can also be a promise for either of these value types. - */ - guardRoute?:(instance:Object, instruction:RouteInstruction) => any; - } - - export interface RootRouter extends Router { - /** - * Activates the router and the underlying history tracking mechanism. - * @returns {Promise} A promise that resolves when the router is ready. - */ - activate(options?: history.HistoryOptions): JQueryPromise; - - /** - * Disable history, perhaps temporarily. Not useful in a real app, but possibly useful for unit testing Routers. - */ - deactivate(): void; - - /** - * Installs the router's custom ko binding handler. - */ - install(): void; - } + /** + * Cancels the subscription. + * @chainable + */ + off(): DurandalEventSubscription; } + +interface DurandalEventSupport { + /** + * Creates a subscription or registers a callback for the specified event. + * @param {string} events One or more events, separated by white space. + * @returns {Subscription} A subscription is returned. + */ + on(events: string): DurandalEventSubscription; + + /** + * Creates a subscription or registers a callback for the specified event. + * @param {string} events One or more events, separated by white space. + * @param {function} [callback] The callback function to invoke when the event is triggered. + * @param {object} [context] An object to use as `this` when invoking the `callback`. + * @returns {Events} The events object is returned for chaining. + */ + on(events: string, callback: Function, context?: any): T; + + /** + * Removes the callbacks for the specified events. + * @param {string} [events] One or more events, separated by white space to turn off. If no events are specified, then the callbacks will be removed. + * @param {function} [callback] The callback function to remove. If `callback` is not provided, all callbacks for the specified events will be removed. + * @param {object} [context] The object that was used as `this`. Callbacks with this context will be removed. + * @chainable + */ + off(events: string, callback: Function, context?: any): T; + + /** + * Triggers the specified events. + * @param {string} [events] One or more events, separated by white space to trigger. + * @chainable + */ + trigger(events: string, ...eventArgs: any[]): T; + + /** + * Creates a function that will trigger the specified events when called. Simplifies proxying jQuery (or other) events through to the events object. + * @param {string} events One or more events, separated by white space to trigger by invoking the returned function. + * @returns {function} Calling the function will invoke the previously specified events on the events object. + */ + proxy(events: string): Function; +} + +interface DurandalEventModule { + new (): DurandalEventSupport; + includeIn(targetObject: any): void; +} + +interface DurandalAppModule extends DurandalEventSupport { + /** + * The title of your application. + */ + title: string; + + /** + * Shows a dialog via the dialog plugin. + * @param {object|string} obj The object (or moduleId) to display as a dialog. + * @param {object} [activationData] The data that should be passed to the object upon activation. + * @param {string} [context] The name of the dialog context to use. Uses the default context if none is specified. + * @returns {Promise} A promise that resolves when the dialog is closed and returns any data passed at the time of closing. + */ + showDialog(obj: any, activationData?: any, context?: string): JQueryPromise; + + /** + * Shows a message box via the dialog plugin. + * @param {string} message The message to display in the dialog. + * @param {string} [title] The title message. + * @param {string[]} [options] The options to provide to the user. + * @returns {Promise} A promise that resolves when the message box is closed and returns the selected option. + */ + showMessage(message: string, title?: string, options?: string[]): JQueryPromise; + + /** + * Configures one or more plugins to be loaded and installed into the application. + * @method configurePlugins + * @param {object} config Keys are plugin names. Values can be truthy, to simply install the plugin, or a configuration object to pass to the plugin. + * @param {string} [baseUrl] The base url to load the plugins from. + */ + configurePlugins(config: Object, baseUrl?: string): void; + + /** + * Starts the application. + * @returns {promise} + */ + start(): JQueryPromise; + + /** + * Sets the root module/view for the application. + * @param {string} root The root view or module. + * @param {string} [transition] The transition to use from the previous root (or splash screen) into the new root. + * @param {string} [applicationHost] The application host element id. By default the id 'applicationHost' will be used. + */ + setRoot(root: any, transition?: string, applicationHost?: string): void; + + /** + * Sets the root module/view for the application. + * @param {string} root The root view or module. + * @param {string} [transition] The transition to use from the previous root (or splash screen) into the new root. + * @param {string} [applicationHost] The application host element. By default the id 'applicationHost' will be used. + */ + setRoot(root: any, transition?: string, applicationHost?: HTMLElement): void; +} + +interface DurandalActivatorSettings { + /** + * The default value passed to an object's deactivate function as its close parameter. + * @default true + */ + closeOnDeactivate: boolean; + + /** + * Lower-cased words which represent a truthy value. + * @default ['yes', 'ok', 'true'] + */ + affirmations: string[]; + + /** + * Interprets the response of a `canActivate` or `canDeactivate` call using the known affirmative values in the `affirmations` array. + * @param {object} value + * @returns {boolean} + */ + interpretResponse(value: any): boolean; + + /** + * Determines whether or not the current item and the new item are the same. + * @param {object} currentItem + * @param {object} newItem + * @param {object} currentActivationData + * @param {object} newActivationData + * @returns {boolean} + */ + areSameItem(currentItem: any, newItem: any, currentActivationData: any, newActivationData: any): boolean; + + /** + * Called immediately before the new item is activated. + * @param {object} newItem + */ + beforeActivate(newItem: any): any; + + /** + * Called immediately after the old item is deactivated. + * @param {object} oldItem The previous item. + * @param {boolean} close Whether or not the previous item was closed. + * @param {function} setter The activate item setter function. + */ + afterDeactivate(oldItem: any, close: boolean, setter: Function): void; +} + +interface DurandalActivator extends KnockoutComputed { + /** + * The settings for this activator. + */ + settings: DurandalActivatorSettings; + + /** + * An observable which indicates whether or not the activator is currently in the process of activating an instance. + * @returns {boolean} + */ + isActivating: KnockoutObservable; + + /** + * Determines whether or not the specified item can be deactivated. + * @param {object} item The item to check. + * @param {boolean} close Whether or not to check if close is possible. + * @returns {promise} + */ + canDeactivateItem(item: T, close: boolean): JQueryPromise; + + /** + * Deactivates the specified item. + * @param {object} item The item to deactivate. + * @param {boolean} close Whether or not to close the item. + * @returns {promise} + */ + deactivateItem(item: T, close: boolean): JQueryPromise; + + /** + * Determines whether or not the specified item can be activated. + * @param {object} item The item to check. + * @param {object} activationData Data associated with the activation. + * @returns {promise} + */ + canActivateItem(newItem: T, activationData?: any): JQueryPromise; + + /** + * Activates the specified item. + * @param {object} newItem The item to activate. + * @param {object} newActivationData Data associated with the activation. + * @returns {promise} + */ + activateItem(newItem: T, activationData?: any): JQueryPromise; + + /** + * Determines whether or not the activator, in its current state, can be activated. + * @returns {promise} + */ + canActivate(): JQueryPromise; + + /** + * Activates the activator, in its current state. + * @returns {promise} + */ + activate(): JQueryPromise; + + /** + * Determines whether or not the activator, in its current state, can be deactivated. + * @returns {promise} + */ + canDeactivate(close: boolean): JQueryPromise; + + /** + * Deactivates the activator, in its current state. + * @returns {promise} + */ + deactivate(close: boolean): JQueryPromise; + + /** + * Adds canActivate, activate, canDeactivate and deactivate functions to the provided model which pass through to the corresponding functions on the activator. + */ + includeIn(includeIn: any): void; + + /** + * Sets up a collection representing a pool of objects which the activator will activate. See below for details. Activators without an item bool always close their values on deactivate. Activators with an items pool only deactivate, but do not close them. + */ + forItems(items): DurandalActivator; +} + +interface DurandalHistoryOptions { + /** + * The function that will be called back when the fragment changes. + */ + routeHandler: (fragment: string) => void; + + /** + * The url root used to extract the fragment when using push state. + */ + root?: string; + + /** + * Use hash change when present. + * @default true + */ + hashChange?: boolean; + + /** + * Use push state when present. + * @default false + */ + pushState?: boolean; + + /** + * Prevents loading of the current url when activating history. + * @default false + */ + silent?: boolean; +} + +interface DurandalNavigationOptions { + trigger: boolean; + replace: boolean; +} + +interface DurandalRouteConfiguration { + title?: string; + moduleId?: string; + hash?: string; + route?: string; + routePattern?: RegExp; + isActive?: KnockoutComputed; + nav:any; +} + +interface DurandalRouteInstruction { + fragment: string; + queryString: string; + config: DurandalRouteConfiguration; + params: any[]; + queryParams: Object; +} + +interface DurandalRelativeRouteSettings { + moduleId?: string; + route?: string; + fromParent?: boolean; +} + +interface DurandalRouterBase extends DurandalEventSupport { + /** + * The route handlers that are registered. Each handler consists of a `routePattern` and a `callback`. + */ + handlers: { routePattern: RegExp; callback: (fragment: string) => void; }[]; + + /** + * The route configs that are registered. + */ + routes: DurandalRouteConfiguration[]; + + /** + * The active item/screen based on the current navigation state. + */ + activeItem: DurandalActivator; + + /** + * The route configurations that have been designated as displayable in a nav ui (nav:true). + */ + navigationModel: KnockoutObservableArray; + + /** + * Indicates that the router (or a child router) is currently in the process of navigating. + */ + isNavigating: KnockoutComputed; + + /** + * An observable surfacing the active routing instruction that is currently being processed or has recently finished processing. + * The instruction object has `config`, `fragment`, `queryString`, `params` and `queryParams` properties. + */ + activeInstruction: KnockoutObservable; + + /** + * Parses a query string into an object. + * @param {string} queryString The query string to parse. + * @returns {object} An object keyed according to the query string parameters. + */ + parseQueryString(queryString: string): Object; + + /** + * Add a route to be tested when the url fragment changes. + * @param {RegEx} routePattern The route pattern to test against. + * @param {function} callback The callback to execute when the route pattern is matched. + */ + route(routePattern: RegExp, callback: (fragment: string) => void): void; + + /** + * Attempt to load the specified URL fragment. If a route succeeds with a match, returns `true`. If no defined routes matches the fragment, returns `false`. + * @param {string} fragment The URL fragment to find a match for. + * @returns {boolean} True if a match was found, false otherwise. + */ + loadUrl(fragment: string): boolean; + + /** + * Updates the document title based on the activated module instance, the routing instruction and the app.title. + * @param {object} instance The activated module. + * @param {object} instruction The routing instruction associated with the action. It has a `config` property that references the original route mapping config. + */ + updateDocumentTitle(instance: Object, instruction: DurandalRouteInstruction): void; + + /** + * Save a fragment into the hash history, or replace the URL state if the + * 'replace' option is passed. You are responsible for properly URL-encoding + * the fragment in advance. + * The options object can contain `trigger: false` if you wish to not have the + * route callback be fired, or `replace: true`, if + * you wish to modify the current URL without adding an entry to the history. + * @param {string} fragment The url fragment to navigate to. + * @param {object|boolean} options An options object with optional trigger and replace flags. You can also pass a boolean directly to set the trigger option. Trigger is `true` by default. + * @return {boolean} Returns true/false from loading the url. + */ + navigate(fragment: string, trigger?: boolean): boolean; + + /** + * Save a fragment into the hash history, or replace the URL state if the + * 'replace' option is passed. You are responsible for properly URL-encoding + * the fragment in advance. + * The options object can contain `trigger: false` if you wish to not have the + * route callback be fired, or `replace: true`, if + * you wish to modify the current URL without adding an entry to the history. + * @param {string} fragment The url fragment to navigate to. + * @param {object|boolean} options An options object with optional trigger and replace flags. You can also pass a boolean directly to set the trigger option. Trigger is `true` by default. + * @return {boolean} Returns true/false from loading the url. + */ + navigate(fragment: string, options: DurandalNavigationOptions): boolean; + + /** + * Navigates back in the browser history. + */ + navigateBack(): void; + + /** + * Converts a route to a hash suitable for binding to a link's href. + * @param {string} route + * @returns {string} The hash. + */ + convertRouteToHash(route: string): string; + + /** + * Converts a route to a module id. This is only called if no module id is supplied as part of the route mapping. + * @param {string} route + * @returns {string} The module id. + */ + convertRouteToModuleId(route: string): string; + + /** + * Converts a route to a displayable title. This is only called if no title is specified as part of the route mapping. + * @method convertRouteToTitle + * @param {string} route + * @returns {string} The title. + */ + convertRouteToTitle(route: string): string; + + /** + * Maps route patterns to modules. + * @param {string} route A route. + * @chainable + */ + map(route: string): T; + + /** + * Maps route patterns to modules. + * @param {string} route A route pattern. + * @param {string} moduleId The module id to map the route to. + * @chainable + */ + map(route: string, moduleId: string): T; + + /** + * Maps route patterns to modules. + * @param {RegExp} route A route pattern. + * @param {string} moduleId The module id to map the route to. + * @chainable + */ + map(route: RegExp, moduleId: string): T; + + /** + * Maps route patterns to modules. + * @param {string} route A route pattern. + * @param {RouteConfiguration} config The route's configuration. + * @chainable + */ + map(route: string, config: DurandalRouteConfiguration): T; + + /** + * Maps route patterns to modules. + * @method map + * @param {RegExp} route A route pattern. + * @param {RouteConfiguration} config The route's configuration. + * @chainable + */ + map(route: RegExp, config: DurandalRouteConfiguration): T; + + /** + * Maps route patterns to modules. + * @param {RouteConfiguration} config The route's configuration. + * @chainable + */ + map(config: DurandalRouteConfiguration): T; + + /** + * Maps route patterns to modules. + * @param {RouteConfiguration[]} configs An array of route configurations. + * @chainable + */ + map(configs: DurandalRouteConfiguration[]): T; + + /** + * Builds an observable array designed to bind a navigation UI to. The model will exist in the `navigationModel` property. + * @param {number} defaultOrder The default order to use for navigation visible routes that don't specify an order. The defualt is 100. + * @chainable + */ + buildNavigationModel(defaultOrder?: number): T; + + /** + * Configures the router to map unknown routes to modules at the same path. + * @chainable + */ + mapUnknownRoutes(): T; + + /** + * Configures the router use the specified module id for all unknown routes. + * @param {string} notFoundModuleId Represents the module id to route all unknown routes to. + * @param {string} [replaceRoute] Optionally provide a route to replace the url with. + * @chainable + */ + mapUnknownRoutes(notFoundModuleId: string, replaceRoute?: string): T; + + /** + * Configures how the router will handle unknown routes. + * @param {function} callback Called back with the route instruction containing the route info. The function can then modify the instruction by adding a moduleId and the router will take over from there. + * @chainable + */ + mapUnknownRoutes(callback: (instruction: DurandalRouteInstruction) => void): T; + + /** + * Configures how the router will handle unknown routes. + * @param {RouteConfiguration} config The route configuration to use for unknown routes. + * @chainable + */ + mapUnknownRoutes(config: DurandalRouteConfiguration): T; + + /** + * Resets the router by removing handlers, routes, event handlers and previously configured options. + * @chainable + */ + reset(): T; + + /** + * Makes all configured routes and/or module ids relative to a certain base url. + * @param {string} settings The value is used as the base for routes and module ids. + * @chainable + */ + makeRelative(settings: string): T; + + /** + * Makes all configured routes and/or module ids relative to a certain base url. + * @param {RelativeRouteSettings} settings If an object, you can specify `route` and `moduleId` separately. In place of specifying route, you can set `fromParent:true` to make routes automatically relative to the parent router's active route. + * @chainable + */ + makeRelative(settings: DurandalRelativeRouteSettings): T; + + /** + * Creates a child router. + * @returns {Router} The child router. + */ + createChildRouter(): T; + + /** + * Inspects routes and modules before activation. Can be used to protect access by cancelling navigation or redirecting. + * @param {object} instance The module instance that is about to be activated by the router. + * @param {object} instruction The route instruction. The instruction object has config, fragment, queryString, params and queryParams properties. + * @returns {Promise|Boolean|String} If a boolean, determines whether or not the route should activate or be cancelled. If a string, causes a redirect to the specified route. Can also be a promise for either of these value types. + */ + guardRoute?: (instance: Object, instruction: DurandalRouteInstruction) => any; +} + +interface DurandalRouter extends DurandalRouterBase { } + +interface DurandalRootRouter extends DurandalRouterBase { + /** + * Activates the router and the underlying history tracking mechanism. + * @returns {Promise} A promise that resolves when the router is ready. + */ + activate(options?: DurandalHistoryOptions): JQueryPromise; + + /** + * Disable history, perhaps temporarily. Not useful in a real app, but possibly useful for unit testing Routers. + */ + deactivate(): void; + + /** + * Installs the router's custom ko binding handler. + */ + install(): void; +} \ No newline at end of file