Changeset 1144


Ignore:
Timestamp:
12/24/08 15:34:25 (5 years ago)
Author:
ray
Message:

Updated inline documentation for XinhaCore?.js and XinhaDialog?.js

Location:
trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/XinhaCore.js

    r1142 r1144  
    2626/*global  Dialog , _editor_css , _editor_icons, _editor_lang , _editor_skin , _editor_url, dumpValues, ActiveXObject, HTMLArea, _editor_lcbackend*/ 
    2727 
     28/** Information about the Xinha version  
     29 * @type Object 
     30 */ 
    2831Xinha.version = 
    2932{ 
     
    6972   
    7073  // convert _editor_url to absolute 
    71   if(!_editor_url.match(/^([^:]+\:)?\//)){ 
    72     Xinha.tmpPath = window.location.toString().replace(/\?.*$/,'').split("/"); 
    73     Xinha.tmpPath.pop(); 
    74     _editor_url = Xinha._resolveRelativeUrl(Xinha.tmpPath.join("/"), _editor_url); 
    75     delete Xinha.tmpPath;   
     74  if(!_editor_url.match(/^([^:]+\:)?\//)) 
     75  { 
     76    (function() 
     77    { 
     78      var tmpPath = window.location.toString().replace(/\?.*$/,'').split("/"); 
     79      tmpPath.pop(); 
     80      _editor_url = Xinha._resolveRelativeUrl(tmpPath.join("/"), _editor_url); 
     81    })(); 
    7682  } 
    7783} 
     
    115121// browser identification 
    116122/** Cache the user agent for the following checks 
     123 * @type String 
    117124 * @private 
    118125 */ 
    119126Xinha.agt       = navigator.userAgent.toLowerCase(); 
    120127/** Browser is Microsoft Internet Explorer 
    121 @type string  
    122 */ 
     128 * @type Boolean  
     129 */ 
    123130Xinha.is_ie    = ((Xinha.agt.indexOf("msie") != -1) && (Xinha.agt.indexOf("opera") == -1)); 
    124131/** Version Number, if browser is Microsoft Internet Explorer 
    125 @type string  
    126 */ 
     132 * @type Float  
     133 */ 
    127134Xinha.ie_version= parseFloat(Xinha.agt.substring(Xinha.agt.indexOf("msie")+5)); 
    128135/** Browser is Opera 
    129 @type string  
    130 */ 
     136 * @type Boolean  
     137 */ 
    131138Xinha.is_opera  = (Xinha.agt.indexOf("opera") != -1); 
    132139/** Version Number, if browser is Opera  
    133 @type string  
    134 */ 
     140  * @type Float  
     141  */ 
    135142if(Xinha.is_opera && Xinha.agt.match(/opera[\/ ]([0-9.]+)/)) 
    136143{ 
     
    142149} 
    143150/** Browserengine is KHTML (Konqueror, Safari) 
    144 @type string  
    145 */ 
     151 * @type Boolean  
     152 */ 
    146153Xinha.is_khtml  = (Xinha.agt.indexOf("khtml") != -1); 
    147154/** Browser is WebKit 
    148 @type string  
    149 */ 
     155 * @type Boolean  
     156 */ 
    150157Xinha.is_webkit  = (Xinha.agt.indexOf("applewebkit") != -1); 
     158/** Webkit build number 
     159 * @type Integer 
     160 */ 
    151161Xinha.webkit_version = parseInt(navigator.appVersion.replace(/.*?AppleWebKit\/([\d]).*?/,'$1'), 10); 
    152162 
    153163/** Browser is Safari 
    154 @type string  
    155 */ 
     164 * @type Boolean  
     165 */ 
    156166Xinha.is_safari  = (Xinha.agt.indexOf("safari") != -1); 
    157167 
    158168/** Browser is Google Chrome 
    159 @type string  
    160 */ 
     169 * @type Boolean  
     170 */ 
    161171Xinha.is_chrome = (Xinha.agt.indexOf("chrome") != -1); 
    162172 
    163173/** OS is MacOS 
    164 @type string  
    165 */ 
     174 * @type Boolean  
     175 */ 
    166176Xinha.is_mac       = (Xinha.agt.indexOf("mac") != -1); 
    167177/** Browser is Microsoft Internet Explorer Mac 
    168 @type string  
    169 */ 
     178 * @type Boolean  
     179 */ 
    170180Xinha.is_mac_ie = (Xinha.is_ie && Xinha.is_mac); 
    171181/** Browser is Microsoft Internet Explorer Windows 
    172 @type string  
    173 */ 
     182 * @type Boolean  
     183 */ 
    174184Xinha.is_win_ie = (Xinha.is_ie && !Xinha.is_mac); 
    175185/** Browser engine is Gecko (Mozilla), applies also to Safari and Opera which work 
    176186 *  largely similar. 
    177 @type string  
    178 */ 
     187 *@type Boolean  
     188 */ 
    179189Xinha.is_gecko  = (navigator.product == "Gecko") || Xinha.is_opera; 
     190/** Browser engine is really Gecko, i.e. Browser is Firefox (or Netscape, SeaMonkey, Flock, Songbird, Beonex, K-Meleon, Camino, Galeon, Kazehakase, Skipstone, or whatever derivate might exist out there...) 
     191 * @type Boolean  
     192 */ 
    180193Xinha.is_real_gecko = (navigator.product == "Gecko" && !Xinha.is_webkit); 
     194/** Gecko version 1.9 (or greater) 
     195 * @type Boolean  
     196 */ 
    181197Xinha.is_ff3 = Xinha.is_real_gecko && parseInt(navigator.productSub, 10) >= 2007121016; 
     198/** Gecko version lower than 1.9 
     199 * @type Boolean  
     200 */ 
    182201Xinha.is_ff2 = Xinha.is_real_gecko && parseInt(navigator.productSub, 10) < 2007121016; 
    183202 
    184203/** File is opened locally opened ("file://" protocol) 
    185  * @type string 
     204 * @type Boolean 
    186205 * @private 
    187206 */ 
    188207Xinha.isRunLocally = document.URL.toLowerCase().search(/^file:/) != -1; 
    189208/** Editing is enabled by document.designMode (Gecko, Opera), as opposed to contenteditable (IE) 
    190  * @type string 
     209 * @type Boolean 
    191210 * @private 
    192211 */ 
     
    490509Xinha.Config = function() 
    491510{ 
     511  /** The svn revision number  
     512   * @type Number 
     513   */ 
    492514  this.version = Xinha.version.Revision; 
    493515   
     
    739761   */ 
    740762  this.outwardHtml = function (html) { return html; }; 
    741  
     763   
     764  /** This setting determines whether or not the editor will be automatically activated and focused when the page loads.  
     765   *  If the page contains only a single editor, autofocus can be set to true to focus it.  
     766   *  Alternatively, if the page contains multiple editors, autofocus may be set to the ID of the text area of the editor to be focused.  
     767   *  For example, the following setting would focus the editor attached to the text area whose ID is "myTextArea":  
     768   *  <code>xinha_config.autofocus = "myTextArea";</code> 
     769   *  Default: <code>false</code> 
     770   *  @type Boolean|String 
     771   */ 
     772  this.autofocus = false; 
     773   
    742774 /** Set to true if you want Word code to be cleaned upon Paste. This only works if  
    743775   * you use the toolbr button to paste, not ^V. This means that due to the restrictions 
     
    60886120 
    60896121 
    6090 /* * These are all the tags for which the end tag is not optional or  forbidden, taken from the list at: 
     6122/** These are all the tags for which the end tag is not optional or  forbidden, taken from the list at: 
    60916123 *   http: www.w3.org/TR/REC-html40/index/elements.html 
    60926124 *   
    60936125 *  @private 
    60946126 *  @see Xinha#needsClosingTag 
    6095  *  @type {String} 
     6127 *  @type String 
    60966128 */ 
    60976129Xinha._closingTags = " a abbr acronym address applet b bdo big blockquote button caption center cite code del dfn dir div dl em fieldset font form frameset h1 h2 h3 h4 h5 h6 i iframe ins kbd label legend map menu noframes noscript object ol optgroup pre q s samp script select small span strike strong style sub sup table textarea title tt u ul var "; 
     
    61476179  return string.replace(basere, ""); 
    61486180}; 
    6149 /** Removes whitespace from beginning and end of a string 
    6150  *   
    6151  *  @returns {String}  
    6152  */ 
    6153 String.prototype.trim = function() 
    6154 { 
    6155   return this.replace(/^\s+/, '').replace(/\s+$/, ''); 
    6156 }; 
     6181 
     6182if (typeof String.prototype.trim != 'function') 
     6183{ 
     6184  /** Removes whitespace from beginning and end of a string. Custom implementation for JS engines that don't support it natively 
     6185   *   
     6186   *  @returns {String}  
     6187   */ 
     6188  String.prototype.trim = function() 
     6189  { 
     6190    return this.replace(/^\s+/, '').replace(/\s+$/, ''); 
     6191  }; 
     6192} 
    61576193 
    61586194/** Creates a rgb-style rgb(r,g,b) color from a (24bit) number 
     
    65526588 */ 
    65536589  
    6554 // mod_security (an apache module which scans incoming requests for potential hack attempts) 
    6555 // has a rule which triggers when it gets an incoming Content-Type with a charset 
    6556 // see ticket:1028 to try and work around this, if we get a failure in a postback 
    6557 // then Xinha._postback_send_charset will be set to false and the request tried again (once) 
     6590/** mod_security (an apache module which scans incoming requests for potential hack attempts) 
     6591 *  has a rule which triggers when it gets an incoming Content-Type with a charset 
     6592 *  see ticket:1028 to try and work around this, if we get a failure in a postback 
     6593 *  then Xinha._postback_send_charset will be set to false and the request tried again (once) 
     6594 *  @type Boolean 
     6595 *  @private 
     6596 */  
     6597//  
     6598//  
     6599//  
    65586600Xinha._postback_send_charset = true; 
     6601/** Use XMLHTTPRequest to send some some data to the server and do something 
     6602 *  with the getback (asyncronously!) 
     6603 * @param {String} url The address for the HTTPRequest 
     6604 * @param {Function} success A function that is called when an answer is 
     6605 *                           received from the server with the responseText as argument. 
     6606 * @param {Function} failure A function that is called when we fail to receive 
     6607 *                           an answer from the server. We pass it the request object. 
     6608 */ 
    65596609Xinha._postback = function(url, data, success, failure) 
    65606610{ 
     
    66106660}; 
    66116661 
    6612 /**  
    6613  * Use XMLHTTPRequest to receive some data from the server and do something 
     6662/** Use XMLHTTPRequest to receive some data from the server and do something 
    66146663 * with the it (asyncronously!) 
    66156664 * @param {String} url The address for the HTTPRequest 
     
    67986847  }; 
    67996848} 
    6800 /** Executes a provided function once per array element 
     6849/** Executes a provided function once per array element. 
     6850 *  Custom implementation for JS engines that don't support it natively 
    68016851 * @source http://developer.mozilla.org/En/Core_JavaScript_1.5_Reference/Global_Objects/Array/ForEach 
    68026852 * @param {Function} fn Function to execute for each element 
     
    68236873  }; 
    68246874} 
     6875/** Returns all elements within a given class name inside an element 
     6876 * @type Array 
     6877 * @param {DomNode|document} el wherein to search 
     6878 * @param {Object} className 
     6879 */ 
    68256880Xinha.getElementsByClassName = function(el,className) 
    68266881{ 
  • trunk/modules/Dialogs/XinhaDialog.js

    r1141 r1144  
    2626 
    2727/** Xinha Dialog 
    28  * 
    29  * 
    30  * @param editor Xinha object     
    31  * @param html string  
    32  * @param localizer string the "context" parameter for Xinha._lc(), typically the name of the plugin 
    33  * @param size object with two possible properties of the size: width & height as int, where height is optional 
    34  * @param options dictionary with optional boolean attributes 'modal', 'closable', 'resizable', and 'centered', as well as integer attribute 'layer' 
     28 *   
     29 * @constructor 
     30 * @version $LastChangedRevision$ $LastChangedDate$ 
     31 * @param {Xinha} editor Xinha object     
     32 * @param {String} html string The HTML for the dialog's UI 
     33 * @param {String} localizer string the "context" parameter for Xinha._lc(), typically the name of the plugin 
     34 * @param {Object} size object with two possible properties of the size: width & height as int, where height is optional 
     35 * @param {Object} options dictionary with optional boolean attributes 'modal', 'closable', 'resizable', and 'centered', as well as integer attribute 'layer' 
     36 
    3537 */ 
    3638Xinha.Dialog = function(editor, html, localizer, size, options) 
    3739{ 
    3840  var dialog = this; 
     41   
     42  /** Used for dialog.getElementById() 
     43   * @type Object 
     44   * @private 
     45   */ 
    3946  this.id    = { }; 
     47  /** Used for dialog.getElementById() 
     48   * @type Object 
     49   * @private 
     50   */ 
    4051  this.r_id  = { }; // reverse lookup id 
     52  /** The calling Xinha instance 
     53   * @type Xinha 
     54   * @private 
     55   */ 
    4156  this.editor   = editor; 
     57  /**  
     58   * @private 
     59   * @type Document 
     60   */ 
    4261  this.document = document; 
     62  /** Object with width, height as numbers 
     63   * @type Object 
     64   */ 
     65   
    4366  this.size = size; 
     67  /**  
     68   * @type Boolean 
     69   * @private 
     70   */ 
    4471  this.modal = (options && options.modal === false) ? false : true; 
     72  /**  
     73   * @type Boolean 
     74   * @private 
     75   */ 
    4576  this.closable = (options && options.closable === false) ? false : true; 
     77  /**  
     78   * @type Boolean 
     79   * @private 
     80   */ 
    4681  this.resizable = (options && options.resizable === false) ? false : true; 
     82  /**  
     83   * @type Number 
     84   * @private 
     85   */ 
    4786  this.layer = (options && options.layer) ? options.layer : 0; 
     87  /**  
     88   * @type Boolean 
     89   * @private 
     90   */ 
    4891  this.centered = (options && options.centered === true) ? true : false; 
     92  /**  
     93   * @type Boolean 
     94   * @private 
     95   */ 
    4996  this.closeOnEscape = (options && options.closeOnEscape === true) ? true : false; 
    50  
     97   
     98  /** The div that is the actual dialog 
     99   *  @type DomNode 
     100   */ 
     101  this.rootElem = null; 
     102   
     103  /** The caption at the top of the dialog that is used to dragged the dialog. It is automatically created from the first h1 in the dialog's HTML 
     104   *  @type DomNode 
     105   */ 
     106  this.captionBar = null; 
     107  /** This div contains the content 
     108   *  @type DomNode 
     109   */ 
     110  this.main = null; 
     111   
     112  /** Each dialog has a background 
     113   *  @type DomNode 
     114   *  @private 
     115   */ 
     116  this.background = null; 
     117  /**  
     118   * @type Boolean 
     119   * @private 
     120   */ 
     121  this.centered = null; 
     122  /**  
     123   * @type Boolean 
     124   * @private 
     125   */ 
     126  this.greyout = null; 
     127   
     128  /**  
     129   * @type DomNode 
     130   * @private 
     131   */ 
     132  this.buttons = null; 
     133  /**  
     134   * @type DomNode 
     135   * @private 
     136   */ 
     137  this.closer = null; 
     138  /**  
     139   * @type DomNode 
     140   * @private 
     141   */ 
     142  this.icon = null; 
     143  /**  
     144   * @type DomNode 
     145   * @private 
     146   */ 
     147  this.resizer = null; 
     148  /**  
     149   * @type Number 
     150   * @private 
     151   */ 
     152  this.initialZ = null; 
     153   
    51154  /* Check global config to see if we should override any of the above options 
    52155    If a global option is set, it will apply to all dialogs, regardless of their 
     
    152255 
    153256  document.body.appendChild(backG); 
     257 
    154258  this.background = backG; 
    155259 
     
    326430 
    327431}; 
    328  
     432/** This function is called when the dialog is resized.  
     433 *  By default it does nothing, but you can override it in your Xinha.Dialog object e.g. to resize elements within you Dialog. 
     434 *  Example:<br /> 
     435 *  <code> 
     436 *  var dialog = this.dialog; //The plugin's dialog instance; 
     437 *  dialog.onresize = function()  
     438 *  { 
     439 *    var el = dialog.getElementById('foo'); 
     440 *    el.style.width = dialog.width; 
     441 *  } 
     442 *  </code> 
     443 */ 
    329444Xinha.Dialog.prototype.onresize = function() 
    330445{ 
    331446  return true; 
    332447}; 
    333  
     448/** This function shows the dialog and populates form elements with values. 
     449 * Example:<br /> 
     450 * Given your dialog contains an input element like <code>&lt;input name="[myInput]" type="text" /&gt;</code> 
     451 * <code> 
     452 *  var dialog = this.dialog; //The plugin's dialog instance; 
     453 *  var values = {myInput : 'My input value'} 
     454 *  dialog.show(values); 
     455 *  </code> 
     456 *  @see #setValues 
     457 *  @param {Object} values Object indexed by names of input elements 
     458 */ 
    334459Xinha.Dialog.prototype.show = function(values) 
    335460{ 
     
    489614  this.dialogShown = true; 
    490615}; 
    491  
     616/** Hides the dialog and returns an object with the valuse of form elements 
     617 * @see #getValues 
     618 * @type Object 
     619 */ 
    492620Xinha.Dialog.prototype.hide = function() 
    493621{ 
     
    538666  return this.getValues(); 
    539667}; 
    540  
     668/** Shows/hides the dialog 
     669 *  
     670 */ 
    541671Xinha.Dialog.prototype.toggle = function() 
    542672{ 
     
    550680  } 
    551681}; 
     682/** Reduces the dialog to the size of the caption bar 
     683 *  
     684 */ 
    552685Xinha.Dialog.prototype.collapse = function() 
    553686{ 
     
    564697}; 
    565698/** Equivalent to document.getElementById. You can't use document.getElementById because id's are dynamic to avoid id clashes between plugins 
    566  * @type {Element} 
     699 * @type DomNode 
    567700 * @param {String} id 
    568701 */ 
     
    572705}; 
    573706/** Equivalent to document.getElementByName. You can't use document.getElementByName because names are dynamic to avoid name clashes between plugins 
    574  * @type {Array} 
     707 * @type Array 
    575708 * @param {String} name 
    576709 */ 
     
    581714}; 
    582715/** Return all elements in the dialog that have the given class 
    583  * @type {Array}  
     716 * @type Array  
    584717 * @param {String} className 
    585718 */ 
     
    589722}; 
    590723 
     724/** Initiates dragging 
     725 * @private 
     726 * @param {Object} ev Mousedown event 
     727 */ 
    591728Xinha.Dialog.prototype.dragStart = function (ev)  
    592729{ 
     
    628765  } 
    629766}; 
    630  
     767/** Sets the position while dragging 
     768 * @private 
     769 * @param {Object} ev Mousemove event 
     770 */ 
    631771Xinha.Dialog.prototype.dragIt = function(ev) 
    632772{ 
     
    655795  dialog.posDialog(newPos); 
    656796}; 
    657  
     797/** Ends dragging 
     798 * @private 
     799 * @param {Object} ev Mouseup event 
     800 */ 
    658801Xinha.Dialog.prototype.dragEnd = function(ev) 
    659802{ 
     
    693836 
    694837}; 
    695  
     838/** Initiates resizing 
     839 * @private 
     840 * @param {Object} ev Mousedown event 
     841 */ 
    696842Xinha.Dialog.prototype.resizeStart = function (ev) { 
    697843  var dialog = this; 
     
    728874  } 
    729875}; 
    730  
     876/** Sets the size while resiziong 
     877 * @private 
     878 * @param {Object} ev Mousemove event 
     879 */ 
    731880Xinha.Dialog.prototype.resizeIt = function(ev) 
    732881{ 
     
    763912  dialog.onresize(); 
    764913}; 
    765  
     914/** Ends resizing 
     915 * @private 
     916 * @param {Object} ev Mouseup event 
     917 */ 
    766918Xinha.Dialog.prototype.resizeEnd = function(ev) 
    767919{ 
     
    793945  }   
    794946}; 
    795  
     947/** Attaches a modeless dialog to a panel on the given side 
     948 *  Triggers a notifyOf panel_change event 
     949 *  @param {String} side one of 'left', 'right', 'top', 'bottom' 
     950 */ 
    796951Xinha.Dialog.prototype.attachToPanel = function(side) 
    797952{ 
     
    831986  editor.notifyOf('panel_change', {'action':'add','panel':rootElem}); 
    832987}; 
    833  
    834 Xinha.Dialog.prototype.detachFromPanel = function(ev) 
     988/** Removes a panel dialog from its panel and makes it float 
     989 *  
     990 */ 
     991Xinha.Dialog.prototype.detachFromPanel = function() 
    835992{ 
    836993  var dialog = this; 
     
    8691026   
    8701027}; 
    871  
     1028/**  
     1029 * @private 
     1030 * @type Object Object with width, height strings incl. "px" for CSS 
     1031 */ 
    8721032Xinha.Dialog.calcFullBgSize = function() 
    8731033{ 
     
    8761036  return {width:(page.x > viewport.x  ? page.x : viewport.x )  + "px",height:(page.x > viewport.y ? page.y : viewport.y ) + "px"}; 
    8771037}; 
    878  
     1038/** Sizes the background to the size of the dialog 
     1039 *  @private 
     1040 */ 
    8791041Xinha.Dialog.prototype.sizeBgToDialog = function() 
    8801042{ 
     
    8861048  bgStyle.height = rootElemStyle.height; 
    8871049}; 
     1050/** Hides the background 
     1051 *  @private 
     1052 */ 
    8881053Xinha.Dialog.prototype.hideBackground = function() 
    8891054{ 
     
    8911056  Xinha.Dialog.fadeOut(this.background); 
    8921057}; 
     1058/** Shows the background 
     1059 *  @private 
     1060 */ 
    8931061Xinha.Dialog.prototype.showBackground = function() 
    8941062{ 
     
    8961064  Xinha.Dialog.fadeIn(this.background,70); 
    8971065}; 
     1066/** Positions the background 
     1067 *  @private 
     1068 *  @param {Object} pos Object with top, left strings incl. "px" for CSS 
     1069 */ 
    8981070Xinha.Dialog.prototype.posBackground = function(pos) 
    8991071{ 
     
    9041076  } 
    9051077}; 
     1078/** Resizes the background 
     1079 *  @private 
     1080 *  @param {Object} size Object with width, height strings incl. "px" for CSS 
     1081 */ 
    9061082Xinha.Dialog.prototype.resizeBackground = function(size) 
    9071083{ 
     
    9121088  } 
    9131089}; 
     1090/** Positions the dialog 
     1091 *  @param {Object} pos Object with top, left strings incl. "px" for CSS 
     1092 */ 
    9141093Xinha.Dialog.prototype.posDialog = function(pos) 
    9151094{ 
     
    9181097  st.top  = pos.top; 
    9191098}; 
     1099/** Resizes the dialog 
     1100 *  
     1101 * @param {Object} size Object with width, height strings incl. "px" for CSS 
     1102 */ 
    9201103Xinha.Dialog.prototype.sizeDialog = function(size) 
    9211104{ 
     
    9281111  this.main.style.width = (width > 10) ? width : 10 + 'px'; 
    9291112}; 
     1113/** Sets the values like Xinha.Dialog.prototype.show(values) 
     1114 * @see #show 
     1115 * @param {Object} values  
     1116 */ 
    9301117Xinha.Dialog.prototype.setValues = function(values) 
    9311118{ 
     
    10021189}; 
    10031190 
     1191/** Retrieves the values like Xinha.Dialog.prototype.hide() 
     1192 * @see #hide 
     1193 * @type Object values  
     1194 */ 
    10041195Xinha.Dialog.prototype.getValues = function() 
    10051196{ 
     
    10971288  return values; 
    10981289}; 
    1099  
    1100 Xinha.Dialog.prototype.translateHtml = function(html,localizer) 
     1290/** Localizes strings in the dialog. 
     1291 * @private 
     1292 * @param {String} html The HTML to translate 
     1293 * @param {String} localizer Context for translation, usually plugin's name 
     1294 */ 
     1295Xinha.Dialog.prototype.translateHtml = function(html, localizer) 
    11011296{ 
    11021297  var dialog = this; 
     
    11421337/** 
    11431338 * Fixup links in the elements to allow linking to Xinha resources 
     1339 * @private 
    11441340 */ 
    11451341Xinha.Dialog.prototype.fixupDOM = function(root,plugin) 
Note: See TracChangeset for help on using the changeset viewer.