Changeset 2458 for trunk/framework/Web

Show
Ignore:
Timestamp:
05/06/2008 02:56:47 AM (8 months ago)
Author:
mikl
Message:

Updated jsdoc for some base classes and validation.

Location:
trunk/framework/Web/Javascripts/source/prado
Files:
1 added
2 modified

Legend:

Unmodified
Added
Removed

  • trunk/framework/Web/Javascripts/source/prado/prado.js

    r1411 r2458  
    1  
     1/** 
     2 * Prado base namespace 
     3 * @namespace Prado 
     4 */ 
    25var Prado = 
    36{ 
     7        /** 
     8         * Version of Prado clientscripts 
     9         * @var Version 
     10         */ 
    411        Version: '3.1', 
    512 
    613        /** 
    7          * Returns browser information. Example 
    8          * <code> 
     14         * Returns browser information.  
     15         * <pre> 
    916         * var browser = Prado.Browser(); 
    1017         * alert(browser.ie); //should ouput true if IE, false otherwise 
    11          * </code> 
    12          * @param ${parameter} 
    13          * @return ${return} 
     18         * </pre> 
     19         * @function {object} ? 
     20         * @version 1.0 
     21         * @returns browserinfo 
     22         * @... {string} agent - Reported user agent 
     23         * @... {string} ver - Reported agent version 
     24         * @... {0|1} dom - 1 for DOM browsers  
     25         * @... {0|1} ns4 - 1 for Netscape 4 
     26         * @... {0|1} ns6 - 1 for Netscape 6 and Firefox 
     27         * @... {boolean} ie3 - true for IE 3 
     28         * @... {0|1} ie5 - 1 for IE 5 
     29         * @... {0|1} ie6 - 1 for IE 6 
     30         * @... {0|1} ie4 - 1 for IE 4 
     31         * @... {0|1} ie - 1 for IE 4-6 
     32         * @... {0|1} hotjava - 1 for HotJava 
     33         * @... {0|1} ver3 - 1 for IE3 and HotJava 
     34         * @... {0|1} opera - 1 for Opera 
     35         * @... {boolean} opera7 - true for Opera 7 
     36         * @... {0|1} operaOld - 1 for older Opera     
     37         * @... {0|1} bw - 1 for IE 4-6, Netscape 4&6, Firefox and Opera 
     38         * @... {boolean} mac - true for mac systems  
     39         * @... {static} Version - Version of returned structure (1.0) 
    1440         */ 
    1541        Browser : function() 
    … …  
    3864        }, 
    3965 
     66        /** 
     67         * Import CSS from Url. 
     68         * @function ? 
     69         * @param doc - document DOM object 
     70         * @param css_file - Url to CSS file 
     71         */ 
    4072        ImportCss : function(doc, css_file) 
    4173        { 

  • trunk/framework/Web/Javascripts/source/prado/scriptaculous-adapter.js

    r2414 r2458  
    1  
     1/** 
     2 * Utilities and extions to Prototype/Scriptaculous 
     3 * @file scriptaculous-adapter.js 
     4 */ 
     5  
     6/** 
     7 * Extension to  
     8 * <a href="http://www.prototypejs.org/api/function" target="_blank">Prototype's Function</a> 
     9 * @namespace Function 
     10 */ 
    211/** 
    312 * Similar to bindAsEventLister, but takes additional arguments. 
     13 * @function Function.bindEvent 
    414 */ 
    515Function.prototype.bindEvent = function() 
    … …  
    1323 
    1424/** 
    15  * Creates a new function by copying function definition from 
     25 * Extension to  
     26 * <a href="http://www.prototypejs.org/api/class" target="_blank">Prototype's Class</a> 
     27 * @namespace Class 
     28 */ 
     29  
     30/** 
     31 * Creates a new class by copying class definition from 
    1632 * the <tt>base</tt> and optional <tt>definition</tt>. 
    17  * @param function a base function to copy from. 
    18  * @param array additional definition 
    19  * @param function return a new function with definition from both 
    20  * <tt>base</tt> and <tt>definition</tt>. 
     33 * @function {Class} Class.extend 
     34 * @param {function} base - Base class to copy from. 
     35 * @param {optional Array} - Additional definition  
     36 * @returns Constructor for the extended class 
    2137 */ 
    2238Class.extend = function(base, definition) 
    … …  
    2945}; 
    3046 
    31 /* 
    32         Base, version 1.0.2 
    33         Copyright 2006, Dean Edwards 
    34         License: http://creativecommons.org/licenses/LGPL/2.1/ 
    35 */ 
    36  
     47/** 
     48 * Base, version 1.0.2 
     49 * Copyright 2006, Dean Edwards 
     50 * License: http://creativecommons.org/licenses/LGPL/2.1/ 
     51 * @class Base 
     52 */ 
    3753var Base = function() { 
    3854        if (arguments.length) { 
    … …  
    137153 
    138154/** 
    139  * Performs a post-back using javascript 
    140  * 
     155 * Performs a PostBack using javascript. 
     156 * @function Prado.PostBack 
     157 * @param event - Event that triggered this postback 
     158 * @param options - Postback options 
     159 * @... {string} FormID - Form that should be posted back 
     160 * @... {optional boolean} CausesValidation - Validate before PostBack if true 
     161 * @... {optional string} ValidationGroup - Group to Validate  
     162 * @... {optional string} ID - Validation ID  
     163 * @... {optional string} PostBackUrl - Postback URL 
     164 * @... {optional boolean} TrackFocus - Keep track of focused element if true 
     165 * @... {string} EventTarget - Id of element that triggered PostBack 
     166 * @... {string} EventParameter - EventParameter for PostBack 
    141167 */ 
    142168Prado.PostBack = function(event,options) 
    … …  
    178204}; 
    179205 
     206/** 
     207 * Prado utilities to manipulate DOM elements. 
     208 * @object Prado.Element 
     209 */ 
    180210Prado.Element = 
    181211{ 
    182212        /** 
    183213         * Set the value of a particular element. 
    184          * @param string element id 
    185          * @param string new element value. 
     214         * @function ? 
     215         * @param {string} element - Element id 
     216         * @param {string} value - New element value 
    186217         */ 
    187218        setValue : function(element, value) 
    … …  
    192223        }, 
    193224 
     225        /** 
     226         * Select options from a selectable element. 
     227         * @function ? 
     228         * @param {string} element - Element id 
     229         * @param {string} method - Name of any {@link Prado.Element.Selection} method 
     230         * @param {array|boolean|string} value - Values that should be selected 
     231         * @param {int} total - Number of elements  
     232         */ 
    194233        select : function(element, method, value, total) 
    195234        { 
    … …  
    204243        }, 
    205244 
     245        /** 
     246         * Trigger a click event on a DOM element. 
     247         * @function ? 
     248         * @param {string} element - Element id 
     249         */ 
    206250        click : function(element) 
    207251        { 
    … …  
    211255        }, 
    212256 
     257        /** 
     258         * Check if an DOM element is disabled. 
     259         * @function {boolean} ? 
     260         * @param {string} element - Element id 
     261         * @returns true if element is disabled 
     262         */ 
    213263        isDisabled : function(element) 
    214264        { 
    … …  
    222272        }, 
    223273 
     274        /** 
     275         * Sets an attribute of a DOM element. 
     276         * @function ? 
     277         * @param {string} element - Element id 
     278         * @param {string} attribute - Name of attribute 
     279         * @param {string} value - Value of attribute 
     280         */ 
    224281        setAttribute : function(element, attribute, value) 
    225282        { 
    … …  
    244301        }, 
    245302 
     303        /** 
     304         * Sets the options for a select element.  
     305         * @function ? 
     306         * @param {string} element - Element id 
     307         * @param {array[]} options - Array of options, each an array of structure  
     308         *   [ "optionText" , "optionValue" , "optionGroup" ] 
     309         */ 
    246310        setOptions : function(element, options) 
    247311        { 
    … …  
    262326 
    263327        /** 
    264          * Create opt-group options from an array of options[0]=text, options[1]=value, options[2]=group 
     328         * Create opt-group options from an array of options.  
     329         * @function {array} ? 
     330         * @param {array[]} options - Array of options, each an array of structure  
     331         *   [ "optionText" , "optionValue" , "optionGroup" ] 
     332         * @returns Array of option DOM elements 
    265333         */ 
    266334        createOptions : function(options) 
    … …  
    303371 
    304372        /** 
    305          * A delayed focus on a particular element 
    306          * @param {element} element to apply focus() 
     373         * Set focus (delayed) on a particular element. 
     374         * @function ? 
     375         * @param {string} element - Element id 
    307376         */ 
    308377        focus : function(element) 
    … …  
    314383        }, 
    315384 
     385        /** 
     386         * Replace a DOM element either with given content or 
     387         * with content from a CallBack response boundary 
     388         * using a replacement method. 
     389         * @function ? 
     390         * @param {string|element} element - DOM element or element id 
     391         * @param {string} method - Name of method to use for replacement 
     392         * @param {optional string} content - New content of element 
     393         * @param {optional string} boundary - Boundary of new content 
     394         */ 
    316395        replace : function(element, method, content, boundary) 
    317396        { 
    … …  
    333412        }, 
    334413 
     414        /** 
     415         * Extract content from a text by its boundary id. 
     416         * Boundaries have this form: 
     417         * <pre> 
     418         * &lt;!--123456--&gt;Democontent&lt;!--//123456--&gt; 
     419         * </pre> 
     420         * @function {string} ? 
     421         * @param {string} text - Text that contains boundaries 
     422         * @param {string} boundary - Boundary id 
     423         * @returns Content from given boundaries 
     424         */ 
    335425        extractContent : function(text, boundary) 
    336426        { 
    … …  
    354444        }, 
    355445 
     446        /** 
     447         * Evaluate a javascript snippet from a string. 
     448         * @function ? 
     449         * @param {string} content - String containing the script 
     450         */ 
    356451        evaluateScript : function(content) 
    357452        { 
    … …  
    359454        }, 
    360455         
     456        /** 
     457         * Set CSS style with Camelized keys. 
     458         * See <a href="http://www.prototypejs.org/api/element/setstyle" target="_blank">Prototype's  
     459         * Element.setStyle</a> for details. 
     460         * @function ? 
     461         * @param {string|element} element - DOM element or element id 
     462         * @param {object} styles - Object with style properties/values 
     463         */ 
    361464        setStyle : function (element, styles) 
    362465        { 
    … …  
    371474}; 
    372475 
     476/** 
     477 * Utilities for selections. 
     478 * @object Prado.Element.Selection 
     479 */ 
    373480Prado.Element.Selection = 
    374481{ 
     482        /** 
     483         * Check if an DOM element can be selected. 
     484         * @function {boolean} ? 
     485         * @param {element} el - DOM elemet 
     486         * @returns true if element is selectable 
     487         */ 
    375488        isSelectable : function(el) 
    376489        { 
    … …  
    390503        }, 
    391504 
     505        /** 
     506         * Set checked attribute of a checkbox or radiobutton to value. 
     507         * @function {boolean} ? 
     508         * @param {element} el - DOM element 
     509         * @param {boolean} value - New value of checked attribute 
     510         * @returns New value of checked attribute 
     511         */ 
    392512        inputValue : function(el, value) 
    393513        { 
    … …  
    400520        }, 
    401521 
     522        /** 
     523         * Set selected attribute for elements options by value. 
     524         * If value is boolean, all elements options selected attribute will be set 
     525         * to value. Otherwhise all options that have the given value will be selected.  
     526         * @function ? 
     527         * @param {element[]} elements - Array of selectable DOM elements 
     528         * @param {boolean|string} value - Value of options that should be selected or boolean value of selection status 
     529         */ 
    402530        selectValue : function(elements, value) 
    403531        { 
    … …  
    414542        }, 
    415543 
     544        /** 
     545         * Set selected attribute for elements options by array of values. 
     546         * @function ? 
     547         * @param {element[]} elements - Array of selectable DOM elements 
     548         * @param {string[]} value - Array of values to select 
     549         */ 
    416550        selectValues : function(elements, values) 
    417551        { 
    … …  
    423557        }, 
    424558 
     559        /** 
     560         * Set selected attribute for elements options by option index. 
     561         * @function ? 
     562         * @param {element[]} elements - Array of selectable DOM elements 
     563         * @param {int} index - Index of option to select 
     564         */ 
    425565        selectIndex : function(elements, index) 
    426566        { 
    … …  
    440580        }, 
    441581 
     582        /** 
     583         * Set selected attribute to true for all elements options. 
     584         * @function ? 
     585         * @param {element[]} elements - Array of selectable DOM elements 
     586         */ 
    442587        selectAll : function(elements) 
    443588        { 
    … …  
    454599        }, 
    455600 
     601        /** 
     602         * Toggle the selected attribute for elements options. 
     603         * @function ? 
     604         * @param {element[]} elements - Array of selectable DOM elements 
     605         */ 
    456606        selectInvert : function(elements) 
    457607        { 
    … …  
    468618        }, 
    469619 
     620        /** 
     621         * Set selected attribute for elements options by array of option indices. 
     622         * @function ? 
     623         * @param {element[]} elements - Array of selectable DOM elements 
     624         * @param {int[]} indices - Array of option indices to select 
     625         */ 
    470626        selectIndices : function(elements, indices) 
    471627        { 
    … …  
    477633        }, 
    478634 
     635        /** 
     636         * Unselect elements. 
     637         * @function ? 
     638         * @param {element[]} elements - Array of selectable DOM elements 
     639         */ 
    479640        selectClear : function(elements) 
    480641        { 
    … …  
    485646        }, 
    486647 
     648        /** 
     649         * Get list elements of an element. 
     650         * @function {element[]} ? 
     651         * @param {element[]} elements - Array of selectable DOM elements 
     652         * @param {int} total - Number of list elements to return 
     653         * @returns Array of list DOM elements 
     654         */ 
    487655        getListElements : function(element, total) 
    488656        { 
    … …  
    497665        }, 
    498666 
     667        /** 
     668         * Set checked attribute of elements by value. 
     669         * If value is boolean, checked attribute will be set to value.  
     670         * Otherwhise all elements that have the given value will be checked.  
     671         * @function ? 
     672         * @param {element[]} elements - Array of checkable DOM elements 
     673         * @param {boolean|String} value - Value that should be checked or boolean value of checked status 
     674         *        
     675         */ 
    499676        checkValue : function(elements, value) 
    500677        { 
    … …  
    508685        }, 
    509686 
     687        /** 
     688         * Set checked attribute of elements by array of values. 
     689         * @function ? 
     690         * @param {element[]} elements - Array of checkable DOM elements 
     691         * @param {string[]} values - Values that should be checked 
     692         *        
     693         */ 
    510694        checkValues : function(elements, values) 
    511695        { 
    … …  
    517701        }, 
    518702 
     703        /** 
     704         * Set checked attribute of elements by list index. 
     705         * @function ? 
     706         * @param {element[]} elements - Array of checkable DOM elements 
     707         * @param {int} index - Index of element to set checked 
     708         */ 
    519709        checkIndex : function(elements, index) 
    520710        { 
    … …  
    526716        }, 
    527717 
     718        /** 
     719         * Set checked attribute of elements by array of list indices. 
     720         * @function ? 
     721         * @param {element[]} elements - Array of selectable DOM elements 
     722         * @param {int[]} indices - Array of list indices to set checked 
     723         */ 
    528724        checkIndices : function(elements, indices) 
    529725        { 
    … …  
    535731        }, 
    536732 
     733        /** 
     734         * Uncheck elements. 
     735         * @function ? 
     736         * @param {element[]} elements - Array of checkable DOM elements 
     737         */ 
    537738        checkClear : function(elements) 
    538739        { 
    … …  
    543744        }, 
    544745 
     746        /** 
     747         * Set checked attribute of all elements to true. 
     748         * @function ? 
     749         * @param {element[]} elements - Array of checkable DOM elements 
     750         */ 
    545751        checkAll : function(elements) 
    546752        { 
    … …  
    551757        }, 
    552758 
     759        /** 
     760         * Toggle the checked attribute of elements. 
     761         * @function ? 
     762         * @param {element[]} elements - Array of selectable DOM elements 
     763         */ 
    553764        checkInvert : function(elements) 
    554765        { 
    … …  
    561772 
    562773 
     774/** 
     775 * Utilities for insertion. 
     776 * @object Prado.Element.Insert 
     777 */ 
    563778Prado.Element.Insert = 
    564779{ 
     780        /** 
     781         * Append content to element 
     782         * @function ? 
     783         * @param {element} element - DOM element that content should be appended to 
     784         * @param {element} content - DOM element to append 
     785         */ 
    565786        append: function(element, content) 
    566787        { 
    … …  
    568789        }, 
    569790 
     791        /** 
     792         * Prepend content to element 
     793         * @function ? 
     794         * @param {element} element - DOM element that content should be prepended to 
     795         * @param {element} content - DOM element to prepend 
     796         */ 
    570797        prepend: function(element, content) 
    571798        { 
    … …  
    573800        }, 
    574801 
     802        /** 
     803         * Insert content after element 
     804         * @function ? 
     805         * @param {element} element - DOM element that content should be inserted after 
     806         * @param {element} content - DOM element to insert 
     807         */ 
    575808        after: function(element, content) 
    576809        { 
    … …  
    578811        }, 
    579812 
     813        /** 
     814         * Insert content before element 
     815         * @function ? 
     816         * @param {element} element - DOM element that content should be inserted before 
     817         * @param {element} content - DOM element to insert 
     818         */ 
    580819        before: function(element, content) 
    581820        { 
    … …  
    586825 
    587826/** 
    588  * Export scripaculous builder utilities as window[functions] 
    589  */ 
     827 * Extension to  
     828 * <a href="http://wiki.script.aculo.us/scriptaculous/show/builder" target="_blank">Scriptaculous' Builder</a> 
     829 * @namespace Builder 
     830 */ 
     831 
    590832Object.extend(Builder, 
    591833{ 
     834        /** 
     835         * Export scriptaculous builder utilities as window[functions] 
     836         * @function ? 
     837         */ 
    592838        exportTags:function() 
    593839        { 
    … …  
    609855        } 
    610856}); 
    611  
    612857Builder.exportTags(); 
    613858 
    614859/** 
    615  * @class String extensions 
     860 * Extension to  
     861 * <a href="http://www.prototypejs.org/api/string" target="_blank">Prototype's String</a> 
     862 * @namespace String 
    616863 */ 
    617864Object.extend(String.prototype, { 
    618         /** 
    619          * @param {String} "left" to pad the string on the left, "right" to pad right. 
    620          * @param {Number} minimum string length. 
    621          * @param {String} character(s) to pad 
    622          * @return {String} padded character(s) on the left or right to satisfy minimum string length 
    623          */ 
    624  
     865 
     866        /** 
     867         * Add padding to string 
     868         * @function {string} ? 
     869         * @param {string} side - "left" to pad the string on the left, "right" to pad right. 
     870         * @param {int} len - Minimum string length. 
     871         * @param {string} chr - Character(s) to pad 
     872         * @returns Padded string 
     873         */ 
    625874        pad : function(side, len, chr) { 
    626875                if (!chr) chr = ' '; 
    … …  
    632881 
    633882        /** 
    634          * @param {Number} minimum string length. 
    635          * @param {String} character(s) to pad 
    636          * @return {String} padded character(s) on the left to satisfy minimum string length 
     883         * Add left padding to string 
     884         * @function {string} ? 
     885         * @param {int} len - Minimum string length. 
     886         * @param {string} chr - Character(s) to pad 
     887         * @returns Padded string 
    637888         */ 
    638889        padLeft : function(len, chr) { 
    … …  
    641892 
    642893        /** 
    643          * @param {Number} minimum string length. 
    644          * @param {String} character(s) to pad 
    645          * @return {String} padded character(s) on the right to satisfy minimum string length 
     894         * Add right padding to string 
     895         * @function {string} ? 
     896         * @param {int} len - Minimum string length. 
     897         * @param {string} chr - Character(s) to pad 
     898         * @returns Padded string 
    646899         */ 
    647900        padRight : function(len, chr) { 
    … …  
    650903 
    651904        /** 
    652          * @param {Number} minimum string length. 
    653          * @return {String} append zeros to the left to satisfy minimum string length. 
     905         * Add zeros to the right of string