From e92fbf9001ddf5d78ee61c70f5fc725876e008b7 Mon Sep 17 00:00:00 2001 From: mikl <> Date: Tue, 6 May 2008 07:56:47 +0000 Subject: Updated jsdoc for some base classes and validation. --- framework/Web/Javascripts/source/prado/prado.js | 44 +- .../source/prado/scriptaculous-adapter.js | 453 ++++++++++-- .../source/prado/validator/validation3.js | 789 +++++++++++++++------ 3 files changed, 977 insertions(+), 309 deletions(-) (limited to 'framework/Web/Javascripts') diff --git a/framework/Web/Javascripts/source/prado/prado.js b/framework/Web/Javascripts/source/prado/prado.js index dff74f03..ae96bb6d 100644 --- a/framework/Web/Javascripts/source/prado/prado.js +++ b/framework/Web/Javascripts/source/prado/prado.js @@ -1,16 +1,42 @@ - +/** + * Prado base namespace + * @namespace Prado + */ var Prado = { + /** + * Version of Prado clientscripts + * @var Version + */ Version: '3.1', /** - * Returns browser information. Example - * + * Returns browser information. + *
 	 * var browser = Prado.Browser();
 	 * alert(browser.ie); //should ouput true if IE, false otherwise
-	 * 
-	 * @param ${parameter}
-	 * @return ${return}
+	 * 
+ * @function {object} ? + * @version 1.0 + * @returns browserinfo + * @... {string} agent - Reported user agent + * @... {string} ver - Reported agent version + * @... {0|1} dom - 1 for DOM browsers + * @... {0|1} ns4 - 1 for Netscape 4 + * @... {0|1} ns6 - 1 for Netscape 6 and Firefox + * @... {boolean} ie3 - true for IE 3 + * @... {0|1} ie5 - 1 for IE 5 + * @... {0|1} ie6 - 1 for IE 6 + * @... {0|1} ie4 - 1 for IE 4 + * @... {0|1} ie - 1 for IE 4-6 + * @... {0|1} hotjava - 1 for HotJava + * @... {0|1} ver3 - 1 for IE3 and HotJava + * @... {0|1} opera - 1 for Opera + * @... {boolean} opera7 - true for Opera 7 + * @... {0|1} operaOld - 1 for older Opera + * @... {0|1} bw - 1 for IE 4-6, Netscape 4&6, Firefox and Opera + * @... {boolean} mac - true for mac systems + * @... {static} Version - Version of returned structure (1.0) */ Browser : function() { @@ -37,6 +63,12 @@ var Prado = return info; }, + /** + * Import CSS from Url. + * @function ? + * @param doc - document DOM object + * @param css_file - Url to CSS file + */ ImportCss : function(doc, css_file) { if (Prado.Browser().ie) diff --git a/framework/Web/Javascripts/source/prado/scriptaculous-adapter.js b/framework/Web/Javascripts/source/prado/scriptaculous-adapter.js index 2905deec..5ea71364 100644 --- a/framework/Web/Javascripts/source/prado/scriptaculous-adapter.js +++ b/framework/Web/Javascripts/source/prado/scriptaculous-adapter.js @@ -1,6 +1,16 @@ - +/** + * Utilities and extions to Prototype/Scriptaculous + * @file scriptaculous-adapter.js + */ + +/** + * Extension to + * Prototype's Function + * @namespace Function + */ /** * Similar to bindAsEventLister, but takes additional arguments. + * @function Function.bindEvent */ Function.prototype.bindEvent = function() { @@ -12,12 +22,18 @@ Function.prototype.bindEvent = function() }; /** - * Creates a new function by copying function definition from + * Extension to + * Prototype's Class + * @namespace Class + */ + +/** + * Creates a new class by copying class definition from * the base and optional definition. - * @param function a base function to copy from. - * @param array additional definition - * @param function return a new function with definition from both - * base and definition. + * @function {Class} Class.extend + * @param {function} base - Base class to copy from. + * @param {optional Array} - Additional definition + * @returns Constructor for the extended class */ Class.extend = function(base, definition) { @@ -28,12 +44,12 @@ Class.extend = function(base, definition) return component; }; -/* - Base, version 1.0.2 - Copyright 2006, Dean Edwards - License: http://creativecommons.org/licenses/LGPL/2.1/ -*/ - +/** + * Base, version 1.0.2 + * Copyright 2006, Dean Edwards + * License: http://creativecommons.org/licenses/LGPL/2.1/ + * @class Base + */ var Base = function() { if (arguments.length) { if (this == window) { // cast an object to this class @@ -136,8 +152,18 @@ Base.implement = function(_interface) { }; /** - * Performs a post-back using javascript - * + * Performs a PostBack using javascript. + * @function Prado.PostBack + * @param event - Event that triggered this postback + * @param options - Postback options + * @... {string} FormID - Form that should be posted back + * @... {optional boolean} CausesValidation - Validate before PostBack if true + * @... {optional string} ValidationGroup - Group to Validate + * @... {optional string} ID - Validation ID + * @... {optional string} PostBackUrl - Postback URL + * @... {optional boolean} TrackFocus - Keep track of focused element if true + * @... {string} EventTarget - Id of element that triggered PostBack + * @... {string} EventParameter - EventParameter for PostBack */ Prado.PostBack = function(event,options) { @@ -177,12 +203,17 @@ Prado.PostBack = function(event,options) Event.fireEvent(form,"submit"); }; +/** + * Prado utilities to manipulate DOM elements. + * @object Prado.Element + */ Prado.Element = { /** * Set the value of a particular element. - * @param string element id - * @param string new element value. + * @function ? + * @param {string} element - Element id + * @param {string} value - New element value */ setValue : function(element, value) { @@ -191,6 +222,14 @@ Prado.Element = el.value = value; }, + /** + * Select options from a selectable element. + * @function ? + * @param {string} element - Element id + * @param {string} method - Name of any {@link Prado.Element.Selection} method + * @param {array|boolean|string} value - Values that should be selected + * @param {int} total - Number of elements + */ select : function(element, method, value, total) { var el = $(element); @@ -203,6 +242,11 @@ Prado.Element = } }, + /** + * Trigger a click event on a DOM element. + * @function ? + * @param {string} element - Element id + */ click : function(element) { var el = $(element); @@ -210,6 +254,12 @@ Prado.Element = Event.fireEvent(el,'click'); }, + /** + * Check if an DOM element is disabled. + * @function {boolean} ? + * @param {string} element - Element id + * @returns true if element is disabled + */ isDisabled : function(element) { if(!element.attributes['disabled']) //FF @@ -221,6 +271,13 @@ Prado.Element = return value == true; }, + /** + * Sets an attribute of a DOM element. + * @function ? + * @param {string} element - Element id + * @param {string} attribute - Name of attribute + * @param {string} value - Value of attribute + */ setAttribute : function(element, attribute, value) { var el = $(element); @@ -243,6 +300,13 @@ Prado.Element = el.setAttribute(attribute, value); }, + /** + * Sets the options for a select element. + * @function ? + * @param {string} element - Element id + * @param {array[]} options - Array of options, each an array of structure + * [ "optionText" , "optionValue" , "optionGroup" ] + */ setOptions : function(element, options) { var el = $(element); @@ -261,7 +325,11 @@ Prado.Element = }, /** - * Create opt-group options from an array of options[0]=text, options[1]=value, options[2]=group + * Create opt-group options from an array of options. + * @function {array} ? + * @param {array[]} options - Array of options, each an array of structure + * [ "optionText" , "optionValue" , "optionGroup" ] + * @returns Array of option DOM elements */ createOptions : function(options) { @@ -302,8 +370,9 @@ Prado.Element = }, /** - * A delayed focus on a particular element - * @param {element} element to apply focus() + * Set focus (delayed) on a particular element. + * @function ? + * @param {string} element - Element id */ focus : function(element) { @@ -313,6 +382,16 @@ Prado.Element = return false; }, + /** + * Replace a DOM element either with given content or + * with content from a CallBack response boundary + * using a replacement method. + * @function ? + * @param {string|element} element - DOM element or element id + * @param {string} method - Name of method to use for replacement + * @param {optional string} content - New content of element + * @param {optional string} boundary - Boundary of new content + */ replace : function(element, method, content, boundary) { if(boundary) @@ -332,6 +411,17 @@ Prado.Element = } }, + /** + * Extract content from a text by its boundary id. + * Boundaries have this form: + *
+	 * <!--123456-->Democontent<!--//123456-->
+	 * 
+ * @function {string} ? + * @param {string} text - Text that contains boundaries + * @param {string} boundary - Boundary id + * @returns Content from given boundaries + */ extractContent : function(text, boundary) { var tagStart = ''; @@ -353,11 +443,24 @@ Prado.Element = return null;*/ }, + /** + * Evaluate a javascript snippet from a string. + * @function ? + * @param {string} content - String containing the script + */ evaluateScript : function(content) { content.evalScripts(); }, + /** + * Set CSS style with Camelized keys. + * See Prototype's + * Element.setStyle for details. + * @function ? + * @param {string|element} element - DOM element or element id + * @param {object} styles - Object with style properties/values + */ setStyle : function (element, styles) { var s = {} @@ -370,8 +473,18 @@ Prado.Element = } }; +/** + * Utilities for selections. + * @object Prado.Element.Selection + */ Prado.Element.Selection = { + /** + * Check if an DOM element can be selected. + * @function {boolean} ? + * @param {element} el - DOM elemet + * @returns true if element is selectable + */ isSelectable : function(el) { if(el && el.type) @@ -389,6 +502,13 @@ Prado.Element.Selection = return false; }, + /** + * Set checked attribute of a checkbox or radiobutton to value. + * @function {boolean} ? + * @param {element} el - DOM element + * @param {boolean} value - New value of checked attribute + * @returns New value of checked attribute + */ inputValue : function(el, value) { switch(el.type.toLowerCase()) @@ -399,6 +519,14 @@ Prado.Element.Selection = } }, + /** + * Set selected attribute for elements options by value. + * If value is boolean, all elements options selected attribute will be set + * to value. Otherwhise all options that have the given value will be selected. + * @function ? + * @param {element[]} elements - Array of selectable DOM elements + * @param {boolean|string} value - Value of options that should be selected or boolean value of selection status + */ selectValue : function(elements, value) { elements.each(function(el) @@ -413,6 +541,12 @@ Prado.Element.Selection = }) }, + /** + * Set selected attribute for elements options by array of values. + * @function ? + * @param {element[]} elements - Array of selectable DOM elements + * @param {string[]} value - Array of values to select + */ selectValues : function(elements, values) { selection = this; @@ -422,6 +556,12 @@ Prado.Element.Selection = }) }, + /** + * Set selected attribute for elements options by option index. + * @function ? + * @param {element[]} elements - Array of selectable DOM elements + * @param {int} index - Index of option to select + */ selectIndex : function(elements, index) { elements.each(function(el) @@ -439,6 +579,11 @@ Prado.Element.Selection = }) }, + /** + * Set selected attribute to true for all elements options. + * @function ? + * @param {element[]} elements - Array of selectable DOM elements + */ selectAll : function(elements) { elements.each(function(el) @@ -453,6 +598,11 @@ Prado.Element.Selection = }) }, + /** + * Toggle the selected attribute for elements options. + * @function ? + * @param {element[]} elements - Array of selectable DOM elements + */ selectInvert : function(elements) { elements.each(function(el) @@ -467,6 +617,12 @@ Prado.Element.Selection = }) }, + /** + * Set selected attribute for elements options by array of option indices. + * @function ? + * @param {element[]} elements - Array of selectable DOM elements + * @param {int[]} indices - Array of option indices to select + */ selectIndices : function(elements, indices) { selection = this; @@ -476,6 +632,11 @@ Prado.Element.Selection = }) }, + /** + * Unselect elements. + * @function ? + * @param {element[]} elements - Array of selectable DOM elements + */ selectClear : function(elements) { elements.each(function(el) @@ -484,6 +645,13 @@ Prado.Element.Selection = }) }, + /** + * Get list elements of an element. + * @function {element[]} ? + * @param {element[]} elements - Array of selectable DOM elements + * @param {int} total - Number of list elements to return + * @returns Array of list DOM elements + */ getListElements : function(element, total) { elements = new Array(); @@ -496,6 +664,15 @@ Prado.Element.Selection = return elements; }, + /** + * Set checked attribute of elements by value. + * If value is boolean, checked attribute will be set to value. + * Otherwhise all elements that have the given value will be checked. + * @function ? + * @param {element[]} elements - Array of checkable DOM elements + * @param {boolean|String} value - Value that should be checked or boolean value of checked status + * + */ checkValue : function(elements, value) { elements.each(function(el) @@ -507,6 +684,13 @@ Prado.Element.Selection = }); }, + /** + * Set checked attribute of elements by array of values. + * @function ? + * @param {element[]} elements - Array of checkable DOM elements + * @param {string[]} values - Values that should be checked + * + */ checkValues : function(elements, values) { selection = this; @@ -516,6 +700,12 @@ Prado.Element.Selection = }) }, + /** + * Set checked attribute of elements by list index. + * @function ? + * @param {element[]} elements - Array of checkable DOM elements + * @param {int} index - Index of element to set checked + */ checkIndex : function(elements, index) { for(var i = 0; iScriptaculous' Builder + * @namespace Builder */ + Object.extend(Builder, { + /** + * Export scriptaculous builder utilities as window[functions] + * @function ? + */ exportTags:function() { var tags=["BUTTON","TT","PRE","H1","H2","H3","BR","CANVAS","HR","LABEL","TEXTAREA","FORM","STRONG","SELECT","OPTION","OPTGROUP","LEGEND","FIELDSET","P","UL","OL","LI","TD","TR","THEAD","TBODY","TFOOT","TABLE","TH","INPUT","SPAN","A","DIV","IMG", "CAPTION"]; @@ -608,20 +854,23 @@ Object.extend(Builder, }); } }); - Builder.exportTags(); /** - * @class String extensions + * Extension to + * Prototype's String + * @namespace String */ Object.extend(String.prototype, { + /** - * @param {String} "left" to pad the string on the left, "right" to pad right. - * @param {Number} minimum string length. - * @param {String} character(s) to pad - * @return {String} padded character(s) on the left or right to satisfy minimum string length + * Add padding to string + * @function {string} ? + * @param {string} side - "left" to pad the string on the left, "right" to pad right. + * @param {int} len - Minimum string length. + * @param {string} chr - Character(s) to pad + * @returns Padded string */ - pad : function(side, len, chr) { if (!chr) chr = ' '; var s = this; @@ -631,47 +880,59 @@ Object.extend(String.prototype, { }, /** - * @param {Number} minimum string length. - * @param {String} character(s) to pad - * @return {String} padded character(s) on the left to satisfy minimum string length + * Add left padding to string + * @function {string} ? + * @param {int} len - Minimum string length. + * @param {string} chr - Character(s) to pad + * @returns Padded string */ padLeft : function(len, chr) { return this.pad('left',len,chr); }, /** - * @param {Number} minimum string length. - * @param {String} character(s) to pad - * @return {String} padded character(s) on the right to satisfy minimum string length + * Add right padding to string + * @function {string} ? + * @param {int} len - Minimum string length. + * @param {string} chr - Character(s) to pad + * @returns Padded string */ padRight : function(len, chr) { return this.pad('right',len,chr); }, /** - * @param {Number} minimum string length. - * @return {String} append zeros to the left to satisfy minimum string length. + * Add zeros to the right of string + * @function {string} ? + * @param {int} len - Minimum string length. + * @returns Padded string */ zerofill : function(len) { return this.padLeft(len,'0'); }, /** - * @return {String} removed white spaces from both ends. + * Remove white spaces from both ends of string. + * @function {string} ? + * @returns Trimmed string */ trim : function() { return this.replace(/^\s+|\s+$/g,''); }, /** - * @return {String} removed white spaces from the left end. + * Remove white spaces from the left side of string. + * @function {string} ? + * @returns Trimmed string */ trimLeft : function() { return this.replace(/^\s+/,''); }, /** - * @return {String} removed white spaces from the right end. + * Remove white spaces from the right side of string. + * @function {string} ? + * @returns Trimmed string */ trimRight : function() { return this.replace(/\s+$/,''); @@ -679,9 +940,12 @@ Object.extend(String.prototype, { /** * Convert period separated function names into a function reference. - * e.g. "Prado.AJAX.Callback.Action.setValue".toFunction() will return - * the actual function Prado.AJAX.Callback.Action.setValue() - * @return {Function} the corresponding function represented by the string. + *
Example: + *
 
+	 * "Prado.AJAX.Callback.Action.setValue".toFunction()
+	 * 
+ * @function {function} ? + * @returns Reference to the corresponding function */ toFunction : function() { @@ -704,8 +968,9 @@ Object.extend(String.prototype, { }, /** - * Convert a string into integer, returns null if not integer. - * @return {Number} null if string does not represent an integer. + * Convert string into integer, returns null if not integer. + * @function {int} ? + * @returns Integer, null if string does not represent an integer. */ toInteger : function() { @@ -717,10 +982,11 @@ Object.extend(String.prototype, { }, /** - * Convert a string into a double/float value. Internationalization + * Convert string into a double/float value. Internationalization * is not supported - * @param {String} the decimal character - * @return {Double} null if string does not represent a float value + * @function {double} ? + * @param {string} decimalchar - Decimal character, defaults to "." + * @returns Double, null if string does not represent a float value */ toDouble : function(decimalchar) { @@ -741,15 +1007,16 @@ Object.extend(String.prototype, { }, /** - * Convert strings that represent a currency value (e.g. a float with grouping - * characters) to float. E.g. "10,000.50" will become "10000.50". The number + * Convert strings that represent a currency value to float. + * E.g. "10,000.50" will become "10000.50". The number * of dicimal digits, grouping and decimal characters can be specified. * The currency input format is very strict, null will be returned if * the pattern does not match. - * @param {String} the grouping character, default is "," - * @param {Number} number of decimal digits - * @param {String} the decimal character, default is "." - * @type {Double} the currency value as float. + * @function {double} ? + * @param {string} groupchar - Grouping character, defaults to "," + * @param {int} digits - Number of decimal digits + * @param {string} decimalchar - Decimal character, defaults to "." + * @returns Double, null if string does not represent a currency value */ toCurrency : function(groupchar, digits, decimalchar) { @@ -774,8 +1041,9 @@ Object.extend(String.prototype, { /** * Converts the string to a date by finding values that matches the * date format pattern. - * @param string date format pattern, e.g. MM-dd-yyyy - * @return {Date} the date extracted from the string + * @function {Date} ? + * @param {string} format - Date format pattern, e.g. MM-dd-yyyy + * @returns Date extracted from the string */ toDate : function(format) { @@ -784,7 +1052,9 @@ Object.extend(String.prototype, { }); /** - * @class Event extensions. + * Extension to + * Prototype's Event + * @namespace Event */ Object.extend(Event, { @@ -792,14 +1062,14 @@ Object.extend(Event, * Register a function to be executed when the page is loaded. * Note that the page is only loaded if all resources (e.g. images) * are loaded. - * - * Example: Show an alert box with message "Page Loaded!" when the + *
Example: + *
Show an alert box with message "Page Loaded!" when the * page finished loading. - * + *
 	 * Event.OnLoad(function(){ alert("Page Loaded!"); });
-	 * 
-	 *
-	 * @param {Function} function to execute when page is loaded.
+	 * 
+ * @function ? + * @param {function} fn - Function to execute when page is loaded. */ OnLoad : function (fn) { @@ -810,9 +1080,10 @@ Object.extend(Event, }, /** - * @param {Event} a keyboard event - * @return {Number} the Unicode character code generated by the key - * that was struck. + * Returns the unicode character generated by key. + * @param {event} e - Keyboard event + * @function {int} ? + * @returns Unicode character code generated by the key that was struck. */ keyCode : function(e) { @@ -820,9 +1091,10 @@ Object.extend(Event, }, /** - * @param {String} event type or event name. - * @return {Boolean} true if event type is of HTMLEvent, false - * otherwise + * Checks if an Event is of type HTMLEvent. + * @function {boolean} ? + * @param {string} type - Event type or event name. + * @return true if event is of type HTMLEvent. */ isHTMLEvent : function(type) { @@ -833,9 +1105,10 @@ Object.extend(Event, }, /** - * @param {String} event type or event name - * @return {Boolean} true if event type is of MouseEvent, - * false otherwise + * Checks if an Event is a mouse event. + * @function {boolean} ? + * @param {string} type - Event type or event name + * @return true if event is of type MouseEvent. */ isMouseEvent : function(type) { @@ -850,8 +1123,9 @@ Object.extend(Event, * dispatched, keyboard events or UIEvent can not be dispatch * via javascript consistently. * For the "submit" event the submit() method is called. - * @param {Object} element id string or a DOM element. - * @param {String} event type to dispatch. + * @function ? + * @param {element|string} element - Element id string or DOM element. + * @param {string} type - Event type to dispatch. */ fireEvent : function(element,type) { @@ -894,9 +1168,20 @@ Object.extend(Event, }); - +/** + * Extension to + * Prototype's Date + * @namespace Date + */ Object.extend(Date.prototype, { + /** + * SimpleFormat + * @function ? + * @param {string} format - TODO + * @param {string} data - TODO + * @returns TODO + */ SimpleFormat: function(format, data) { data = data || {}; @@ -926,6 +1211,11 @@ Object.extend(Date.prototype, return frm; }, + /** + * toISODate + * @function {string} ? + * @returns TODO + */ toISODate : function() { var y = this.getFullYear(); @@ -937,6 +1227,13 @@ Object.extend(Date.prototype, Object.extend(Date, { + /** + * SimpleParse + * @function ? + * @param {string} format - TODO + * @param {string} data - TODO + * @returns TODO + */ SimpleParse: function(value, format) { val=String(value); @@ -1046,8 +1343,18 @@ Object.extend(Date, } }); +/** + * Prado utilities for effects. + * @object Prado.Effect + */ Prado.Effect = { + /** + * Highlights an element + * @function ? + * @param {element} element - DOM element to highlight + * @param {optional object} options - Highlight options + */ Highlight : function (element,options) { new Effect.Highlight(element,options); diff --git a/framework/Web/Javascripts/source/prado/validator/validation3.js b/framework/Web/Javascripts/source/prado/validator/validation3.js index cb6d58c5..5f08b615 100644 --- a/framework/Web/Javascripts/source/prado/validator/validation3.js +++ b/framework/Web/Javascripts/source/prado/validator/validation3.js @@ -1,36 +1,41 @@ /** * Prado client-side javascript validation fascade. * - * There are 4 basic classes, Validation, ValidationManager, ValidationSummary - * and TBaseValidator, that interact together to perform validation. - * The Prado.Validation class co-ordinates together the + *

There are 4 basic classes: {@link Prado.Validation}, + * {@link Prado.ValidationManager}, {@link Prado.WebUI.TValidationSummary} + * and {@link Prado.WebUI.TBaseValidator}, + * that interact together to perform validation. + * The {@link Prado.Validation} class co-ordinates together the * validation scheme and is responsible for maintaining references - * to ValidationManagers. + * to ValidationManagers.

* - * The ValidationManager class is responsible for maintaining refereneces + *

The {@link Prado.ValidationManager} class is responsible for + * maintaining refereneces * to individual validators, validation summaries and their associated - * groupings. + * groupings.

* - * The ValidationSummary take cares of display the validator error messages - * as html output or an alert output. + *

The {@link Prado.WebUI.TValidationSummary} takes care of displaying + * the validator error messages + * as html output or an alert output.

* - * The TBaseValidator is the base class for all validators and contains - * methods to interact with the actual inputs, data type conversion. + *

The {@link Prado.WebUI.TBaseValidator} is the base class for all + * validators and contains + * methods to interact with the actual inputs, data type conversion.

* - * An instance of ValidationManager must be instantiated first for a - * particular form before instantiating validators and summaries. + *

An instance of {@link Prado.ValidationManager} must be instantiated first for a + * particular form before instantiating validators and summaries.

* - * Usage example: adding a required field to a text box input with - * ID "input1" in a form with ID "form1". - * - * - * - *
- *
- * - * - * - * - *
- *
- *
+ * </script> + * </div> + * </form> + * + * + * @module validation */ + Prado.Validation = Class.create(); /** - * A global validation manager. - * To validate the inputs of a particular form, call - * Prado.Validation.validate(formID, groupID) + * Global Validation Object. + * + *

To validate the inputs of a particular form, call + * {@link Prado.Validation.validate}(formID, groupID) * where formID is the HTML form ID, and the optional * groupID if present will only validate the validators - * in a particular group. + * in a particular group.

+ * + * @object {static} Prado.Validation */ Object.extend(Prado.Validation, { + /** + * Hash of registered validation managers + * @var managers + */ managers : {}, /** * Validate the validators (those that DO NOT - * belong to a particular group) the form specified by the + * belong to a particular group) in the form specified by the * formID parameter. If groupID is specified - * then only validators belonging to that group will be validated. - * @param string ID of the form to validate - * @param string ID of the group to validate. - * @param HTMLElement element that calls for validation + * only validators belonging to that group will be validated. + * @function {boolean} ? + * @param {string} formID - ID of the form to validate + * @param {string} groupID - ID of the ValidationGroup to validate. + * @param {element} invoker - DOM element that calls for validation + * @returns true if validation succeeded */ validate : function(formID, groupID, invoker) { @@ -90,7 +107,9 @@ Object.extend(Prado.Validation, }, /** - * @return string first form ID. + * Return first registered form + * @function {string} ? + * @returns ID of first form. */ getForm : function() { @@ -102,8 +121,10 @@ Object.extend(Prado.Validation, * Check if the validators are valid for a particular form (and group). * The validators states will not be changed. * The validate function should be called first. - * @param string ID of the form to validate - * @param string ID of the group to validate. + * @function {boolean} ? + * @param {string} formID - ID of the form to validate + * @param {string} groupID - ID of the ValiationGroup to validate. + * @return true if form is valid */ isValid : function(formID, groupID) { @@ -115,6 +136,9 @@ Object.extend(Prado.Validation, /** * Reset the validators for a given group. + * The group is searched in the first registered form. + * @function ? + * @param {string} groupID - ID of the ValidationGroup to reset. */ reset : function(groupID) { @@ -125,9 +149,10 @@ Object.extend(Prado.Validation, /** * Add a new validator to a particular form. - * @param string the form that the validator belongs. - * @param object a validator - * @return object the manager + * @function {ValidationManager} ? + * @param {string} formID - ID of the form that the validator belongs to. + * @param {TBaseValidator} validator - Validator object + * @return ValidationManager for the form */ addValidator : function(formID, validator) { @@ -140,9 +165,10 @@ Object.extend(Prado.Validation, /** * Add a new validation summary. - * @param string the form that the validation summary belongs. - * @param object a validation summary - * @return object manager + * @function {ValidationManager} ? + * @param {string} formID - ID of the form that the validation summary belongs to. + * @param {TValidationSummary} validator - TValidationSummary object + * @return ValidationManager for the form */ addSummary : function(formID, validator) { @@ -169,28 +195,48 @@ Object.extend(Prado.Validation, } }); -Prado.ValidationManager = Class.create(); /** - * Validation manager instances. Manages validators for a particular - * HTML form. The manager contains references to all the validators + * Manages validators for a particular HTML form. + * + *

The manager contains references to all the validators * summaries, and their groupings for a particular form. - * Generally, Prado.Validation methods should be called rather - * than calling directly the ValidationManager. + * Generally, {@link Prado.Validation} methods should be called rather + * than calling directly the ValidationManager.

+ * + * @class Prado.ValidationManager */ +Prado.ValidationManager = Class.create(); Prado.ValidationManager.prototype = { /** - * - * options['FormID']* The ID of HTML form to manage. - * + * Initialize ValidationManager. + * @constructor {protected} ? + * @param {object} options - Options for initialization + * @... {string} FormID - ID of form of this manager */ initialize : function(options) { if(!Prado.Validation.managers[options.FormID]) { - this.validators = []; // list of validators - this.summaries = []; // validation summaries - this.groups = []; // validation groups + /** + * List of validators + * @var {TBaseValidator[]} validators + */ + this.validators = []; + /** + * List of validation summaries + * @var {TValidationSummary[]} summaries + */ + this.summaries = []; + /** + * List of ValidationGroups + * @var {string[]} groups + */ + this.groups = []; + /** + * Options of this ValidationManager + * @var {object} options + */ this.options = {}; this.options = options; @@ -208,7 +254,10 @@ Prado.ValidationManager.prototype = }, /** - * Reset all validators in the given group (if group is null, validators without a group are used). + * Reset all validators in the given group. + * If group is null, validators without a group are used. + * @function ? + * @param {string} group - ID of ValidationGroup */ reset : function(group) { @@ -218,9 +267,11 @@ Prado.ValidationManager.prototype = /** * Validate the validators managed by this validation manager. - * @param string only validate validators belonging to a group (optional) - * @param HTMLElement element that calls for validation - * @return boolean true if all validators are valid, false otherwise. + * If group is set, only validate validators in that group. + * @function {boolean} ? + * @param {optional string} group - ID of ValidationGroup + * @param {element} source - DOM element that calls for validation + * @return true if all validators are valid, false otherwise. */ validate : function(group, source) { @@ -234,6 +285,8 @@ Prado.ValidationManager.prototype = /** * Focus on the first validator that is invalid and options.FocusOnError is true. + * @function ? + * @param {TBaseValidator[]} validators - Array of validator objects */ focusOnError : function(validators) { @@ -245,8 +298,14 @@ Prado.ValidationManager.prototype = }, /** - * @return array[0] validators belong to a group if group is given, otherwise validators - * not belongining to any group. array[1] the opposite of array[0]. + * Get all validators in a group and all other validators. + * Returns an array with two arrays of validators. The first + * array contains all validators in the group if group is given, + * otherwhise all validators without a group. The second array + * contains all other validators. + * @function {[ TBaseValidator[] , TBaseValidator[] ]} ? + * @param {optional string} group - ID of ValidationGroup + * @return Array with two arrays of validators. */ validatorPartition : function(group) { @@ -254,8 +313,13 @@ Prado.ValidationManager.prototype = }, /** - * @return array validatiors in a given group in first array and - * validators not belonging to the group in 2nd array. + * Get all validators in a group. + * Returns an array with two arrays of validators. The first + * array contains all validators in the group. The second array + * contains all other validators. + * @function {[ TBaseValidator[] , TBaseValidator[] ]} ? + * @param {optional string} groupID - ID of ValidationGroup + * @return Array with two arrays of validators. */ validatorsInGroup : function(groupID) { @@ -271,8 +335,13 @@ Prado.ValidationManager.prototype = }, /** - * @return array validators without any group in first array, and those - * with groups in 2nd array. + * Get all validators without a group. + * Returns an array with two arrays of validators. The first + * array contains all validators without a group. The second + * array contains all other validators. + * @function {[ TBaseValidator[] , TBaseValidator[] ]} ? + * @return Array with two arrays of validators: Array[0] has all + * validators without a group, Array[1] all other validators. */ validatorsWithoutGroup : function() { @@ -283,8 +352,12 @@ Prado.ValidationManager.prototype = }, /** - * Gets the state of all the validators, true if they are all valid. - * @return boolean true if the validators are valid. + * Get the state of validators. + * If group is set, only validators in that group are checked. + * Otherwhise only validators without a group are checked. + * @function {booelan} ? + * @param {optional string} group - ID of ValidationGroup + * @return true if all validators (in a group, if supplied) are valid. */ isValid : function(group) { @@ -293,7 +366,8 @@ Prado.ValidationManager.prototype = /** * Add a validator to this manager. - * @param Prado.WebUI.TBaseValidator a new validator + * @function ? + * @param {TBaseValidator} validator - Validator object */ addValidator : function(validator) { @@ -309,7 +383,8 @@ Prado.ValidationManager.prototype = /** * Add a validation summary. - * @param Prado.WebUI.TValidationSummary validation summary. + * @function ? + * @param {TValidationSummary} summary - Validation summary. */ addSummary : function(summary) { @@ -317,8 +392,11 @@ Prado.ValidationManager.prototype = }, /** - * Gets all validators that belong to a group or that the validator - * group is null and the validator validation was false. + * Gets validators with errors. + * If group is set, only validators in that group are returned. + * Otherwhise only validators without a group are returned. + * @function {TBaseValidator[]} ? + * @param {optional string} group - ID of ValidationGroup * @return array list of validators with error. */ getValidatorsWithError : function(group) @@ -331,7 +409,12 @@ Prado.ValidationManager.prototype = /** * Update the summary of a particular group. - * @param string validation group to update. + * If group is set, only the summary for validators in that + * group is updated. Otherwhise only the summary for validators + * without a group is updated. + * @function ? + * @param {optional string} group - ID of ValidationGroup + * @param {boolean} refresh - Wether the summary should be refreshed */ updateSummary : function(group, refresh) { @@ -349,44 +432,67 @@ Prado.ValidationManager.prototype = }; /** - * TValidationSummary displays a summary of validation errors inline on a Web page, + * TValidationSummary displays a summary of validation errors. + * + *

The summary is displayed inline on a Web page, * in a message box, or both. By default, a validation summary will collect * ErrorMessage of all failed validators on the page. If * ValidationGroup is not empty, only those validators who belong - * to the group will show their error messages in the summary. + * to the group will show their error messages in the summary.

* - * The summary can be displayed as a list, as a bulleted list, or as a single + *

The summary can be displayed as a list, as a bulleted list, or as a single * paragraph based on the DisplayMode option. - * The messages shown can be prefixed with HeaderText. + * The messages shown can be prefixed with HeaderText.

* - * The summary can be displayed on the Web page and in a message box by setting + *

The summary can be displayed on the Web page and in a message box by setting * the ShowSummary and ShowMessageBox - * options, respectively. + * options, respectively.

+ * + * @class Prado.WebUI.TValidationSummary */ Prado.WebUI.TValidationSummary = Class.create(); Prado.WebUI.TValidationSummary.prototype = { /** - * - * options['ID']* Validation summary ID, i.e., an HTML element ID - * options['FormID']* HTML form that this summary belongs. - * options['ShowMessageBox'] True to show the summary in an alert box. - * options['ShowSummary'] True to show the inline summary. - * options['HeaderText'] Summary header text - * options['DisplayMode'] Summary display style, 'BulletList', 'List', 'SingleParagraph' - * options['Refresh'] True to update the summary upon validator state change. - * options['ValidationGroup'] Validation summary group - * options['Display'] Display mode, 'None', 'Fixed', 'Dynamic'. - * options['ScrollToSummary'] True to scroll to the validation summary upon refresh. - * + * Initialize TValidationSummary. + * @constructor {protected} ? + * @param {object} options - Options for initialization + * @... {string} ID - ID of validation summary element + * @... {string} FormID - ID of form of this manager + * @... {optional string} ValidationGroup - ID of ValidationGroup. + * @... {optional boolean} ShowMessageBox - true to show the summary in an alert box. + * @... {optional boolean} ShowSummary - true to show the inline summary. + * @... {optional string} HeaderText - Summary header text + * @... {optional string} DisplayMode - Summary display style, 'BulletList', 'List', 'SingleParagraph' + * @... {optional boolean} Refresh - true to update the summary upon validator state change. + * @... {optional string} Display - Display mode, 'None', 'Fixed', 'Dynamic'. + * @... {optional boolean} ScrollToSummary - true to scroll to the validation summary upon refresh. + * @... {optional function} OnHideSummary - Called on hide event. + * @... {optional function} OnShowSummary - Called on show event. */ initialize : function(options) { + /** + * ValidationManager options + * @var {object} options + */ this.options = options; + /** + * ValidationGroup + * @var {string} group + */ this.group = options.ValidationGroup; + /** + * Summary DOM element + * @var {element} messages + */ this.messages = $(options.ID); if(this.messages) { + /** + * Current visibility state of summary + * @var {boolean} visible + */ this.visible = this.messages.style.visibility != "hidden" this.visible = this.visible && this.messages.style.display != "none"; Prado.Validation.addSummary(options.FormID, this); @@ -394,10 +500,10 @@ Prado.WebUI.TValidationSummary.prototype = }, /** - * Update the validation summary to show the error message from - * validators that failed validation. - * @param array list of validators that failed validation. - * @param boolean update the summary; + * Update the validation summary. + * @function ? + * @param {TBaseValidator[]} validators - List of validators that failed validation. + * @param {boolean} update - true if visible summary should be updated */ updateSummary : function(validators, update) { @@ -433,6 +539,8 @@ Prado.WebUI.TValidationSummary.prototype = /** * Display the validator error messages as inline HTML. + * @function ? + * @param {string[]} messages - Array of error messages. */ updateHTMLMessages : function(messages) { @@ -443,6 +551,8 @@ Prado.WebUI.TValidationSummary.prototype = /** * Display the validator error messages as an alert box. + * @function ? + * @param {string[]} messages - Array of error messages. */ alertMessages : function(messages) { @@ -451,7 +561,10 @@ Prado.WebUI.TValidationSummary.prototype = }, /** - * @return array list of validator error messages. + * Get messages from validators. + * @function {string[]} ? + * @param {TBaseValidator[]} validators - Array of validators. + * @return Array of validator error messages. */ getMessages : function(validators) { @@ -466,7 +579,9 @@ Prado.WebUI.TValidationSummary.prototype = }, /** - * Hides the validation summary. + * Hide the validation summary. + * @function ? + * @param {TBaseValidator[]} validators - Array of validators. */ hideSummary : function(validators) { if(typeof(this.options.OnHideSummary) == "function") @@ -485,6 +600,8 @@ Prado.WebUI.TValidationSummary.prototype = /** * Shows the validation summary. + * @function ? + * @param {TBaseValidator[]} validators - Array of validators. */ showSummary : function(validators) { @@ -498,8 +615,14 @@ Prado.WebUI.TValidationSummary.prototype = /** * Return the format parameters for the summary. - * @param string format type, "List", "SingleParagraph" or "BulletList" - * @type array formatting parameters + * @function {object} ? + * @param {string} type - Format type: "List", "SingleParagraph" or "BulletList" (default) + * @return Object with format parameters: + * @... {string} header - Text for header + * @... {string} first - Text to prepend before message list + * @... {string} pre - Text to prepend before each message + * @... {string} post - Text to append after each message + * @... {string} first - Text to append after message list */ formats : function(type) { @@ -517,8 +640,9 @@ Prado.WebUI.TValidationSummary.prototype = /** * Format the message summary. - * @param array list of error messages. - * @type string formatted message + * @function {string} ? + * @param {string[]} messages - Array of error messages. + * @return Formatted message */ formatSummary : function(messages) { @@ -536,8 +660,9 @@ Prado.WebUI.TValidationSummary.prototype = }, /** * Format the message alert box. - * @param array a list of error messages. - * @type string format message for alert. + * @function {string} ? + * @param {string[]} messages - Array of error messages. + * @return Formatted message for alert */ formatMessageBox : function(messages) { @@ -565,31 +690,35 @@ Prado.WebUI.TValidationSummary.prototype = /** * TBaseValidator serves as the base class for validator controls. * - * Validation is performed when a postback control, such as a TButton, + *

Validation is performed when a postback control, such as a TButton, * a TLinkButton or a TTextBox (under AutoPostBack mode) is submitting * the page and its CausesValidation option is true. * The input control to be validated is specified by ControlToValidate - * option. + * option.

+ * + * @class Prado.WebUI.TBaseValidator */ Prado.WebUI.TBaseValidator = Class.create(); Prado.WebUI.TBaseValidator.prototype = { /** - * - * options['ID']* Validator ID, e.g. span with message - * options['FormID']* HTML form that the validator belongs - * options['ControlToValidate']*HTML form input to validate - * options['Display'] Display mode, 'None', 'Fixed', 'Dynamic' - * options['ErrorMessage'] Validation error message - * options['FocusOnError'] True to focus on validation error - * options['FocusElementID'] Element to focus on error - * options['ValidationGroup'] Validation group - * options['ControlCssClass'] Css class to use on the input upon error - * options['OnValidate'] Function to call immediately after validation - * options['OnValidationSuccess'] Function to call upon after successful validation - * options['OnValidationError'] Function to call upon after error in validation. - * options['ObserveChanges'] True to observe changes in input - * + * Initialize TBaseValidator. + * @constructor {protected} ? + * @param {object} options - Options for initialization. + * @... {string} ID - ID of validation summary element. + * @... {string} FormID - ID of form of this manager. + * @... {string} ControlToValidate - ID of control to validate. + * @... {optional string} InitialValue - Initial value of control to validate. + * @... {optional string} ErrorMessage - Validation error message. + * @... {optional string} ValidationGroup - ID of ValidationGroup. + * @... {optional string} Display - Display mode, 'None', 'Fixed', 'Dynamic'. + * @... {optional boolean} ObserveChanges - True to observer changes of ControlToValidate + * @... {optional boolean} FocusOnError - True to focus on validation error. + * @... {optional string} FocusElementID - ID of element to focus on error. + * @... {optional string} ControlCssClass - Css class to use on ControlToValidate on error + * @... {optional function} OnValidate - Called immediately after validation. + * @... {optional function} OnValidationSuccess - Called after successful validation. + * @... {optional function} OnValidationError - Called after validation error. */ initialize : function(options) { @@ -598,26 +727,68 @@ Prado.WebUI.TBaseValidator.prototype = options.OnError = options.OnError || Prototype.emptyFunction; */ + /** + * Wether the validator is enabled (default true) + * @var {boolean} enabled + */ this.enabled = true; + /** + * Visibility state of validator(default false) + * @var {boolean} visible + */ this.visible = false; + /** + * State of validation (default true) + * @var {boolean} isValid + */ this.isValid = true; + /** + * DOM elements that are observed by this validator + * @var {private element[]} _isObserving + */ this._isObserving = {}; + /** + * ValidationGroup + * @var {string} group + */ this.group = null; + /** + * Wether a request was dispatched (default false) + * @var {boolean} requestDispatched + */ this.requestDispatched = false; + /** + * Validator options + * @var {object} options + */ this.options = options; + /** + * DOM element of control to validate + * @var {element} control + */ this.control = $(options.ControlToValidate); + /** + * DOM element of validator + * @var {element} message + */ this.message = $(options.ID); if(this.control && this.message) { this.group = options.ValidationGroup; + /** + * ValidationManager of this validator + * @var {ValidationManager} manager + */ this.manager = Prado.Validation.addValidator(options.FormID, this); } }, /** - * @return string validation error message. + * Get error message. + * @function {string} ? + * @return Validation error message. */ getErrorMessage : function() { @@ -625,11 +796,12 @@ Prado.WebUI.TBaseValidator.prototype = }, /** - * Update the validator span, input CSS class, and focus particular - * element. Updating the validator control will set the validator + * Update the validator. + * Updating the validator control will set the validator * visible property to true. + * @function ? */ - updateControl: function(focus) + updateControl: function() { this.refreshControlAndMessage(); @@ -639,6 +811,10 @@ Prado.WebUI.TBaseValidator.prototype = this.visible = true; }, + /** + * Updates span and input CSS class. + * @function ? + */ refreshControlAndMessage : function() { this.visible = true; @@ -656,10 +832,12 @@ Prado.WebUI.TBaseValidator.prototype = }, /** + * Update CSS class of control to validate. * Add a css class to the input control if validator is invalid, * removes the css class if valid. - * @param object html control element - * @param boolean true to remove the css class, false to add. + * @function ? + * @param {element} control - DOM element of control to validate + * @param {boolean} valid - Validation state of control */ updateControlCssClass : function(control, valid) { @@ -683,7 +861,8 @@ Prado.WebUI.TBaseValidator.prototype = }, /** - * Hides the validator messages and remove any validation changes. + * Hide the validator messages and remove any validation changes. + * @function ? */ hide : function() { @@ -692,7 +871,9 @@ Prado.WebUI.TBaseValidator.prototype = }, /** + * Reset validator. * Sets isValid = true and updates the validator display. + * @function ? */ reset : function() { @@ -701,10 +882,12 @@ Prado.WebUI.TBaseValidator.prototype = }, /** + * Perform validation. * Calls evaluateIsValid() function to set the value of isValid property. * Triggers onValidate event and onSuccess or onError event. - * @param HTMLElement element that calls for validation - * @return boolean true if valid. + * @function {boolean} ? + * @param {element} invoker - DOM element that triggered validation + * @return Valdation state of control. */ validate : function(invoker) { @@ -736,7 +919,9 @@ Prado.WebUI.TBaseValidator.prototype = }, /** - * Updates the validation messages, update the control to be validated. + * Update validation display. + * Updates the validation messages and the control to validate. + * @param {element} invoker - DOM element that triggered validation */ updateValidationDisplay : function(invoker) { @@ -769,9 +954,11 @@ Prado.WebUI.TBaseValidator.prototype = }, /** - * Observe changes to the control input, re-validate upon change. If - * the validator is not visible, no updates are propagated. - * @param HTMLElement element that calls for validation + * Add control to observe for changes. + * Re-validates upon change. If the validator is not visible, + * no updates are propagated. + * @function ? + * @param {element} control - DOM element of control to observe */ observeChanges : function(control) { @@ -797,7 +984,10 @@ Prado.WebUI.TBaseValidator.prototype = }, /** - * @return string trims the string value, empty string if value is not string. + * Trim a string. + * @function {string} ? + * @param {string} value - String that should be trimmed. + * @return Trimmed string, empty string if value is not string. */ trim : function(value) { @@ -806,9 +996,10 @@ Prado.WebUI.TBaseValidator.prototype = /** * Convert the value to a specific data type. - * @param {string} the data type, "Integer", "Double", "Date" or "String" - * @param {string} the value to convert. - * @type {mixed|null} the converted data value. + * @function {mixed|null} ? + * @param {string} dataType - Data type: "Integer", "Double", "Date" or "String" + * @param {mixed} value - Value to convert. + * @return Converted data value. */ convert : function(dataType, value) { @@ -840,9 +1031,12 @@ Prado.WebUI.TBaseValidator.prototype = }, /** + * Get value that should be validated. * The ControlType property comes from TBaseValidator::getClientControlClass() * Be sure to update the TBaseValidator::$_clientClass if new cases are added. - * @return mixed control value to validate + * @function {mixed} ? + * @param {optional element} control - Control to get value from (default: this.control) + * @return Control value to validate */ getValidationValue : function(control) { @@ -884,6 +1078,11 @@ Prado.WebUI.TBaseValidator.prototype = } }, + /** + * Get value of radio button group + * @function {string} ? + * @return Value of a radio button group + */ getRadioButtonGroupValue : function() { name = this.control.name; @@ -898,6 +1097,7 @@ Prado.WebUI.TBaseValidator.prototype = /** * Observe changes in the drop down list date picker, IE only. + * @function ? */ observeDatePickerChanges : function() { @@ -911,9 +1111,13 @@ Prado.WebUI.TBaseValidator.prototype = }, /** - * Gets numeber selections and their values. - * @return object returns selected values in values property - * and number of selections in checks property. + * Gets number of selections and their values. + * @function {object} ? + * @param {element[]} elements - Elements to get values from. + * @param {string} initialValue - Initial value of element + * @return Object: + * @... {mixed[]} values - Array of selected values + * @... {int} checks - Number of selections */ getSelectedValuesAndChecks : function(elements, initialValue) { @@ -932,9 +1136,12 @@ Prado.WebUI.TBaseValidator.prototype = }, /** + * Get list elements of TCheckBoxList or TListBox. * Gets an array of the list control item input elements, for TCheckBoxList - * checkbox inputs are returned, for TListBox HTML option elements are returned. - * @return array list control option elements. + * checkbox input elements are returned, for TListBox HTML option elements + * are returned. + * @function {element[]} ? + * @return Array of list control option DOM elements. */ getListElements : function() { @@ -964,7 +1171,10 @@ Prado.WebUI.TBaseValidator.prototype = }, /** - * @return boolean true if element is of checkbox or radio type. + * Check if control is of type checkbox or radio. + * @function {boolean} ? + * @param {element} element - DOM element to check. + * @return True if element is of checkbox or radio type. */ isCheckBoxType : function(element) { @@ -977,7 +1187,9 @@ Prado.WebUI.TBaseValidator.prototype = }, /** - * @return boolean true if control to validate is of some of the TListControl type. + * Check if control to validate is a TListControl type. + * @function {boolean} ? + * @return True if control to validate is a TListControl type. */ isListControlType : function() { @@ -986,7 +1198,9 @@ Prado.WebUI.TBaseValidator.prototype = }, /** - * @return string gets the first selected list value, initial value if none found. + * Get first selected list value or initial value if none found. + * @function {string} ? + * @return First selected list value, initial value if none found. */ getFirstSelectedListValue : function() { @@ -1002,16 +1216,19 @@ Prado.WebUI.TBaseValidator.prototype = /** * TRequiredFieldValidator makes the associated input control a required field. - * The input control fails validation if its value does not change from - * the InitialValue option upon losing focus. - * - * options['InitialValue'] Validation fails if control input equals initial value. - * + * + *

The input control fails validation if its value does not change from + * the InitialValue option upon losing focus.

+ * + * @class Prado.WebUI.TRequiredFieldValidator + * @extends Prado.WebUI.TBaseValidator */ Prado.WebUI.TRequiredFieldValidator = Class.extend(Prado.WebUI.TBaseValidator, { /** - * @return boolean true if the input value is not empty nor equal to the initial value. + * Evaluate validation state + * @function {boolean} ? + * @return True if the input value is not empty nor equal to the initial value. */ evaluateIsValid : function() { @@ -1025,37 +1242,48 @@ Prado.WebUI.TRequiredFieldValidator = Class.extend(Prado.WebUI.TBaseValidator, /** * TCompareValidator compares the value entered by the user into an input * control with the value entered into another input control or a constant value. - * To compare the associated input control with another input control, + * + *

To compare the associated input control with another input control, * set the ControlToCompare option to the ID path * of the control to compare with. To compare the associated input control with * a constant value, specify the constant value to compare with by setting the - * ValueToCompare option. + * ValueToCompare option.

* - * The DataType property is used to specify the data type + *

The DataType property is used to specify the data type * of both comparison values. Both values are automatically converted to this data * type before the comparison operation is performed. The following value types are supported: * - Integer A 32-bit signed integer data type. * - Float A double-precision floating point number data type. - * - Date A date data type. The format can be by the DateFormat option. - * - String A string data type. + * - Date A date data type. The format can be set by the DateFormat option. + * - String A string data type.

* * Use the Operator property to specify the type of comparison * to perform. Valid operators include Equal, NotEqual, GreaterThan, GreaterThanEqual, * LessThan and LessThanEqual. - * - * options['ControlToCompare'] - * options['ValueToCompare'] - * options['Operator'] - * options['Type'] - * options['DateFormat'] - * + * + * @class Prado.WebUI.TCompareValidator + * @extends Prado.WebUI.TBaseValidator */ Prado.WebUI.TCompareValidator = Class.extend(Prado.WebUI.TBaseValidator, { + /** + * Additional constructor options. + * @constructor initialize + * @param {object} options - Additional constructor options: + * @... {string} ControlToCompare - Control with compare value. + * @... {string} ValueToCompare - Value to compare. + * @... {string} Operator - Type of comparison: "Equal", "NotEqual", "GreaterThan", + * "GreaterThanEqual", "LessThan" or "LessThanEqual". + * @... {string} Type - Type of values: "Integer", "Float", "Date" or "String". + * @... {string} DateFormat - Valid date format. + */ + //_observingComparee : false, /** - * Compares the input to another input or a given value. + * Evaluate validation state + * @function {boolean} ? + * @return True if comparision condition is met. */ evaluateIsValid : function() { @@ -1081,11 +1309,15 @@ Prado.WebUI.TCompareValidator = Class.extend(Prado.WebUI.TBaseValidator, }, /** - * Compares two values, their values are casted to type defined + * Compare two operands. + * The operand values are casted to type defined * by DataType option. False is returned if the first * operand converts to null. Returns true if the second operand * converts to null. The comparision is done based on the * Operator option. + * @function ? + * @param {mixed} operand1 - First operand. + * @param {mixed} operand2 - Second operand. */ compare : function(operand1, operand2) { @@ -1116,32 +1348,43 @@ Prado.WebUI.TCompareValidator = Class.extend(Prado.WebUI.TBaseValidator, * TCustomValidator performs user-defined client-side validation on an * input component. * - * To create a client-side validation function, add the client-side + *

To create a client-side validation function, add the client-side * validation javascript function to the page template. - * The function should have the following signature: - * - * - * - * Use the ClientValidationFunction option + * </script> + * + * + *

Use the ClientValidationFunction option * to specify the name of the client-side validation script function associated - * with the TCustomValidator. - * - * options['ClientValidationFunction'] custom validation function. - * + * with the TCustomValidator.

+ * + * @class Prado.WebUI.TCustomValidator + * @extends Prado.WebUI.TBaseValidator */ Prado.WebUI.TCustomValidator = Class.extend(Prado.WebUI.TBaseValidator, { /** - * Calls custom validation function. + * Additional constructor options. + * @constructor initialize + * @param {object} options - Additional constructor options: + * @... {function} ClientValidationFunction - Custom validation function. + */ + + /** + * Evaluate validation state + * Returns true if no valid custom validation function is present. + * @function {boolean} ? + * @return True if custom validation returned true. */ evaluateIsValid : function() { @@ -1158,10 +1401,21 @@ Prado.WebUI.TCustomValidator = Class.extend(Prado.WebUI.TBaseValidator, /** * Uses callback request to perform validation. + * + * @class Prado.WebUI.TActiveCustomValidator + * @extends Prado.WebUI.TBaseValidator */ Prado.WebUI.TActiveCustomValidator = Class.extend(Prado.WebUI.TBaseValidator, { + /** + * Value to validate + * @var {string} validatingValue + */ validatingValue : null, + /** + * DOM element that triggered validation + * @var {element} invoker + */ invoker : null, /** @@ -1169,8 +1423,9 @@ Prado.WebUI.TActiveCustomValidator = Class.extend(Prado.WebUI.TBaseValidator, * re-validate after the callback has returned * Calls evaluateIsValid() function to set the value of isValid property. * Triggers onValidate event and onSuccess or onError event. - * @param HTMLElement element that calls for validation - * @return boolean true if valid. + * @function {boolean} ? + * @param {element} invoker - DOM element that triggered validation + * @return True if valid. */ validate : function(invoker) { @@ -1207,7 +1462,9 @@ Prado.WebUI.TActiveCustomValidator = Class.extend(Prado.WebUI.TBaseValidator, }, /** - * Calls custom validation function. + * Send CallBack to start serverside validation. + * @function {boolean} ? + * @return True if valid. */ evaluateIsValid : function() { @@ -1229,6 +1486,12 @@ Prado.WebUI.TActiveCustomValidator = Class.extend(Prado.WebUI.TBaseValidator, return this.isValid; }, + /** + * Parse CallBack response data on success. + * @function ? + * @param {CallbackRequest} request - CallbackRequest. + * @param {string} data - Response data. + */ callbackOnSuccess : function(request, data) { this.isValid = data; @@ -1245,6 +1508,12 @@ Prado.WebUI.TActiveCustomValidator = Class.extend(Prado.WebUI.TBaseValidator, }, + /** + * Handle callback failure. + * @function ? + * @param {CallbackRequest} request - CallbackRequest. + * @param {string} data - Response data. + */ callbackOnFailure : function(request, data) { this.requestDispatched = false; @@ -1256,30 +1525,42 @@ Prado.WebUI.TActiveCustomValidator = Class.extend(Prado.WebUI.TBaseValidator, /** * TRangeValidator tests whether an input value is within a specified range. * - * TRangeValidator uses three key properties to perform its validation. - * The MinValue and MaxValue options specify the minimum - * and maximum values of the valid range. The DataType option is + *

TRangeValidator uses three key properties to perform its validation.

+ * + *

The MinValue and MaxValue options specify the minimum + * and maximum values of the valid range.

+ *

The DataType option is * used to specify the data type of the value and the minimum and maximum range values. - * These values are converted to this data type before the validation - * operation is performed. The following value types are supported: - * - Integer A 32-bit signed integer data type. - * - Float A double-precision floating point number data type. - * - Date A date data type. The date format can be specified by + * The values are converted to this data type before the validation + * operation is performed. The following value types are supported:

+ * + * - Integer A 32-bit signed integer data type.
+ * - Float A double-precision floating point number data type.
+ * - Date A date data type. The date format can be specified by
* setting DateFormat option, which must be recognizable * by Date.SimpleParse javascript function. * - String A string data type. - * - * options['MinValue'] Minimum range value - * options['MaxValue'] Maximum range value - * options['DataType'] Value data type - * options['DateFormat'] Date format for date data type. - * + * + * @class Prado.WebUI.TRangeValidator + * @extends Prado.WebUI.TBaseValidator */ Prado.WebUI.TRangeValidator = Class.extend(Prado.WebUI.TBaseValidator, { /** - * Compares the input value with a minimum and/or maximum value. - * @return boolean true if the value is empty, returns false if conversion fails. + * Additional constructor options. + * @constructor initialize + * @param {object} options - Additional constructor options: + * @... {string} MinValue - Minimum range value + * @... {string} MaxValue - Maximum range value + * @... {string} DataType - Value data type: "Integer", "Float", "Date" or "String" + * @... {string} DateFormat - Date format for data type Date. + */ + + /** + * Evaluate validation state + * @function {boolean} ? + * @return True if value is in range or value is empty, + * false otherwhise and when type conversion failed. */ evaluateIsValid : function() { @@ -1318,14 +1599,23 @@ Prado.WebUI.TRangeValidator = Class.extend(Prado.WebUI.TBaseValidator, /** * TRegularExpressionValidator validates whether the value of an associated * input component matches the pattern specified by a regular expression. - * - * options['ValidationExpression'] regular expression to match against. - * + * + * @class Prado.WebUI.TRegularExpressionValidator + * @extends Prado.WebUI.TBaseValidator */ Prado.WebUI.TRegularExpressionValidator = Class.extend(Prado.WebUI.TBaseValidator, { /** - * Compare the control input against a regular expression. + * Additional constructor option. + * @constructor initialize + * @param {object} options - Additional constructor option: + * @... {string} ValidationExpression - Regular expression to match against. + */ + + /** + * Evaluate validation state + * @function {boolean} ? + * @return True if value matches regular expression or value is empty. */ evaluateIsValid : function() { @@ -1342,6 +1632,9 @@ Prado.WebUI.TRegularExpressionValidator = Class.extend(Prado.WebUI.TBaseValidato /** * TEmailAddressValidator validates whether the value of an associated * input component is a valid email address. + * + * @class Prado.WebUI.TEmailAddressValidator + * @extends Prado.WebUI.TRegularExpressionValidator */ Prado.WebUI.TEmailAddressValidator = Prado.WebUI.TRegularExpressionValidator; @@ -1349,12 +1642,16 @@ Prado.WebUI.TEmailAddressValidator = Prado.WebUI.TRegularExpressionValidator; /** * TListControlValidator checks the number of selection and their values * for a TListControl that allows multiple selections. + * + * @class Prado.WebUI.TListControlValidator + * @extends Prado.WebUI.TBaseValidator */ Prado.WebUI.TListControlValidator = Class.extend(Prado.WebUI.TBaseValidator, { /** - * @return true if the number of selections and/or their values - * match the requirements. + * Evaluate validation state + * @function {boolean} ? + * @return True if number of selections and/or their values match requirements. */ evaluateIsValid : function() { @@ -1369,7 +1666,9 @@ Prado.WebUI.TListControlValidator = Class.extend(Prado.WebUI.TBaseValidator, }, /** - * Observe list elements for IE browsers of changes + * Observe list elements for of changes (only IE) + * @function ? + * @param {element[]} elements - Array of DOM elements to observe */ observeListElements : function(elements) { @@ -1384,10 +1683,14 @@ Prado.WebUI.TListControlValidator = Class.extend(Prado.WebUI.TBaseValidator, }, /** - * Determine if the number of checked and the checked values + * Check if list is valid. + * Determine if the number of checked values and the checked values * satisfy the required number of checks and/or the checked values * equal to the required values. - * @return boolean true if checked values and number of checks are satisfied. + * @function {boolean} ? + * @param {int} checked - Number of required checked values + * @param {string[]} values - Array of required checked values + * @return True if checked values and number of checks are satisfied. */ isValidList : function(checked, values) { @@ -1413,7 +1716,9 @@ Prado.WebUI.TListControlValidator = Class.extend(Prado.WebUI.TBaseValidator, }, /** - * @return array list of required options that must be selected. + * Get list of required values. + * @function {string[]} ? + * @return Array of required values that must be selected. */ getRequiredValues : function() { @@ -1428,32 +1733,57 @@ Prado.WebUI.TListControlValidator = Class.extend(Prado.WebUI.TBaseValidator, /** * TDataTypeValidator verifies if the input data is of the type specified * by DataType option. - * The following data types are supported: - * - Integer A 32-bit signed integer data type. - * - Float A double-precision floating point number data type. - * - Date A date data type. - * - String A string data type. - * For Date type, the option DateFormat - * will be used to determine how to parse the date string. + * + *

The following data types are supported:

+ * + * - Integer A 32-bit signed integer data type.
+ * - Float A double-precision floating point number data type.
+ * - Date A date data type.
+ * - String A string data type.
+ * + *

For Date type, the option DateFormat + * will be used to determine how to parse the date string.

+ * + * @class Prado.WebUI.TDataTypeValidator + * @extends Prado.WebUI.TBaseValidator */ Prado.WebUI.TDataTypeValidator = Class.extend(Prado.WebUI.TBaseValidator, { - evaluateIsValid : function() - { - value = this.getValidationValue(); - if(value.length <= 0) - return true; - return this.convert(this.options.DataType, value) != null; - } + /** + * Additional constructor option. + * @constructor initialize + * @param {object} options - Additional constructor option: + * @... {string} DataType - Value data type: "Integer", "Float", "Date" or "String" + * @... {string} DateFormat - Date format for data type Date. + */ + + /** + * Evaluate validation state + * @function {boolean} ? + * @return True if value matches required data type. + */ + evaluateIsValid : function() + { + value = this.getValidationValue(); + if(value.length <= 0) + return true; + return this.convert(this.options.DataType, value) != null; + } }); /** - * TCaptchaValidator verifies if the input data is the same as the token shown in the associated CAPTCHA contorl. + * TCaptchaValidator verifies if the input data is the same as + * the token shown in the associated CAPTCHA control. + * + * @class Prado.WebUI.TCaptchaValidator + * @extends Prado.WebUI.TBaseValidator */ Prado.WebUI.TCaptchaValidator = Class.extend(Prado.WebUI.TBaseValidator, { /** - * @return boolean true if the input value is not empty nor equal to the initial value. + * Evaluate validation state + * @function {boolean} ? + * @return True if value matches captcha text */ evaluateIsValid : function() { @@ -1487,7 +1817,6 @@ Prado.WebUI.TCaptchaValidator = Class.extend(Prado.WebUI.TBaseValidator, utftext += String.fromCharCode(((c >> 6) & 63) | 128); utftext += String.fromCharCode((c & 63) | 128); } - } return utftext; -- cgit v1.2.3