integrating the latest montage version

Signed-off-by: Valerio Virgillito <valerio@motorola.com>

1 files changed, 145 insertions, 40 deletions

diff --git a/node_modules/montage/ui/native-control.js b/node_modules/montage/ui/native-control.js
index 7cf65bd5..8dad5408 100644
--- a/node_modules/montage/ui/native-control.js
+++ b/node_modules/montage/ui/native-control.js
@@ -4,23 +4,32 @@
  (c) Copyright 2011 Motorola Mobility, Inc.  All Rights Reserved.
  </copyright> */
 
+/**
+    @module "montage/ui/native-control"
+    @requires montage/core/core
+    @requires montage/ui/component
+*/
+
 var Montage = require("montage").Montage,
     Component = require("ui/component").Component;
 
-var isUndefined = function(obj) {
-   return (typeof obj === 'undefined');
-};
-
 
 /**
- * Base component for all native controls.
+    Base component for all native components, such as RadioButton and Checkbox.
+    @class module:montage/ui/native-control.NativeControl
+    @extends module:montage/ui/component.Component
  */
-var NativeControl = exports.NativeControl = Montage.create(Component, {
+var NativeControl = exports.NativeControl = Montage.create(Component, /** @lends module:montage/ui/native-control.NativeControl# */ {
 
     hasTemplate: {
         value: false
     },
 
+/**
+    The HTML element associated with the NativeControl instance.
+    @type {element}
+    @default null
+*/
     element: {
         serializable: true,
         enumerable: true,
@@ -37,18 +46,19 @@ var NativeControl = exports.NativeControl = Montage.create(Component, {
     },
 
 
-    /** Stores values that need to be set on the element. Cleared each draw
-     * cycle.
+    /**
+        Stores values that need to be set on the element. Cleared each draw cycle.
+        @private
      */
     _elementAttributeValues: {
         value: {},
         distinct: true
     },
 
-    /** Stores the descriptors of the properties that can be set on this
-     * control
+    /**
+        Stores the descriptors of the properties that can be set on this control
+        @private
      */
-
     _elementAttributeDescriptors: {
        value: {},
        distinct: true
@@ -59,7 +69,7 @@ var NativeControl = exports.NativeControl = Montage.create(Component, {
         value: function(attributeName) {
             var attributeDescriptor, instance = this;
             // walk up the prototype chain from the instance to NativeControl's prototype
-            while(instance && !isUndefined(instance._elementAttributeDescriptors)) {
+            while(instance && (typeof instance._elementAttributeDescriptors !== 'undefined')) {
                 attributeDescriptor = instance._elementAttributeDescriptors[attributeName];
                 if(attributeDescriptor) {
                     break;
@@ -67,28 +77,28 @@ var NativeControl = exports.NativeControl = Montage.create(Component, {
                     instance = Object.getPrototypeOf(instance);
                 }
             }
-
             return attributeDescriptor;
         }
     },
 
     /**
-    * Add a property to this Component. A default getter/setter is provided and a
-    * "_" property is created by default. Eg: if the property is "title", "_title" is
-    * automatically created and the value set to the value from the descriptor.
+    * Adds a property to the component with the specified name. This method is used internally by the framework convert a DOM element's standard attributes into bindable properties. It creates an accessor property (getter/setter) with the same name as the specified property, as well as a "backing" data property whose name is prepended with an underscore (_). The backing variable is assigned the value from the property descriptor. For example, if the name  "title" is passed as the first parameter, a "title" accessor property is created as well a data property named "_title".
+    * @function
+    * @param {String} name The property name to add.
+    * @param {Object} descriptor An object that specifies the new properties default attributes such as configurable and enumerable.
     */
     defineAttribute: {
         value: function(name, descriptor) {
             descriptor = descriptor || {};
+            var _name = '_' + name;
+
 
             var newDescriptor = {
-                configurable: isUndefined(descriptor.configurable) ? true: descriptor.configurable,
-                enumerable: isUndefined(descriptor.enumerable) ?  true: descriptor.enumerable,
-                serializable: isUndefined(descriptor.serializable) ? true: descriptor.serializable,
-                set: (function(name) {
+                configurable: (typeof descriptor.configurable == 'undefined') ? true: descriptor.configurable,
+                enumerable: (typeof descriptor.enumerable == 'undefined') ?  true: descriptor.enumerable,
+                serializable: (typeof descriptor.serializable == 'undefined') ? true: descriptor.serializable,
+                set: (function(name, attrName) {
                     return function(value) {
-                        var attrName = '_' + name;
-
                         var desc = this._getElementAttributeDescriptor(name, this);
 
                         // if requested dataType is boolean (eg: checked, readonly etc)
@@ -100,29 +110,31 @@ var NativeControl = exports.NativeControl = Montage.create(Component, {
                         // If the set value is different to the current one,
                         // update it here, and set it to be updated on the
                         // element in the next draw cycle.
-                        if(!isUndefined(value) && this[attrName] !== value) {
+                        if((typeof value !== 'undefined') && this[attrName] !== value) {
                             this[attrName] = value;
                             this._elementAttributeValues[name] = value;
                             this.needsDraw = true;
                         }
                     };
-                }(name)),
-                get: (function(name) {
+                }(name, _name)),
+                get: (function(name, attrName) {
                     return function() {
-                        return this['_' + name];
+                        return this[attrName];
                     };
-                }(name))
+                }(name, _name))
             };
 
             // Define _ property
-            Montage.defineProperty(this, '_' + name, {value: null});
+            Montage.defineProperty(this, _name, {value: null});
             // Define property getter and setter
             Montage.defineProperty(this, name, newDescriptor);
         }
     },
 
     /**
-    * Add the specified properties as properties of this Component
+    * Add the specified properties as properties of this component.
+    * @function
+    * @param {object} properties An object that contains the properties you want to add.
     */
     addAttributes: {
         value: function(properties) {
@@ -142,7 +154,7 @@ var NativeControl = exports.NativeControl = Montage.create(Component, {
 
                     // Only add the internal property, and getter and setter if
                     // they don't already exist.
-                    if(isUndefined(this[property])) {
+                    if(typeof this[property] == 'undefined') {
                         this.defineAttribute(property, descriptor);
                     }
                 }
@@ -150,6 +162,8 @@ var NativeControl = exports.NativeControl = Montage.create(Component, {
         }
     },
 
+// callbacks
+
     didSetElement: {
         value: function() {
             // The element is now ready, so we can read the attributes that
@@ -161,9 +175,9 @@ var NativeControl = exports.NativeControl = Montage.create(Component, {
                 name = attributes[i].name;
                 value = attributes[i].value;
 
-                if(isUndefined(this._elementAttributeValues[name])) {
+                if(typeof this._elementAttributeValues[name] == 'undefined') {
                     this._elementAttributeValues[name] = value;