lib/dijit/layout/StackContainer.js

   1 /*
   2         Copyright (c) 2004-2011, The Dojo Foundation All Rights Reserved.
   3         Available via Academic Free License >= 2.1 OR the modified BSD license.
   4         see: http://dojotoolkit.org/license for details
   5 */
   6
   7
   8 if(!dojo._hasResource["dijit.layout.StackContainer"]){ //_hasResource checks added by build. Do not use _hasResource directly in your code.
   9 dojo._hasResource["dijit.layout.StackContainer"] = true;
  10 dojo.provide("dijit.layout.StackContainer");
  11 dojo.require("dijit._Templated");
  12 dojo.require("dijit.layout._LayoutWidget");
  13 dojo.requireLocalization("dijit", "common", null, "ROOT,ar,ca,cs,da,de,el,es,fi,fr,he,hu,it,ja,kk,ko,nb,nl,pl,pt,pt-pt,ro,ru,sk,sl,sv,th,tr,zh,zh-tw");
  14 dojo.require("dojo.cookie");
  15 dojo.require("dijit.layout.StackController");
  16
  17
  18 dojo.declare(
  19         "dijit.layout.StackContainer",
  20         dijit.layout._LayoutWidget,
  21         {
  22         // summary:
  23         //              A container that has multiple children, but shows only
  24         //              one child at a time
  25         //
  26         // description:
  27         //              A container for widgets (ContentPanes, for example) That displays
  28         //              only one Widget at a time.
  29         //
  30         //              Publishes topics [widgetId]-addChild, [widgetId]-removeChild, and [widgetId]-selectChild
  31         //
  32         //              Can be base class for container, Wizard, Show, etc.
  33
  34         // doLayout: Boolean
  35         //              If true, change the size of my currently displayed child to match my size
  36         doLayout: true,
  37
  38         // persist: Boolean
  39         //              Remembers the selected child across sessions
  40         persist: false,
  41
  42         baseClass: "dijitStackContainer",
  43
  44 /*=====
  45         // selectedChildWidget: [readonly] dijit._Widget
  46         //              References the currently selected child widget, if any.
  47         //              Adjust selected child with selectChild() method.
  48         selectedChildWidget: null,
  49 =====*/
  50
  51         buildRendering: function(){
  52                 this.inherited(arguments);
  53                 dojo.addClass(this.domNode, "dijitLayoutContainer");
  54                 dijit.setWaiRole(this.containerNode, "tabpanel");
  55         },
  56
  57         postCreate: function(){
  58                 this.inherited(arguments);
  59                 this.connect(this.domNode, "onkeypress", this._onKeyPress);
  60         },
  61
  62         startup: function(){
  63                 if(this._started){ return; }
  64
  65                 var children = this.getChildren();
  66
  67                 // Setup each page panel to be initially hidden
  68                 dojo.forEach(children, this._setupChild, this);
  69
  70                 // Figure out which child to initially display, defaulting to first one
  71                 if(this.persist){
  72                         this.selectedChildWidget = dijit.byId(dojo.cookie(this.id + "_selectedChild"));
  73                 }else{
  74                         dojo.some(children, function(child){
  75                                 if(child.selected){
  76                                         this.selectedChildWidget = child;
  77                                 }
  78                                 return child.selected;
  79                         }, this);
  80                 }
  81                 var selected = this.selectedChildWidget;
  82                 if(!selected && children[0]){
  83                         selected = this.selectedChildWidget = children[0];
  84                         selected.selected = true;
  85                 }
  86
  87                 // Publish information about myself so any StackControllers can initialize.
  88                 // This needs to happen before this.inherited(arguments) so that for
  89                 // TabContainer, this._contentBox doesn't include the space for the tab labels.
  90                 dojo.publish(this.id+"-startup", [{children: children, selected: selected}]);
  91
  92                 // Startup each child widget, and do initial layout like setting this._contentBox,
  93                 // then calls this.resize() which does the initial sizing on the selected child.
  94                 this.inherited(arguments);
  95         },
  96
  97         resize: function(){
  98                 // Resize is called when we are first made visible (it's called from startup()
  99                 // if we are initially visible).   If this is the first time we've been made
 100                 // visible then show our first child.
 101                 var selected = this.selectedChildWidget;
 102                 if(selected && !this._hasBeenShown){
 103                         this._hasBeenShown = true;
 104                         this._showChild(selected);
 105                 }
 106                 this.inherited(arguments);
 107         },
 108
 109         _setupChild: function(/*dijit._Widget*/ child){
 110                 // Overrides _LayoutWidget._setupChild()
 111
 112                 this.inherited(arguments);
 113
 114                 dojo.replaceClass(child.domNode, "dijitHidden", "dijitVisible");
 115
 116                 // remove the title attribute so it doesn't show up when i hover
 117                 // over a node
 118                 child.domNode.title = "";
 119         },
 120
 121         addChild: function(/*dijit._Widget*/ child, /*Integer?*/ insertIndex){
 122                 // Overrides _Container.addChild() to do layout and publish events
 123
 124                 this.inherited(arguments);
 125
 126                 if(this._started){
 127                         dojo.publish(this.id+"-addChild", [child, insertIndex]);
 128
 129                         // in case the tab titles have overflowed from one line to two lines
 130                         // (or, if this if first child, from zero lines to one line)
 131                         // TODO: w/ScrollingTabController this is no longer necessary, although
 132                         // ScrollTabController.resize() does need to get called to show/hide
 133                         // the navigation buttons as appropriate, but that's handled in ScrollingTabController.onAddChild()
 134                         this.layout();
 135
 136                         // if this is the first child, then select it
 137                         if(!this.selectedChildWidget){
 138                                 this.selectChild(child);
 139                         }
 140                 }
 141         },
 142
 143         removeChild: function(/*dijit._Widget*/ page){
 144                 // Overrides _Container.removeChild() to do layout and publish events
 145
 146                 this.inherited(arguments);
 147
 148                 if(this._started){
 149                         // this will notify any tablists to remove a button; do this first because it may affect sizing
 150                         dojo.publish(this.id + "-removeChild", [page]);
 151                 }
 152
 153                 // If we are being destroyed than don't run the code below (to select another page), because we are deleting
 154                 // every page one by one
 155                 if(this._beingDestroyed){ return; }
 156
 157                 // Select new page to display, also updating TabController to show the respective tab.
 158                 // Do this before layout call because it can affect the height of the TabController.
 159                 if(this.selectedChildWidget === page){
 160                         this.selectedChildWidget = undefined;
 161                         if(this._started){
 162                                 var children = this.getChildren();
 163                                 if(children.length){
 164                                         this.selectChild(children[0]);
 165                                 }
 166                         }
 167                 }
 168
 169                 if(this._started){
 170                         // In case the tab titles now take up one line instead of two lines
 171                         // (note though that ScrollingTabController never overflows to multiple lines),
 172                         // or the height has changed slightly because of addition/removal of tab which close icon
 173                         this.layout();
 174                 }
 175         },
 176
 177         selectChild: function(/*dijit._Widget|String*/ page, /*Boolean*/ animate){
 178                 // summary:
 179                 //              Show the given widget (which must be one of my children)
 180                 // page:
 181                 //              Reference to child widget or id of child widget
 182
 183                 page = dijit.byId(page);
 184
 185                 if(this.selectedChildWidget != page){
 186                         // Deselect old page and select new one
 187                         var d = this._transition(page, this.selectedChildWidget, animate);
 188                         this._set("selectedChildWidget", page);
 189                         dojo.publish(this.id+"-selectChild", [page]);
 190
 191                         if(this.persist){
 192                                 dojo.cookie(this.id + "_selectedChild", this.selectedChildWidget.id);
 193                         }
 194                 }
 195
 196                 return d;               // If child has an href, promise that fires when the child's href finishes loading
 197         },
 198
 199         _transition: function(/*dijit._Widget*/ newWidget, /*dijit._Widget*/ oldWidget, /*Boolean*/ animate){
 200                 // summary:
 201                 //              Hide the old widget and display the new widget.
 202                 //              Subclasses should override this.
 203                 // tags:
 204                 //              protected extension
 205                 if(oldWidget){
 206                         this._hideChild(oldWidget);
 207                 }
 208                 var d = this._showChild(newWidget);
 209
 210                 // Size the new widget, in case this is the first time it's being shown,
 211                 // or I have been resized since the last time it was shown.
 212                 // Note that page must be visible for resizing to work.
 213                 if(newWidget.resize){
 214                         if(this.doLayout){
 215                                 newWidget.resize(this._containerContentBox || this._contentBox);
 216                         }else{
 217                                 // the child should pick it's own size but we still need to call resize()
 218                                 // (with no arguments) to let the widget lay itself out
 219                                 newWidget.resize();
 220                         }
 221                 }
 222
 223                 return d;       // If child has an href, promise that fires when the child's href finishes loading
 224         },
 225
 226         _adjacent: function(/*Boolean*/ forward){
 227                 // summary:
 228                 //              Gets the next/previous child widget in this container from the current selection.
 229                 var children = this.getChildren();
 230                 var index = dojo.indexOf(children, this.selectedChildWidget);
 231                 index += forward ? 1 : children.length - 1;
 232                 return children[ index % children.length ]; // dijit._Widget
 233         },
 234
 235         forward: function(){
 236                 // summary:
 237                 //              Advance to next page.
 238                 return this.selectChild(this._adjacent(true), true);
 239         },
 240
 241         back: function(){
 242                 // summary:
 243                 //              Go back to previous page.
 244                 return this.selectChild(this._adjacent(false), true);
 245         },
 246
 247         _onKeyPress: function(e){
 248                 dojo.publish(this.id+"-containerKeyPress", [{ e: e, page: this}]);
 249         },
 250
 251         layout: function(){
 252                 // Implement _LayoutWidget.layout() virtual method.
 253                 if(this.doLayout && this.selectedChildWidget && this.selectedChildWidget.resize){
 254                         this.selectedChildWidget.resize(this._containerContentBox || this._contentBox);
 255                 }
 256         },
 257
 258         _showChild: function(/*dijit._Widget*/ page){
 259                 // summary:
 260                 //              Show the specified child by changing it's CSS, and call _onShow()/onShow() so
 261                 //              it can do any updates it needs regarding loading href's etc.
 262                 // returns:
 263                 //              Promise that fires when page has finished showing, or true if there's no href
 264                 var children = this.getChildren();
 265                 page.isFirstChild = (page == children[0]);
 266                 page.isLastChild = (page == children[children.length-1]);
 267                 page._set("selected", true);
 268
 269                 dojo.replaceClass(page.domNode, "dijitVisible", "dijitHidden");
 270
 271                 return page._onShow() || true;
 272         },
 273
 274         _hideChild: function(/*dijit._Widget*/ page){
 275                 // summary:
 276                 //              Hide the specified child by changing it's CSS, and call _onHide() so
 277                 //              it's notified.
 278                 page._set("selected", false);
 279                 dojo.replaceClass(page.domNode, "dijitHidden", "dijitVisible");
 280
 281                 page.onHide();
 282         },
 283
 284         closeChild: function(/*dijit._Widget*/ page){
 285                 // summary:
 286                 //              Callback when user clicks the [X] to remove a page.
 287                 //              If onClose() returns true then remove and destroy the child.
 288                 // tags:
 289                 //              private
 290                 var remove = page.onClose(this, page);
 291                 if(remove){
 292                         this.removeChild(page);
 293                         // makes sure we can clean up executeScripts in ContentPane onUnLoad
 294                         page.destroyRecursive();
 295                 }
 296         },
 297
 298         destroyDescendants: function(/*Boolean*/ preserveDom){
 299                 dojo.forEach(this.getChildren(), function(child){
 300                         this.removeChild(child);
 301                         child.destroyRecursive(preserveDom);
 302                 }, this);
 303         }
 304 });
 305
 306 // For back-compat, remove for 2.0
 307
 308
 309 // These arguments can be specified for the children of a StackContainer.
 310 // Since any widget can be specified as a StackContainer child, mix them
 311 // into the base widget class.  (This is a hack, but it's effective.)
 312 dojo.extend(dijit._Widget, {
 313         // selected: Boolean
 314         //              Parameter for children of `dijit.layout.StackContainer` or subclasses.
 315         //              Specifies that this widget should be the initially displayed pane.
 316         //              Note: to change the selected child use `dijit.layout.StackContainer.selectChild`
 317         selected: false,
 318
 319         // closable: Boolean
 320         //              Parameter for children of `dijit.layout.StackContainer` or subclasses.
 321         //              True if user can close (destroy) this child, such as (for example) clicking the X on the tab.
 322         closable: false,
 323
 324         // iconClass: String
 325         //              Parameter for children of `dijit.layout.StackContainer` or subclasses.
 326         //              CSS Class specifying icon to use in label associated with this pane.
 327         iconClass: "",
 328
 329         // showTitle: Boolean
 330         //              Parameter for children of `dijit.layout.StackContainer` or subclasses.
 331         //              When true, display title of this widget as tab label etc., rather than just using
 332         //              icon specified in iconClass
 333         showTitle: true
 334 });
 335
 336 }