Changeset 1144

Timestamp:

12/24/08 15:34:25 (4 years ago)

Author:

ray

Message:

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

Location:

trunk

Files:

• XinhaCore.js (modified) (12 diffs)
• modules/Dialogs/XinhaDialog.js (modified) (29 diffs)

trunk/XinhaCore.js

@@ -26 +26 @@
 /*global  Dialog , _editor_css , _editor_icons, _editor_lang , _editor_skin , _editor_url, dumpValues, ActiveXObject, HTMLArea, _editor_lcbackend*/
 
+/** Information about the Xinha version 
+ * @type Object
+ */
 Xinha.version =
 {
@@ -69 +72 @@
   
   // convert _editor_url to absolute
-  if(!_editor_url.match(/^([^:]+\:)?\//)){
-    Xinha.tmpPath = window.location.toString().replace(/\?.*$/,'').split("/");
-    Xinha.tmpPath.pop();
-    _editor_url = Xinha._resolveRelativeUrl(Xinha.tmpPath.join("/"), _editor_url);
-    delete Xinha.tmpPath;  
+  if(!_editor_url.match(/^([^:]+\:)?\//))
+  {
+    (function()
+    {
+      var tmpPath = window.location.toString().replace(/\?.*$/,'').split("/");
+      tmpPath.pop();
+      _editor_url = Xinha._resolveRelativeUrl(tmpPath.join("/"), _editor_url);
+    })();
   }
 }
@@ -115 +121 @@
 // browser identification
 /** Cache the user agent for the following checks
+ * @type String
  * @private
  */
 Xinha.agt       = navigator.userAgent.toLowerCase();
 /** Browser is Microsoft Internet Explorer
-@type string 
-*/
+ * @type Boolean 
+ */
 Xinha.is_ie    = ((Xinha.agt.indexOf("msie") != -1) && (Xinha.agt.indexOf("opera") == -1));
 /** Version Number, if browser is Microsoft Internet Explorer
-@type string 
-*/
+ * @type Float 
+ */
 Xinha.ie_version= parseFloat(Xinha.agt.substring(Xinha.agt.indexOf("msie")+5));
 /** Browser is Opera
-@type string 
-*/
+ * @type Boolean 
+ */
 Xinha.is_opera  = (Xinha.agt.indexOf("opera") != -1);
 /** Version Number, if browser is Opera 
-@type string 
-*/
+  * @type Float 
+  */
 if(Xinha.is_opera && Xinha.agt.match(/opera[\/ ]([0-9.]+)/))
 {
@@ -142 +149 @@
 }
 /** Browserengine is KHTML (Konqueror, Safari)
-@type string 
-*/
+ * @type Boolean 
+ */
 Xinha.is_khtml  = (Xinha.agt.indexOf("khtml") != -1);
 /** Browser is WebKit
-@type string 
-*/
+ * @type Boolean 
+ */
 Xinha.is_webkit  = (Xinha.agt.indexOf("applewebkit") != -1);
+/** Webkit build number
+ * @type Integer
+ */
 Xinha.webkit_version = parseInt(navigator.appVersion.replace(/.*?AppleWebKit\/([\d]).*?/,'$1'), 10);
 
 /** Browser is Safari
-@type string 
-*/
+ * @type Boolean 
+ */
 Xinha.is_safari  = (Xinha.agt.indexOf("safari") != -1);
 
 /** Browser is Google Chrome
-@type string 
-*/
+ * @type Boolean 
+ */
 Xinha.is_chrome = (Xinha.agt.indexOf("chrome") != -1);
 
 /** OS is MacOS
-@type string 
-*/
+ * @type Boolean 
+ */
 Xinha.is_mac       = (Xinha.agt.indexOf("mac") != -1);
 /** Browser is Microsoft Internet Explorer Mac
-@type string 
-*/
+ * @type Boolean 
+ */
 Xinha.is_mac_ie = (Xinha.is_ie && Xinha.is_mac);
 /** Browser is Microsoft Internet Explorer Windows
-@type string 
-*/
+ * @type Boolean 
+ */
 Xinha.is_win_ie = (Xinha.is_ie && !Xinha.is_mac);
 /** Browser engine is Gecko (Mozilla), applies also to Safari and Opera which work
  *  largely similar.
-@type string 
-*/
+ *@type Boolean 
+ */
 Xinha.is_gecko  = (navigator.product == "Gecko") || Xinha.is_opera;
+/** 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...)
+ * @type Boolean 
+ */
 Xinha.is_real_gecko = (navigator.product == "Gecko" && !Xinha.is_webkit);
+/** Gecko version 1.9 (or greater)
+ * @type Boolean 
+ */
 Xinha.is_ff3 = Xinha.is_real_gecko && parseInt(navigator.productSub, 10) >= 2007121016;
+/** Gecko version lower than 1.9
+ * @type Boolean 
+ */
 Xinha.is_ff2 = Xinha.is_real_gecko && parseInt(navigator.productSub, 10) < 2007121016;
 
 /** File is opened locally opened ("file://" protocol)
- * @type string
+ * @type Boolean
  * @private
  */
 Xinha.isRunLocally = document.URL.toLowerCase().search(/^file:/) != -1;
 /** Editing is enabled by document.designMode (Gecko, Opera), as opposed to contenteditable (IE)
- * @type string
+ * @type Boolean
  * @private
  */
@@ -490 +509 @@
 Xinha.Config = function()
 {
+  /** The svn revision number 
+   * @type Number
+   */
   this.version = Xinha.version.Revision;
   
@@ -739 +761 @@
    */
   this.outwardHtml = function (html) { return html; };
-
+  
+  /** This setting determines whether or not the editor will be automatically activated and focused when the page loads. 
+   *  If the page contains only a single editor, autofocus can be set to true to focus it. 
+   *  Alternatively, if the page contains multiple editors, autofocus may be set to the ID of the text area of the editor to be focused. 
+   *  For example, the following setting would focus the editor attached to the text area whose ID is "myTextArea": 
+   *  <code>xinha_config.autofocus = "myTextArea";</code>
+   *  Default: <code>false</code>
+   *  @type Boolean|String
+   */
+  this.autofocus = false;
+  
  /** Set to true if you want Word code to be cleaned upon Paste. This only works if 
    * you use the toolbr button to paste, not ^V. This means that due to the restrictions
@@ -6088 +6120 @@
 
 
-/* * These are all the tags for which the end tag is not optional or  forbidden, taken from the list at:
+/** These are all the tags for which the end tag is not optional or  forbidden, taken from the list at:
  *   http: www.w3.org/TR/REC-html40/index/elements.html
  *  
  *  @private
  *  @see Xinha#needsClosingTag
- *  @type {String}
+ *  @type String
  */
 Xinha._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 ";
@@ -6147 +6179 @@
   return string.replace(basere, "");
 };
-/** Removes whitespace from beginning and end of a string
- *  
- *  @returns {String} 
- */
-String.prototype.trim = function()
-{
-  return this.replace(/^\s+/, '').replace(/\s+$/, '');
-};
+
+if (typeof String.prototype.trim != 'function')
+{
+  /** Removes whitespace from beginning and end of a string. Custom implementation for JS engines that don't support it natively
+   *  
+   *  @returns {String} 
+   */
+  String.prototype.trim = function()
+  {
+    return this.replace(/^\s+/, '').replace(/\s+$/, '');
+  };
+}
 
 /** Creates a rgb-style rgb(r,g,b) color from a (24bit) number
@@ -6552 +6588 @@
  */
  
-// mod_security (an apache module which scans incoming requests for potential hack attempts)
-// has a rule which triggers when it gets an incoming Content-Type with a charset
-// see ticket:1028 to try and work around this, if we get a failure in a postback
-// then Xinha._postback_send_charset will be set to false and the request tried again (once)
+/** mod_security (an apache module which scans incoming requests for potential hack attempts)
+ *  has a rule which triggers when it gets an incoming Content-Type with a charset
+ *  see ticket:1028 to try and work around this, if we get a failure in a postback
+ *  then Xinha._postback_send_charset will be set to false and the request tried again (once)
+ *  @type Boolean
+ *  @private
+ */ 
+// 
+// 
+// 
 Xinha._postback_send_charset = true;
+/** Use XMLHTTPRequest to send some some data to the server and do something
+ *  with the getback (asyncronously!)
+ * @param {String} url The address for the HTTPRequest
+ * @param {Function} success A function that is called when an answer is
+ *                           received from the server with the responseText as argument.
+ * @param {Function} failure A function that is called when we fail to receive
+ *                           an answer from the server. We pass it the request object.
+ */
 Xinha._postback = function(url, data, success, failure)
 {
@@ -6610 +6660 @@
 };
 
-/** 
- * Use XMLHTTPRequest to receive some data from the server and do something
+/** Use XMLHTTPRequest to receive some data from the server and do something
  * with the it (asyncronously!)
  * @param {String} url The address for the HTTPRequest
@@ -6798 +6847 @@
   };
 }
-/** Executes a provided function once per array element
+/** Executes a provided function once per array element.
+ *  Custom implementation for JS engines that don't support it natively
  * @source http://developer.mozilla.org/En/Core_JavaScript_1.5_Reference/Global_Objects/Array/ForEach
  * @param {Function} fn Function to execute for each element
@@ -6823 +6873 @@
   };
 }
+/** Returns all elements within a given class name inside an element
+ * @type Array
+ * @param {DomNode|document} el wherein to search
+ * @param {Object} className
+ */
 Xinha.getElementsByClassName = function(el,className)
 {

trunk/modules/Dialogs/XinhaDialog.js

@@ -26 +26 @@
 
 /** Xinha Dialog
- *
- *
- * @param editor Xinha object    
- * @param html string 
- * @param localizer string the "context" parameter for Xinha._lc(), typically the name of the plugin
- * @param size object with two possible properties of the size: width & height as int, where height is optional
- * @param options dictionary with optional boolean attributes 'modal', 'closable', 'resizable', and 'centered', as well as integer attribute 'layer'
+ *  
+ * @constructor
+ * @version $LastChangedRevision$ $LastChangedDate$
+ * @param {Xinha} editor Xinha object    
+ * @param {String} html string The HTML for the dialog's UI
+ * @param {String} localizer string the "context" parameter for Xinha._lc(), typically the name of the plugin
+ * @param {Object} size object with two possible properties of the size: width & height as int, where height is optional
+ * @param {Object} options dictionary with optional boolean attributes 'modal', 'closable', 'resizable', and 'centered', as well as integer attribute 'layer'
+
  */
 Xinha.Dialog = function(editor, html, localizer, size, options)
 {
   var dialog = this;
+  
+  /** Used for dialog.getElementById()
+   * @type Object
+   * @private
+   */
   this.id    = { };
+  /** Used for dialog.getElementById()
+   * @type Object
+   * @private
+   */
   this.r_id  = { }; // reverse lookup id
+  /** The calling Xinha instance
+   * @type Xinha
+   * @private
+   */
   this.editor   = editor;
+  /** 
+   * @private
+   * @type Document
+   */
   this.document = document;
+  /** Object with width, height as numbers
+   * @type Object
+   */
+  
   this.size = size;
+  /** 
+   * @type Boolean
+   * @private
+   */
   this.modal = (options && options.modal === false) ? false : true;
+  /** 
+   * @type Boolean
+   * @private
+   */
   this.closable = (options && options.closable === false) ? false : true;
+  /** 
+   * @type Boolean
+   * @private
+   */
   this.resizable = (options && options.resizable === false) ? false : true;
+  /** 
+   * @type Number
+   * @private
+   */
   this.layer = (options && options.layer) ? options.layer : 0;
+  /** 
+   * @type Boolean
+   * @private
+   */
   this.centered = (options && options.centered === true) ? true : false;
+  /** 
+   * @type Boolean
+   * @private
+   */
   this.closeOnEscape = (options && options.closeOnEscape === true) ? true : false;
-
+  
+  /** The div that is the actual dialog
+   *  @type DomNode
+   */
+  this.rootElem = null;
+  
+  /** 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
+   *  @type DomNode
+   */
+  this.captionBar = null;
+  /** This div contains the content
+   *  @type DomNode
+   */
+  this.main = null;
+  
+  /** Each dialog has a background
+   *  @type DomNode
+   *  @private
+   */
+  this.background = null;
+  /** 
+   * @type Boolean
+   * @private
+   */
+  this.centered = null;
+  /** 
+   * @type Boolean
+   * @private
+   */
+  this.greyout = null;
+  
+  /** 
+   * @type DomNode
+   * @private
+   */
+  this.buttons = null;
+  /** 
+   * @type DomNode
+   * @private
+   */
+  this.closer = null;
+  /** 
+   * @type DomNode
+   * @private
+   */
+  this.icon = null;
+  /** 
+   * @type DomNode
+   * @private
+   */
+  this.resizer = null;
+  /** 
+   * @type Number
+   * @private
+   */
+  this.initialZ = null;
+  
   /* Check global config to see if we should override any of the above options
     If a global option is set, it will apply to all dialogs, regardless of their
@@ -152 +255 @@
 
   document.body.appendChild(backG);
+
   this.background = backG;
 
@@ -326 +430 @@
 
 };
-
+/** This function is called when the dialog is resized. 
+ *  By default it does nothing, but you can override it in your Xinha.Dialog object e.g. to resize elements within you Dialog.
+ *  Example:<br />
+ *  <code>
+ *  var dialog = this.dialog; //The plugin's dialog instance;
+ *  dialog.onresize = function() 
+ *  {
+ *    var el = dialog.getElementById('foo');
+ *    el.style.width = dialog.width;
+ *  }
+ *  </code>
+ */
 Xinha.Dialog.prototype.onresize = function()
 {
   return true;
 };
-
+/** This function shows the dialog and populates form elements with values.
+ * Example:<br />
+ * Given your dialog contains an input element like <code>&lt;input name="[myInput]" type="text" /&gt;</code>
+ * <code>
+ *  var dialog = this.dialog; //The plugin's dialog instance;
+ *  var values = {myInput : 'My input value'}
+ *  dialog.show(values);
+ *  </code>
+ *  @see #setValues
+ *  @param {Object} values Object indexed by names of input elements
+ */
 Xinha.Dialog.prototype.show = function(values)
 {
@@ -489 +614 @@
   this.dialogShown = true;
 };
-
+/** Hides the dialog and returns an object with the valuse of form elements
+ * @see #getValues
+ * @type Object
+ */
 Xinha.Dialog.prototype.hide = function()
 {
@@ -538 +666 @@
   return this.getValues();
 };
-
+/** Shows/hides the dialog
+ * 
+ */
 Xinha.Dialog.prototype.toggle = function()
 {
@@ -550 +680 @@
   }
 };
+/** Reduces the dialog to the size of the caption bar
+ * 
+ */
 Xinha.Dialog.prototype.collapse = function()
 {
@@ -564 +697 @@
 };
 /** Equivalent to document.getElementById. You can't use document.getElementById because id's are dynamic to avoid id clashes between plugins
- * @type {Element}
+ * @type DomNode
  * @param {String} id
  */
@@ -572 +705 @@
 };
 /** Equivalent to document.getElementByName. You can't use document.getElementByName because names are dynamic to avoid name clashes between plugins
- * @type {Array}
+ * @type Array
  * @param {String} name
  */
@@ -581 +714 @@
 };
 /** Return all elements in the dialog that have the given class
- * @type {Array} 
+ * @type Array 
  * @param {String} className
  */
@@ -589 +722 @@
 };
 
+/** Initiates dragging
+ * @private
+ * @param {Object} ev Mousedown event
+ */
 Xinha.Dialog.prototype.dragStart = function (ev) 
 {
@@ -628 +765 @@
   }
 };
-
+/** Sets the position while dragging
+ * @private
+ * @param {Object} ev Mousemove event
+ */
 Xinha.Dialog.prototype.dragIt = function(ev)
 {
@@ -655 +795 @@
   dialog.posDialog(newPos);
 };
-
+/** Ends dragging
+ * @private
+ * @param {Object} ev Mouseup event
+ */
 Xinha.Dialog.prototype.dragEnd = function(ev)
 {
@@ -693 +836 @@
 
 };
-
+/** Initiates resizing
+ * @private
+ * @param {Object} ev Mousedown event
+ */
 Xinha.Dialog.prototype.resizeStart = function (ev) {
   var dialog = this;
@@ -728 +874 @@
   }
 };
-
+/** Sets the size while resiziong
+ * @private
+ * @param {Object} ev Mousemove event
+ */
 Xinha.Dialog.prototype.resizeIt = function(ev)
 {
@@ -763 +912 @@
   dialog.onresize();
 };
-
+/** Ends resizing
+ * @private
+ * @param {Object} ev Mouseup event
+ */
 Xinha.Dialog.prototype.resizeEnd = function(ev)
 {
@@ -793 +945 @@
   }  
 };
-
+/** Attaches a modeless dialog to a panel on the given side
+ *  Triggers a notifyOf panel_change event
+ *  @param {String} side one of 'left', 'right', 'top', 'bottom'
+ */
 Xinha.Dialog.prototype.attachToPanel = function(side)
 {
@@ -831 +986 @@
   editor.notifyOf('panel_change', {'action':'add','panel':rootElem});
 };
-
-Xinha.Dialog.prototype.detachFromPanel = function(ev)
+/** Removes a panel dialog from its panel and makes it float
+ * 
+ */
+Xinha.Dialog.prototype.detachFromPanel = function()
 {
   var dialog = this;
@@ -869 +1026 @@
   
 };
-
+/** 
+ * @private
+ * @type Object Object with width, height strings incl. "px" for CSS
+ */
 Xinha.Dialog.calcFullBgSize = function()
 {
@@ -876 +1036 @@
   return {width:(page.x > viewport.x  ? page.x : viewport.x )  + "px",height:(page.x > viewport.y ? page.y : viewport.y ) + "px"};
 };
-
+/** Sizes the background to the size of the dialog
+ *  @private
+ */
 Xinha.Dialog.prototype.sizeBgToDialog = function()
 {
@@ -886 +1048 @@
   bgStyle.height = rootElemStyle.height;
 };
+/** Hides the background
+ *  @private
+ */
 Xinha.Dialog.prototype.hideBackground = function()
 {
@@ -891 +1056 @@
   Xinha.Dialog.fadeOut(this.background);
 };
+/** Shows the background
+ *  @private
+ */
 Xinha.Dialog.prototype.showBackground = function()
 {
@@ -896 +1064 @@
   Xinha.Dialog.fadeIn(this.background,70);
 };
+/** Positions the background
+ *  @private
+ *  @param {Object} pos Object with top, left strings incl. "px" for CSS
+ */
 Xinha.Dialog.prototype.posBackground = function(pos)
 {
@@ -904 +1076 @@
   }
 };
+/** Resizes the background
+ *  @private
+ *  @param {Object} size Object with width, height strings incl. "px" for CSS
+ */
 Xinha.Dialog.prototype.resizeBackground = function(size)
 {
@@ -912 +1088 @@
   }
 };
+/** Positions the dialog
+ *  @param {Object} pos Object with top, left strings incl. "px" for CSS
+ */
 Xinha.Dialog.prototype.posDialog = function(pos)
 {
@@ -918 +1097 @@
   st.top  = pos.top;
 };
+/** Resizes the dialog
+ * 
+ * @param {Object} size Object with width, height strings incl. "px" for CSS
+ */
 Xinha.Dialog.prototype.sizeDialog = function(size)
 {
@@ -928 +1111 @@
   this.main.style.width = (width > 10) ? width : 10 + 'px';
 };
+/** Sets the values like Xinha.Dialog.prototype.show(values)
+ * @see #show
+ * @param {Object} values 
+ */
 Xinha.Dialog.prototype.setValues = function(values)
 {
@@ -1002 +1189 @@
 };
 
+/** Retrieves the values like Xinha.Dialog.prototype.hide()
+ * @see #hide
+ * @type Object values 
+ */
 Xinha.Dialog.prototype.getValues = function()
 {
@@ -1097 +1288 @@
   return values;
 };
-
-Xinha.Dialog.prototype.translateHtml = function(html,localizer)
+/** Localizes strings in the dialog.
+ * @private
+ * @param {String} html The HTML to translate
+ * @param {String} localizer Context for translation, usually plugin's name
+ */
+Xinha.Dialog.prototype.translateHtml = function(html, localizer)
 {
   var dialog = this;
@@ -1142 +1337 @@
 /**
  * Fixup links in the elements to allow linking to Xinha resources
+ * @private
  */
 Xinha.Dialog.prototype.fixupDOM = function(root,plugin)