prettify api doc comments + update README and HISTORY for widget-moda…

…lity, widget-autohide, widget-buttons, widget-position-align, and panel

build/widget-autohide/widget-autohide-debug.js

@@ -4,7 +4,7 @@ YUI.add('widget-autohide', function(Y) {
  * A widget-level extension that provides ability to hide widget when 
  * certain events occur.
  *
- * @module widget-modality
+ * @module widget-autohide
  * @author eferraiuolo, tilomitra
  * @since 3.4.0
  */
@@ -27,7 +27,8 @@ var WIDGET_AUTOHIDE    = 'widgetAutohide',
     getCN               = Y.ClassNameManager.getClassName;
 
 /**
- * Widget extension, which can be used to autohide the widget.
+ * The WidgetAutohide class provides the hideOn attribute which can
+ * be used to hide the widget when certain events occur.
  *
  * @class WidgetAutohide
  * @param {Object} config User configuration object
@@ -61,11 +62,11 @@ WidgetAutohide.ATTRS = {
      *
      * @description An array of objects corresponding to the nodes, events, and keycodes to hide the widget on.
      * The implementer can supply an array of objects, with each object having the following properties:
-     * eventName: (string, required): The eventName to listen to.
-     * node: (Y.Node, optional): The Y.Node that will fire the event (defaults to the boundingBox of the widget)
-     * keyCode: (string, optional): If listening for key events, specify the keyCode
-     * By default, this attribute consists of one object which will cause the widget to hide if the
-     * escape key is pressed.
+     * <p>eventName: (string, required): The eventName to listen to.</p>
+     * <p>node: (Y.Node, optional): The Y.Node that will fire the event (defaults to the boundingBox of the widget)</p>
+     * <p>keyCode: (string, optional): If listening for key events, specify the keyCode</p>
+     * <p>By default, this attribute consists of one object which will cause the widget to hide if the
+     * escape key is pressed.</p>
      */
     hideOn: {
         value: [

build/widget-autohide/widget-autohide.js

@@ -4,7 +4,7 @@ YUI.add('widget-autohide', function(Y) {
  * A widget-level extension that provides ability to hide widget when 
  * certain events occur.
  *
- * @module widget-modality
+ * @module widget-autohide
  * @author eferraiuolo, tilomitra
  * @since 3.4.0
  */
@@ -27,7 +27,8 @@ var WIDGET_AUTOHIDE    = 'widgetAutohide',
     getCN               = Y.ClassNameManager.getClassName;
 
 /**
- * Widget extension, which can be used to autohide the widget.
+ * The WidgetAutohide class provides the hideOn attribute which can
+ * be used to hide the widget when certain events occur.
  *
  * @class WidgetAutohide
  * @param {Object} config User configuration object
@@ -61,11 +62,11 @@ WidgetAutohide.ATTRS = {
      *
      * @description An array of objects corresponding to the nodes, events, and keycodes to hide the widget on.
      * The implementer can supply an array of objects, with each object having the following properties:
-     * eventName: (string, required): The eventName to listen to.
-     * node: (Y.Node, optional): The Y.Node that will fire the event (defaults to the boundingBox of the widget)
-     * keyCode: (string, optional): If listening for key events, specify the keyCode
-     * By default, this attribute consists of one object which will cause the widget to hide if the
-     * escape key is pressed.
+     * <p>eventName: (string, required): The eventName to listen to.</p>
+     * <p>node: (Y.Node, optional): The Y.Node that will fire the event (defaults to the boundingBox of the widget)</p>
+     * <p>keyCode: (string, optional): If listening for key events, specify the keyCode</p>
+     * <p>By default, this attribute consists of one object which will cause the widget to hide if the
+     * escape key is pressed.</p>
      */
     hideOn: {
         value: [

build/widget-buttons/widget-buttons-debug.js

@@ -55,13 +55,15 @@ WidgetButtons.ATTRS = {
                 type: "close"
             }
         ],
-     * @description An array of objects, with each object corresponding to a button that you want to be added to the widget. Each button can have upto 4 properties:
-     * type: {string} Use one of the default buttons provided by the WidgetButtons class. Set this to "close" if you want the 
-     * [x] at the top-right corner of the window. If this key has a value, then values for the remaining properties below don't need to be provided.
-     * value: {string} HTML string or text that should be shown on the button
-     * action: {function} The callback function that should be executed when the button is clicked.
-     * href: {string} (optional) The link to redirect to if the button is clicked> If not supplied, defaults to "#"
-     * section: {string || object} Whether the button should be placed in the header or footer. Represented as "header" or "footer"
+     * @description <p>An array of objects, with each object corresponding to a button that you want to be added to the widget. Each button can have upto 4 properties:</p>
+     *
+     * <p>type: {string} Use one of the default buttons provided by the WidgetButtons class. Set this to "close" if you want the 
+     * [x] at the top-right corner of the window. If this key has a value, then values for the remaining properties below don't need to be provided.</p>
+     *
+     * <p>value: {string} HTML string or text that should be shown on the button</p>
+     * <p>action: {function} The callback function that should be executed when the button is clicked.</p>
+     * <p>href: {string} (optional) The link to redirect to if the button is clicked> If not supplied, defaults to "#"</p>
+     * <p>section: {string || object} Whether the button should be placed in the header or footer. Represented as "header" or "footer"</p>
      */
     buttons: {
 
@@ -110,9 +112,9 @@ WidgetButtons.BUTTON_CLASS_NAMES = {
 
 
 /**
- * Object used to specify the HTML template for the buttons. Consists of the following properties 
- * defaultTemplate: Specifies the HTML markup for each button
- * wrapper: Specifies the HTML markup for the wrapper, which is a DOM Element that wraps around all the buttons
+ * <p>Object used to specify the HTML template for the buttons. Consists of the following properties</p>
+ * <p>defaultTemplate: Specifies the HTML markup for each button</p>
+ * <p>wrapper: Specifies the HTML markup for the wrapper, which is a DOM Element that wraps around all the buttons</p>
  * 
  * @property WidgetButtons.TEMPLATES
  * @static

build/widget-buttons/widget-buttons.js

@@ -55,13 +55,15 @@ WidgetButtons.ATTRS = {
                 type: "close"
             }
         ],
-     * @description An array of objects, with each object corresponding to a button that you want to be added to the widget. Each button can have upto 4 properties:
-     * type: {string} Use one of the default buttons provided by the WidgetButtons class. Set this to "close" if you want the 
-     * [x] at the top-right corner of the window. If this key has a value, then values for the remaining properties below don't need to be provided.
-     * value: {string} HTML string or text that should be shown on the button
-     * action: {function} The callback function that should be executed when the button is clicked.
-     * href: {string} (optional) The link to redirect to if the button is clicked> If not supplied, defaults to "#"
-     * section: {string || object} Whether the button should be placed in the header or footer. Represented as "header" or "footer"
+     * @description <p>An array of objects, with each object corresponding to a button that you want to be added to the widget. Each button can have upto 4 properties:</p>
+     *
+     * <p>type: {string} Use one of the default buttons provided by the WidgetButtons class. Set this to "close" if you want the 
+     * [x] at the top-right corner of the window. If this key has a value, then values for the remaining properties below don't need to be provided.</p>
+     *
+     * <p>value: {string} HTML string or text that should be shown on the button</p>
+     * <p>action: {function} The callback function that should be executed when the button is clicked.</p>
+     * <p>href: {string} (optional) The link to redirect to if the button is clicked> If not supplied, defaults to "#"</p>
+     * <p>section: {string || object} Whether the button should be placed in the header or footer. Represented as "header" or "footer"</p>
      */
     buttons: {
 
@@ -110,9 +112,9 @@ WidgetButtons.BUTTON_CLASS_NAMES = {
 
 
 /**
- * Object used to specify the HTML template for the buttons. Consists of the following properties 
- * defaultTemplate: Specifies the HTML markup for each button
- * wrapper: Specifies the HTML markup for the wrapper, which is a DOM Element that wraps around all the buttons
+ * <p>Object used to specify the HTML template for the buttons. Consists of the following properties</p>
+ * <p>defaultTemplate: Specifies the HTML markup for each button</p>
+ * <p>wrapper: Specifies the HTML markup for the wrapper, which is a DOM Element that wraps around all the buttons</p>
  * 
  * @property WidgetButtons.TEMPLATES
  * @static

build/widget-modality/widget-modality-debug.js

@@ -48,7 +48,7 @@ var WIDGET         = 'widget',
 
     /**
      * Widget extension, which can be used to add modality support to the base Widget class, 
-     * through the <a href="Base.html#method_build">Base.build</a> method.
+     * through the Base.create method.
      *
      * @class WidgetModality
      * @param {Object} config User configuration object
@@ -112,10 +112,10 @@ var WIDGET         = 'widget',
              *
              * @description An array of objects corresponding to the nodes and events that will trigger a re-focus back on the widget.
              * The implementer can supply an array of objects, with each object having the following properties:
-             * eventName: (string, required): The eventName to listen to.
-             * node: (Y.Node, optional): The Y.Node that will fire the event (defaults to the boundingBox of the widget)
-             * By default, this attribute consists of two objects which will cause the widget to re-focus if anything 
-             * outside the widget is clicked on or focussed upon.
+             * <p>eventName: (string, required): The eventName to listen to.</p>
+             * <p>node: (Y.Node, optional): The Y.Node that will fire the event (defaults to the boundingBox of the widget)</p>
+             * <p>By default, this attribute consists of two objects which will cause the widget to re-focus if anything 
+             * outside the widget is clicked on or focussed upon.</p>
              */
             focusOn: {
                 value: [

build/widget-modality/widget-modality.js

@@ -48,7 +48,7 @@ var WIDGET         = 'widget',
 
     /**
      * Widget extension, which can be used to add modality support to the base Widget class, 
-     * through the <a href="Base.html#method_build">Base.build</a> method.
+     * through the Base.create method.
      *
      * @class WidgetModality
      * @param {Object} config User configuration object
@@ -112,10 +112,10 @@ var WIDGET         = 'widget',
              *
              * @description An array of objects corresponding to the nodes and events that will trigger a re-focus back on the widget.
              * The implementer can supply an array of objects, with each object having the following properties:
-             * eventName: (string, required): The eventName to listen to.
-             * node: (Y.Node, optional): The Y.Node that will fire the event (defaults to the boundingBox of the widget)
-             * By default, this attribute consists of two objects which will cause the widget to re-focus if anything 
-             * outside the widget is clicked on or focussed upon.
+             * <p>eventName: (string, required): The eventName to listen to.</p>
+             * <p>node: (Y.Node, optional): The Y.Node that will fire the event (defaults to the boundingBox of the widget)</p>
+             * <p>By default, this attribute consists of two objects which will cause the widget to re-focus if anything 
+             * outside the widget is clicked on or focussed upon.</p>
              */
             focusOn: {
                 value: [

src/panel/HISTORY.md

@@ -1,5 +1,5 @@
 Panel
 ======
 
-3.4.0 - Initial Release
------------------------
+3.4.0PR3 - Initial Release
+--------------------------

src/panel/README.md

@@ -1,10 +1,13 @@
-Overlay
-=======
+Panel
+=====
 
-Overlay is a positionable and stackable widget, which also 
-provides support for the standard module format layout, 
-with a header, body and footer section. 
+Panel is a widget that simulates the behavior of an OS window.
+It is positionable, stackable, and provides support for the standard 
+module format layout, with a header, body and footer section. 
+The header and footer sections can support buttons with specific callback
+functions. The panel can be modal, and can be auto-focussed or hidden when
+certain UI interactions occur.
 
-The overlay is built by extending Widget and adding the 
-WidgetPosition, WidgetStack, WidgetPositionAlign, 
-WidgetPositionConstrain and WidgetStdMod extensions.
+The panel is built by extending Widget and adding the WidgetPosition, 
+WidgetStack, WidgetPositionAlign, WidgetPositionConstrain, WidgetStdMod,
+WidgetModality, WidgetAutohide, and WidgetButtons extensions.

src/widget-autohide/HISTORY.md

@@ -0,0 +1,7 @@
+3.4.0PR3
+--------
+
+  * Changed from a widget plugin to an extension
+
+3.4.0PR2 - Initial release
+--------------------------

src/widget-autohide/README.md

@@ -0,0 +1,8 @@
+WidgetAutohide
+==============
+
+WidgetAutohide is a widget-level extension that provides the ability
+to hide the widget (through the hide() method) when certain UI interactions
+occur, or certain events are fired. It reveals the "hideOn" attribute that 
+can be configured by a widget subclass implementing this extension.
+

src/widget-autohide/js/Widget-Autohide.js

@@ -2,7 +2,7 @@
  * A widget-level extension that provides ability to hide widget when 
  * certain events occur.
  *
- * @module widget-modality
+ * @module widget-autohide
  * @author eferraiuolo, tilomitra
  * @since 3.4.0
  */
@@ -25,7 +25,8 @@ var WIDGET_AUTOHIDE    = 'widgetAutohide',
     getCN               = Y.ClassNameManager.getClassName;
 
 /**
- * Widget extension, which can be used to autohide the widget.
+ * The WidgetAutohide class provides the hideOn attribute which can
+ * be used to hide the widget when certain events occur.
  *
  * @class WidgetAutohide
  * @param {Object} config User configuration object
@@ -59,11 +60,11 @@ WidgetAutohide.ATTRS = {
      *
      * @description An array of objects corresponding to the nodes, events, and keycodes to hide the widget on.
      * The implementer can supply an array of objects, with each object having the following properties:
-     * eventName: (string, required): The eventName to listen to.
-     * node: (Y.Node, optional): The Y.Node that will fire the event (defaults to the boundingBox of the widget)
-     * keyCode: (string, optional): If listening for key events, specify the keyCode
-     * By default, this attribute consists of one object which will cause the widget to hide if the
-     * escape key is pressed.
+     * <p>eventName: (string, required): The eventName to listen to.</p>
+     * <p>node: (Y.Node, optional): The Y.Node that will fire the event (defaults to the boundingBox of the widget)</p>
+     * <p>keyCode: (string, optional): If listening for key events, specify the keyCode</p>
+     * <p>By default, this attribute consists of one object which will cause the widget to hide if the
+     * escape key is pressed.</p>
      */
     hideOn: {
         value: [

src/widget-buttons/HISTORY.md

@@ -0,0 +1,2 @@
+3.4.0PR3 - Initial release
+--------------------------

src/widget-buttons/README.md

@@ -0,0 +1,11 @@
+WidgetButtons
+=============
+
+WidgetButtons is a widget-level extension that provides the ability
+to add buttons to the header and footer sections of a widget that
+implements the WidgetStdMod extension. 
+
+Each button can be configured and execute a callback function when clicked.
+WidgetButtons reveals the "buttons" attribute that can be configured 
+by a widget subclass implementing this extension.
+

src/widget-buttons/js/Widget-Buttons.js

@@ -53,13 +53,15 @@ WidgetButtons.ATTRS = {
                 type: "close"
             }
         ],
-     * @description An array of objects, with each object corresponding to a button that you want to be added to the widget. Each button can have upto 4 properties:
-     * type: {string} Use one of the default buttons provided by the WidgetButtons class. Set this to "close" if you want the 
-     * [x] at the top-right corner of the window. If this key has a value, then values for the remaining properties below don't need to be provided.
-     * value: {string} HTML string or text that should be shown on the button
-     * action: {function} The callback function that should be executed when the button is clicked.
-     * href: {string} (optional) The link to redirect to if the button is clicked> If not supplied, defaults to "#"
-     * section: {string || object} Whether the button should be placed in the header or footer. Represented as "header" or "footer"
+     * @description <p>An array of objects, with each object corresponding to a button that you want to be added to the widget. Each button can have upto 4 properties:</p>
+     *
+     * <p>type: {string} Use one of the default buttons provided by the WidgetButtons class. Set this to "close" if you want the 
+     * [x] at the top-right corner of the window. If this key has a value, then values for the remaining properties below don't need to be provided.</p>
+     *
+     * <p>value: {string} HTML string or text that should be shown on the button</p>
+     * <p>action: {function} The callback function that should be executed when the button is clicked.</p>
+     * <p>href: {string} (optional) The link to redirect to if the button is clicked> If not supplied, defaults to "#"</p>
+     * <p>section: {string || object} Whether the button should be placed in the header or footer. Represented as "header" or "footer"</p>
      */
     buttons: {
 
@@ -108,9 +110,9 @@ WidgetButtons.BUTTON_CLASS_NAMES = {
 
 
 /**
- * Object used to specify the HTML template for the buttons. Consists of the following properties 
- * defaultTemplate: Specifies the HTML markup for each button
- * wrapper: Specifies the HTML markup for the wrapper, which is a DOM Element that wraps around all the buttons
+ * <p>Object used to specify the HTML template for the buttons. Consists of the following properties</p>
+ * <p>defaultTemplate: Specifies the HTML markup for each button</p>
+ * <p>wrapper: Specifies the HTML markup for the wrapper, which is a DOM Element that wraps around all the buttons</p>
  * 
  * @property WidgetButtons.TEMPLATES
  * @static

src/widget-modality/HISTORY.md

@@ -0,0 +1,10 @@
+WidgetModality
+==============
+
+3.4.0PR3
+--------
+
+  * Changed from a widget plugin to an extension
+
+3.4.0PR2 - Initial release
+--------------------------

src/widget-modality/README.md

@@ -0,0 +1,7 @@
+WidgetModality
+==============
+
+WidgetModality is a widget-level extension that provides modality 
+and auto-focus support. It implements two new attributes "modal"
+and "focusOn" which can be configured by a widget subclass implementing
+this extension.