You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tapestry.apache.org by jk...@apache.org on 2006/10/01 00:56:35 UTC
svn commit: r451693 - in
/tapestry/tapestry4/trunk/tapestry-framework/src/js/tapestry: core.js
event.js
Author: jkuhnert
Date: Sat Sep 30 15:56:35 2006
New Revision: 451693
URL: http://svn.apache.org/viewvc?view=rev&rev=451693
Log:
Checking in documentation changes made to fit NaturalDocs.
Modified:
tapestry/tapestry4/trunk/tapestry-framework/src/js/tapestry/core.js
tapestry/tapestry4/trunk/tapestry-framework/src/js/tapestry/event.js
Modified: tapestry/tapestry4/trunk/tapestry-framework/src/js/tapestry/core.js
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/tapestry-framework/src/js/tapestry/core.js?view=diff&rev=451693&r1=451692&r2=451693
==============================================================================
--- tapestry/tapestry4/trunk/tapestry-framework/src/js/tapestry/core.js (original)
+++ tapestry/tapestry4/trunk/tapestry-framework/src/js/tapestry/core.js Sat Sep 30 15:56:35 2006
@@ -7,24 +7,34 @@
dojo.require("dojo.widget.Dialog");
dojo.require("dojo.html.style");
+/**
+ * package: tapestry
+ * Provides the core functionality for the Tapestry javascript package libraries.
+ *
+ * Most of the functions in here are related to initiating and parsing IO
+ * requests.
+ */
tapestry={
- version:"4.1", // tapestry script version
- scriptInFlight:false, // whether or not javascript is currently being eval'd
+ // property: version
+ // The current client side library version, usually matching the current java library version. (ie 4.1, etc..)
+ version:"4.1",
+ scriptInFlight:false, // whether or not javascript is currently being eval'd, default false
ScriptFragment:'(?:<script.*?>)((\n|.|\r)*?)(?:<\/script>)', // regexp for script elements
/**
- * Global XHR bind function for tapestry internals. The
- * error/load functions defined in this package are used to handle
+ * Function: bind
+ *
+ * Core XHR bind function for tapestry internals. The
+ * <error>/<load> functions defined in this package are used to handle
* load/error of dojo.io.bind.
*
- * @param url
- * The url to bind the request to.
- * @param content
- * A properties map of optional extra content to send.
- * @param json
- * Boolean, optional parameter specifying whether or not to create a json request.
- * If not specified the default is to use XHR.
+ * Parameters:
+ *
+ * url - The url to bind the request to.
+ * content - A properties map of optional extra content to send.
+ * json - Boolean, optional parameter specifying whether or not to create a
+ * json request. If not specified the default is to use XHR.
*/
bind:function(url, content, json){
var parms = {
@@ -50,14 +60,34 @@
},
/**
- * Global error handling function for dojo.io.bind requests.
+ * Function: error
+ *
+ * Global error handling function for dojo.io.bind requests. This function is mapped
+ * as the "error:functionName" part of a request in the dojo.io.bind arguments
+ * in <tapestry.bind> calls.
+ *
+ * See Also:
+ * <tapestry.bind>
*/
error:function(type, exception, http, kwArgs){
dojo.log.exception("Error received in IO response.", exception);
},
/**
- * Global load handling function for dojo.io.bind requests.
+ * Function: load
+ *
+ * Global load handling function for dojo.io.bind requests. This isn't typically
+ * called directly by anything, but passed in as the "load" argument to
+ * dojo.io.bind when making IO requests as the function that will handle the
+ * return response.
+ *
+ * Parameters:
+ * type - Type of request.
+ * data - The data returned, depending on the request type might be an xml document /
+ * plaintext / json / etc.
+ * http - The http object used in request, like XmlHttpRequest.
+ * kwArgs - The original set of arguments passed into dojo.io.bind({arg:val,arg1:val2}).
+ *
*/
load:function(type, data, http, kwArgs){
dojo.log.debug("Response recieved.");
@@ -125,6 +155,19 @@
}
},
+ /**
+ * Function: loadContent
+ *
+ * Used by <tapestry.load> when handling xml responses to iterate over the tapestry
+ * specific xml response and appropriately load all content types / perform animations /
+ * execute scripts in the proper order / etc..
+ *
+ * Parameters:
+ * id - The element id that this content should be applied to in the existing document.
+ * node - The node that this new content will be applied to.
+ * element - The incoming xml node containing rules/content to apply to this node.
+ *
+ */
loadContent:function(id, node, element){
if (element.childNodes && element.childNodes.length > 0) {
for (var i = 0; i < element.childNodes.length; i++) {
@@ -150,6 +193,17 @@
node.innerHTML=tapestry.html.getContentAsString(element);
},
+ /**
+ * Function: loadScriptContent
+ *
+ * Manages loading javascript content for a specific incoming xml element.
+ *
+ * Parameters:
+ * element - The element to parse javascript statements from and execute.
+ * async - Whether or not to process the script content asynchronously, meaning
+ * whether or not to execute the script in a block done in a setTimeout call
+ * so as to avoid IE specific issues.
+ */
loadScriptContent:function(element, async){
if (typeof async == "undefined") { async = true; }
@@ -194,6 +248,17 @@
tapestry.scriptInFlight = false;
},
+ /**
+ * Function: loadScriptFromUrl
+ *
+ * Takes a url string and loads the javascript it points to as a normal
+ * document head script include section. ie:
+ *
+ * : <script type="text/javascript" src="http://localhost/js/foo.js"></script>
+ *
+ * Parameters:
+ * url - The url to the script to load into this documents head.
+ */
loadScriptFromUrl:function(url){
var scripts = window.document.getElementsByTagName("script");
for (var i = 0; i < scripts.length; i++) {
@@ -209,6 +274,17 @@
document.getElementsByTagName("head")[0].appendChild(e);
},
+ /**
+ * Function: presentException
+ *
+ * When remote exceptions are caught on the server special xml blocks are returned to
+ * the client when the requests are initiated via async IO. This function takes the incoming
+ * Tapestry exception page content and dumps it into a modal dialog that is presented to the user.
+ *
+ * Parameters:
+ * node - The incoming xml exception node.
+ * kwArgs - The kwArfs used to initiate the original IO request.
+ */
presentException:function(node, kwArgs) {
var excnode=document.createElement("div");
excnode.setAttribute("id", "exceptiondialog");
@@ -234,6 +310,8 @@
},
/**
+ * Function: cleanConnect
+ *
* Utility used to disconnect a previously connected event/function.
*
* This assumes that the incoming function name is being attached to
Modified: tapestry/tapestry4/trunk/tapestry-framework/src/js/tapestry/event.js
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/tapestry-framework/src/js/tapestry/event.js?view=diff&rev=451693&r1=451692&r2=451693
==============================================================================
--- tapestry/tapestry4/trunk/tapestry-framework/src/js/tapestry/event.js (original)
+++ tapestry/tapestry4/trunk/tapestry-framework/src/js/tapestry/event.js Sat Sep 30 15:56:35 2006
@@ -4,18 +4,30 @@
dojo.require("dojo.event.browser");
dojo.require("dojo.dom");
+/**
+ * package: tapestry.event
+ *
+ * Utility functions that handle converting javascript event objects into
+ * a name/value pair format that can be sent to the remote server.
+ */
tapestry.event={
/**
+ * Function: buildEventProperties
+ *
* Takes an incoming browser generated event (like key/mouse events) and
* creates a js object holding the basic values of the event in order for
* it to be submitted to the server.
*
- * @param event The javascript event method is based on, if it isn't a valid
+ * Parameters:
+ *
+ * event - The javascript event method is based on, if it isn't a valid
* browser event it will be ignored.
- * @param props The existing property object to set the values on, if it doesn't
+ * props - The existing property object to set the values on, if it doesn't
* exist one will be created.
- * @return The desired event properties bound to an object. Ie obj.target,obj.charCode, etc..
+ * Returns:
+ *
+ * The desired event properties bound to an object. Ie obj.target,obj.charCode, etc..
*/
buildEventProperties:function(event, props){
if (!dojo.event.browser.isEvent(event)) return {};
@@ -35,8 +47,19 @@
},
/**
+ * Function: buildTargetProperties
+ *
* Generic function to build a properties object populated with
* relevent target data.
+ *
+ * Parameters:
+ *
+ * props - The object that event properties are being set on to return to
+ * the server.
+ * target - The javscript Event.target object that the original event was targeted for.
+ *
+ * Returns:
+ * The original props object passed in, populated with any data found.
*/
buildTargetProperties:function(props, target){
if(!target) { return; }
@@ -49,7 +72,14 @@
},
/**
- * Builds needed target node properties, like the nodes id.
+ * Function: buildNodeProperties
+ *
+ * Builds needed target node properties, like the node's id.
+ *
+ * Parameters:
+ * props - The object that event properties are being set on to return to
+ * the server.
+ * node - The dom node specified as the Event.target in a javascript event.
*/
buildNodeProperties:function(props, node) {
if (node.getAttribute("id")) {