From 945a61bd2138870e6fa1804eff749b106fd7eb77 Mon Sep 17 00:00:00 2001 From: Peter Palotas Date: Sun, 28 Dec 2014 19:32:20 +0100 Subject: [PATCH] - Added documentation to Marionette.RegionManager. - Added constructor with options to Marionette.RegionManager. - Added overloads to addRegions with more specific types. - Specified type of parameter for RegionManager.removeRegion. --- marionette/marionette.d.ts | 281 +++++++++++++++++++++++++++++++++---- 1 file changed, 252 insertions(+), 29 deletions(-) diff --git a/marionette/marionette.d.ts b/marionette/marionette.d.ts index 954acaf3b..ab92482dd 100644 --- a/marionette/marionette.d.ts +++ b/marionette/marionette.d.ts @@ -132,45 +132,274 @@ declare module Marionette { function unbindEntityEvents(target, entity, bindings); class Callbacks { - add(callback:Function, contextOverride:any): void; - run(options:any, context:any): void; + add(callback: Function, contextOverride: any): void; + run(options: any, context: any): void; reset(): void; } - class Controller extends Backbone.Events { - destroy(); + /** + * A base class which other classes can extend from. Object incorporates many + * backbone conventions and utilities like initialize and Backbone.Events. + */ + class Object extends Backbone.Events { + /** + * Initialize is called immediately after the Object has been instantiated, + * and is invoked with the same arguments that the constructor received. + */ + initialize(options?: any); + + /** + * Retrieve an object's attribute either directly from the object, or from + * the object's this.options, with this.options taking precedence. + * @param optionName the name of the option to retrieve. + */ + getOption(optionName: string): any; + + /** + * Objects have a destroy method that unbind the events that are directly + * attached to the instance. Invoking the destroy method will trigger a + * "before:destroy" event and corresponding onBeforeDestroy method call. + * These calls will be passed any arguments destroy was invoked with. + * @param args any arguments to pass to the "before:destory" event and call to + * onBeforeDestroy. + */ + destroy(...args: any[]): void; } - class Region extends Backbone.Events { + /** + * A Controller is an object used in the Marionette Router. Controllers are + * where you store your Router's callbacks. + */ + class Controller extends Backbone.Events { + /** + * @param options Options that should be stored in this options. Can be retreived via + * getOption. + */ + constructor(options?: any); - static buildRegion(regionConfig, defaultRegionType): Region; + /** + * Handles unbinding all of the events that are directly attached to the + * controller instance, as well as those that are bound using the + * EventBinder from the controller. + * + * Invoking the destroy method will trigger the "before:destroy" and + * "destroy" events and the corresponding onBeforeDestory and onDestroy + * method calls. These calls will be passed any arguments destroy was + * invoked with. + */ + destroy(...args: any[]): void; + /** + * Retrieve an object's attribute either directly from the object, or from + * the object's this.options, with this.options taking precedence. + * @param optionName the name of the option to retrieve. + */ + getOption(optionName: string): any; + } + + interface RegionConstructionOptions { + /** + * Specifies the element for the region to manage. This may be + * a selector string, a raw DOM node reference or a jQuery wrapped + * DOM node. + */ + el?: any; + } + + interface RegionShowOptions { + /** + * If you replace the current view with a new view by calling show, by + * default it will automatically destroy the previous view. You can + * prevent this behavior by setting this option to true. + */ + preventDestroy?: boolean; + + /** + * If you re-call show with the same view, by default nothing will happen + * because the view is already in the region. You can force the view to be + * re-shown by setting this option to true. + */ + forceShow?: boolean; + + /** + * Regions that are attached to the document when you execute show are + * special in that the views that they show will also become attached + * to the document. These regions fire a pair of triggerMethods on all + * of the views that are about to be attached – even the nested ones. + * This can cause a performance issue if you're rendering hundreds or + * thousands of views at once. + * If you think these events might be causing some lag in your app, you + * can selectively turn them off with the triggerBeforeAttach + * and triggerAttach properties. + */ + triggerBeforeAttach?: boolean; + + /** + * Regions that are attached to the document when you execute show are + * special in that the views that they show will also become attached + * to the document. These regions fire a pair of triggerMethods on all + * of the views that are about to be attached – even the nested ones. + * This can cause a performance issue if you're rendering hundreds or + * thousands of views at once. + * If you think these events might be causing some lag in your app, you + * can selectively turn them off with the triggerBeforeAttach + * and triggerAttach properties. + */ + triggerAttach?: boolean; + } + + /** + * Regions provide consistent methods to manage, show and destroy views in + * your applications and layouts. They use a jQuery selector to show your + * views in the correct place. + */ + class Region extends Marionette.Object { + + /** + * Build an instance of a region by passing in a configuration object and + * a default region class to use if none is specified in the config. + * The config object should either be a string as a jQuery DOM selector, + * a Region class directly, or an object literal that specifies a selector, + * a custom regionClass, and any options to be supplied to the region + */ + static buildRegion(regionConfig: any, defaultRegionType: any): Region; + + /** + * You can specify an el for the region to manage at the time the region + * is instantiated. + */ + constructor(options?: RegionConstructionOptions); + + /** + * Contains the element that this region should manage. + */ el: any; - show(view: Backbone.View): void; - ensureEl(): void; -<<<<<<< HEAD - open(view: Backbone.View): void; - destroy(): void; - attachView(view: Backbone.View); -======= - open(view: Backbone.View): void; - close(): void; - attachView(view: Backbone.View); ->>>>>>> marionette.superfluous.generics.removed - reset(); + /** + * Renders and displays the specified view in this region. + * @param view the view to display. + */ + show(view: Backbone.View, options?: RegionShowOptions): void; + + /** + * Attaches an existing view to a region, without rendering or showing the view, + * and without replacing the HTML content of the region. + */ + attachView(view: Backbone.View, options?: RegionShowOptions): any; + + /** + * A region can be reset at any time. This destroys any existing view + * being displayed, and deletes the cached el. The next time the region + * shows a view, the region's el is queried from the DOM. + */ + reset(): any; + + /** + * If you wish to check whether a region has a view, you can use the hasView function. This will return a boolean value depending whether or not the region is showing a view. + */ hasView(): boolean; - empty(); + + /** + * Empties the current view from the region. + */ + empty(): any; } + interface RegionDefaults { + /** + * A selector string indicating which element to assign the region two. + */ + selector?: string; + + /** + * A selector string, a jQuery object, or an HTML node indicating which element + * the region should use. + */ + el?: any; + + /** + * A custom region class. + */ + regionClass?: any; + + /** + * Ordinarily regions enforce the presence of a backing DOM element. In + * some instances it may be desirable to allow regions to be instantiated + * and used without an element, such as when regions defined by a parent + * LayoutView class are used by only some of its subclasses. In these + * instances, the region can be defined with this option set to true, + * suppressing the missing element error and causing show calls to the + * region to be treated as no-ops. + */ + allowMissingEl?: boolean; + } + + /** + * Region managers provide a consistent way to manage a number of Marionette.Region + * objects within an application. The RegionManager is intended to be used by + * other objects, to facilitate the addition, storage, retrieval, and removal of + * regions from that object. + */ class RegionManager extends Controller { - addRegions(regionDefinitions, defaults?): any; - addRegion(name, definition): Region; + + /** + * Constructor. + * @param options May contain an optional `regions` option. These regions + * are passed directly into addRegions for this instance. + */ + constructor(options?: any); + + /** + * Adds one or more regions to this RegionManager instance. + * @param regionDefinitions a function returning an object literal with the region definitions. The function will + * be called with the RegionManager instance context and all the arguments passed to addRegions. + * @param defaults Specifies default options that will be applied to every region added. + * @returns an object literal with all the created regions. + */ + addRegions(regionDefinitions: Function, defaults?: RegionDefaults): any; + + /** + * Adds one or more regions to this RegionManager instance. + * @param regionDefinitions an object literal containing region names as keys and region + * definitions as values. + * @param defaults Specifies default options that will be applied to every region added. + * @returns an object literal with all the created regions. + */ + addRegions(regionDefinitions: { [regionName: string]: any }, defaults?: RegionDefaults): any; + + /** + * Adds a region to this RegionManager. + * @param name the region name. + * @param definition the region definition. This may be a selector, object literal + * with various region creation options or an instance of a region object. + */ + addRegion(name: string, definition: any): Region; + + /** + * Gets the region with the specified name from this RegionManager. + */ get(name: string): Region; - removeRegion(name): void; + + /** + * Removes the region with the specified name from this RegionManager. + */ + removeRegion(name: string): void; + + /** + * Removes all regions from the RegionManager. + */ removeRegions(): void; - emptyRegions(): void; + + /** + * Empties all regions from the RegionManager instance. + */ + emptyRegions(): void; + + /** + * Destroys the RegionManager instance entierly which both destroys and + * removes all regions from the RegionManager instance. + */ destroy(); //mixins from Collection (copied from Backbone's Collection declaration) @@ -324,15 +553,9 @@ declare module Marionette { addInitializer(initializer); start(options?); addRegions(regions); -<<<<<<< HEAD emptyRegions(): void; - removeRegion(region: Region); - getRegion(regionName: string): Region; -======= - closeRegions(): void; removeRegion(region: Region); getRegion(regionName: string): Region; ->>>>>>> marionette.superfluous.generics.removed module(moduleNames, moduleDefinition); }