You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@shindig.apache.org by do...@apache.org on 2008/01/19 03:03:42 UTC
svn commit: r613344 - in /incubator/shindig/trunk/features/core: io.js
json.js prefs.js util.js
Author: doll
Date: Fri Jan 18 18:03:40 2008
New Revision: 613344
URL: http://svn.apache.org/viewvc?rev=613344&view=rev
Log:
Restructured the js docs in the public core gadgets files so that they generate nice output with jsdoc toolkit. This required some doc updating as well as a slight change in how the javascript was set up.
This should not have any functional effect so please let me know if anything went wrong with this cl.
(All docs are a wip... many more changes will be forth coming)
Modified:
incubator/shindig/trunk/features/core/io.js
incubator/shindig/trunk/features/core/json.js
incubator/shindig/trunk/features/core/prefs.js
incubator/shindig/trunk/features/core/util.js
Modified: incubator/shindig/trunk/features/core/io.js
URL: http://svn.apache.org/viewvc/incubator/shindig/trunk/features/core/io.js?rev=613344&r1=613343&r2=613344&view=diff
==============================================================================
--- incubator/shindig/trunk/features/core/io.js (original)
+++ incubator/shindig/trunk/features/core/io.js Fri Jan 18 18:03:40 2008
@@ -15,8 +15,10 @@
var gadgets = gadgets || {};
/**
- * Provides remote content retrieval facilities. Available to every gadget.
+ * @fileoverview Provides remote content retrieval facilities.
+ * Available to every gadget.
*/
+
gadgets.io = function() {
/**
* Holds configuration-related data such as proxy urls.
@@ -91,79 +93,76 @@
callback(resp);
}
- /**
- * Retrieves the content at the specified url.
- *
- * @param {String} url The url to fetch.
- * @param {Function} callback Invoked when the request completes. The
- * response object will be passed in as a parameter.
- * @param {Object} opt_params Optional parameters. May be modified.
- *
- * <pre>
- * gadgets.IO.makeRequest(url, fn, {type: gadgets.IO.ContentType.JSON});
- * </pre>
- */
- function makeRequest(url, callback, opt_params) {
- var xhr = makeXhr();
- var params = opt_params || {};
- var newUrl = config.jsonProxyUrl.replace("%url%", encodeURIComponent(url));
- xhr.open(params.postData ? "POST" : "GET", newUrl, true);
- if (callback) {
- xhr.onreadystatechange = gadgets.util.makeClosure(null, processResponse,
- url,
- callback,
- params,
- xhr);
- }
- xhr.send(params.postData);
- }
-
- /**
- * Converts an input object into a url encoded data string (key=value&...)
- *
- * @param {Object} fields The post fields you wish to encode
- * @return {String} The processed post data. This will include a trialing
- * ampersand (&).
- */
- function encodeValues(fields) {
- var buf = [];
- for (var i in fields) {
- buf.push(encodeURIComponent(i));
- buf.push("=");
- buf.push(encodeURIComponent(fields[i]));
- buf.push("&");
- }
- return buf.join("");
- }
+ return /** @scope gadgets.io */ {
+ /**
+ * Retrieves the content at the specified url.
+ *
+ * Example:
+ * <pre>
+ * gadgets.IO.makeRequest(url, fn, {type: gadgets.IO.ContentType.JSON});
+ * </pre>
+ *
+ * @param {String} url The url to fetch.
+ * @param {Function} callback Invoked when the request completes. The
+ * response object will be passed in as a parameter.
+ * @param {Object} opt_params Optional parameters. May be modified.
+ */
+ makeRequest : function (url, callback, opt_params) {
+ var xhr = makeXhr();
+ var params = opt_params || {};
+ var newUrl = config.jsonProxyUrl.replace("%url%",
+ encodeURIComponent(url));
+ xhr.open(params.postData ? "POST" : "GET", newUrl, true);
+ if (callback) {
+ xhr.onreadystatechange = gadgets.util.makeClosure(null,
+ processResponse, url, callback, params, xhr);
+ }
+ xhr.send(params.postData);
+ },
- /**
- * @param {String} url The url to get the proxy url for.
- * @return {String} The proxied version of the url.
- */
- function getProxyUrl(url) {
- return config.proxyUrl.replace("%url%", encodeURIComponent(url));
- }
+ /**
+ * Converts an input object into a url encoded data string (key=value&...)
+ *
+ * @param {Object} fields The post fields you wish to encode
+ * @return {String} The processed post data. This will include a trialing
+ * ampersand (&).
+ */
+ encodeValues : function (fields) {
+ var buf = [];
+ for (var i in fields) {
+ buf.push(encodeURIComponent(i));
+ buf.push("=");
+ buf.push(encodeURIComponent(fields[i]));
+ buf.push("&");
+ }
+ return buf.join("");
+ },
- /**
- * Initializes fetchers
- * @param {Object} configuration Configuration settings.
- * Required:
- * - proxyUrl: The url for content proxy requests. Include %url%
- * as a placeholder for the actual url.
- * - jsonProxyUrl: The url for dynamic proxy requests. Include %url%
- * as a placeholder for the actual url.
- */
- function init(configuration) {
- config = configuration;
- if (!config.proxyUrl || !config.jsonProxyUrl) {
- throw new Error("proxyUrl and jsonProxyUrl are required.");
+ /**
+ * Gets the proxy version of the passed in url.
+ *
+ * @param {String} url The url to get the proxy url for.
+ * @return {String} The proxied version of the url.
+ */
+ getProxyUrl : function (url) {
+ return config.proxyUrl.replace("%url%", encodeURIComponent(url));
+ },
+
+ /**
+ * Initializes fetchers
+ *
+ * @param {Object} configuration Configuration settings.
+ * Required:
+ * - proxyUrl: The url for content proxy requests. Include %url%
+ * as a placeholder for the actual url.
+ * - jsonProxyUrl: The url for dynamic proxy requests. Include %url%
+ * as a placeholder for the actual url.
+ */
+ init : function (configuration) {
+ config = configuration;
+ if (!config.proxyUrl || !config.jsonProxyUrl) {
+ throw new Error("proxyUrl and jsonProxyUrl are required.");
+ }
}
- }
-
- return {
- makeRequest: makeRequest,
- getProxyUrl: getProxyUrl,
- encodeValues: encodeValues,
- init: init
};
}();
Modified: incubator/shindig/trunk/features/core/json.js
URL: http://svn.apache.org/viewvc/incubator/shindig/trunk/features/core/json.js?rev=613344&r1=613343&r2=613344&view=diff
==============================================================================
--- incubator/shindig/trunk/features/core/json.js (original)
+++ incubator/shindig/trunk/features/core/json.js Fri Jan 18 18:03:40 2008
@@ -19,18 +19,22 @@
SOFTWARE.
*/
-/*
- The global object JSON contains two methods.
-
- JSON.stringify(value) takes a JavaScript value and produces a JSON text.
- The value must not be cyclical.
-
- JSON.parse(text) takes a JSON text and produces a JavaScript value. It will
- return false if there is an error.
+/**
+ * @fileoverview
+ * The global object JSON contains two methods.
+ *
+ * JSON.stringify(value) takes a JavaScript value and produces a JSON text.
+ * The value must not be cyclical.
+ *
+ * JSON.parse(text) takes a JSON text and produces a JavaScript value. It will
+ * return false if there is an error.
*/
var gadgets = gadgets || {};
+/**
+ * @scope gadgets.JSON
+ */
gadgets.JSON = function () {
var m = {
'\b': '\\b',
@@ -45,9 +49,11 @@
'boolean': function (x) {
return String(x);
},
+ /** @private */
number: function (x) {
return isFinite(x) ? String(x) : 'null';
},
+ /** @private */
string: function (x) {
if (/["\\\x00-\x1f]/.test(x)) {
x = x.replace(/([\x00-\x1f\\"])/g, function(a, b) {
@@ -63,6 +69,7 @@
}
return '"' + x + '"';
},
+ /** @private */
object: function (x) {
if (x) {
var a = [], b, f, i, l, v;
@@ -114,9 +121,13 @@
return {
copyright: '(c)2005 JSON.org',
license: 'http://www.JSON.org/license.html',
-/*
- Stringify a JavaScript value, producing a JSON text.
-*/
+
+ /**
+ * Stringifies a JavaScript value, producing a JSON text.
+ *
+ * @param {Object} v The object to stringify.
+ * @return {String} The stringified object.
+ */
stringify: function (v) {
var f = s[typeof v];
if (f) {
@@ -127,10 +138,16 @@
}
return null;
},
-/*
- Parse a JSON text, producing a JavaScript value.
- It returns false if there is a syntax error.
-*/
+
+ /**
+ * Parses a JSON text, producing a JavaScript value.
+ * It returns false if there is a syntax error.
+ *
+ * @param {String} text The string to transform into an object. Usually
+ * the result of a previous stringify call.
+ * @return {Object} The object parsed from the passed in text. False if
+ * an error occurred.
+ */
parse: function (text) {
try {
return !(/[^,:{}\[\]0-9.\-+Eaeflnr-u \n\r\t]/.test(
Modified: incubator/shindig/trunk/features/core/prefs.js
URL: http://svn.apache.org/viewvc/incubator/shindig/trunk/features/core/prefs.js?rev=613344&r1=613343&r2=613344&view=diff
==============================================================================
--- incubator/shindig/trunk/features/core/prefs.js (original)
+++ incubator/shindig/trunk/features/core/prefs.js Fri Jan 18 18:03:40 2008
@@ -13,6 +13,8 @@
*/
/**
+ * @fileoverview
+ *
* Provides access to user prefs, module dimensions, and messages.
*
* Clients can access their preferences by constructing an instance of
@@ -62,44 +64,48 @@
/**
* Adds a new user preference to the stored set for the given module id.
*
- * @param {Number | String} moduleId The module id to add the pref for.
+ * @param {String | Number} moduleId The module id to add the pref for.
* @param {String} key The key to add. May be an object where keys = key and
* values = value.
- * @param {String} value The value for the key. Optional.
+ * @param {String} opt_value An optional value used to set the value of the
+ * key.
*/
- function setPref(moduleId, key, value) {
+ function setPref(moduleId, key, opt_value) {
var module = getModuleData(moduleId);
if (typeof key !== "string") {
for (var i in key) {
module.prefs[i] = key[i];
}
} else {
- module.prefs[key] = value;
+ module.prefs[key] = opt_value;
}
}
/**
* Adds a new message to the stored set for the given module id.
*
- * @param {Number | String} moduleId The module id to add the pref for.
+ * @param {String | Number} moduleId The module id to add the pref for.
* @param {String | Object} key The key to add. May be an object where keys =
* key and values = value.
- * @param {String} value The value for the key. Optional.
+ * @param {String} opt_value An optional value used to set the value of the
+ * key.
*/
- function setMsg(moduleId, key, value) {
+ function setMsg(moduleId, key, opt_value) {
var module = getModuleData(moduleId);
if (typeof key !== "string") {
for (var i in key) {
module.msgs[i] = key[i];
}
} else {
- module.msgs[key] = value;
+ module.msgs[key] = opt_value;
}
}
var defaultModuleId = 0;
/**
+ * Sets the default module id.
+ *
* @param {String | Number} moduleId The module id to set as default.
*/
function setDefaultModuleId(moduleId) {
@@ -107,6 +113,8 @@
}
/**
+ * Gets the default module id.
+ *
* @return {String | Number} The default module id.
*/
function getDefaultModuleId() {
@@ -114,8 +122,10 @@
}
/**
- * @param {Number | String} moduleId The module id to set the language for.
- * @param {String} language The language to use.
+ * Sets the default language for this module id.
+ *
+ * @param {String | Number} moduleId The module id to set the language for.
+ * @param {String} language The language code as an ISO 639-1 code.
*/
function setLanguage(moduleId, language) {
getModuleData(moduleId).language = language;
@@ -123,20 +133,24 @@
/**
* Sets the default country for this module id.
+ *
+ * @param {String | Number} moduleId The id of the gagdet instance.
+ * @param {String} country The country code as an ISO 3166-1 alpha-2 code.
*/
function setCountry(moduleId, country) {
getModuleData(moduleId).country = country;
}
- // Export public API.
+ // Export public API for the gadget container code. Gadget authors should
+ // not use this class.
return {
- setPref:setPref,
- setMsg:setMsg,
- setCountry:setCountry,
- setLanguage:setLanguage,
- getModuleData:getModuleData,
- setDefaultModuleId:setDefaultModuleId,
- getDefaultModuleId:getDefaultModuleId
+ setPref: setPref,
+ setMsg: setMsg,
+ setCountry: setCountry,
+ setLanguage: setLanguage,
+ getModuleData: getModuleData,
+ setDefaultModuleId: setDefaultModuleId,
+ getDefaultModuleId: getDefaultModuleId
};
}();
@@ -160,6 +174,8 @@
* Static pref parser. Parses all parameters from the url and stores them
* for later use when creating a new gadgets.Prefs object.
* You should only ever call this if you are a type=url gadget.
+ *
+ * @param {String | Number} moduleId The id of the gagdet instance.
*/
gadgets.Prefs.parseUrl = function(moduleId) {
var prefs = {};
@@ -192,7 +208,8 @@
/**
* Internal helper for pref fetching.
* @param {String} key The key to fetch.
- * @return {String}
+ * @return {Object?} The preference.
+ * @private
*/
gadgets.Prefs.prototype.getPref_ = function(key) {
var val = this.prefs_[key];
@@ -200,7 +217,7 @@
}
/**
- * Retrieves the named preference as a string.
+ * Retrieves a string preference.
* @param {String} key The preference to fetch.
* @return {String} The preference. If not set, an empty string.
*/
@@ -210,7 +227,7 @@
};
/**
- * Retrieves the named preference as an integer.
+ * Retrieves an integer preference.
* @param {String} key The preference to fetch.
* @return {Number} The preference. If not set, 0.
*/
@@ -220,7 +237,7 @@
};
/**
- * Retrieve the named preference as a floating point value.
+ * Retrieves a floating point preference.
* @param {String} key The preference to fetch.
* @return {Number} The preference. If not set, 0.
*/
@@ -230,7 +247,7 @@
};
/**
- * Retrieves the named preference as a boolean.
+ * Retrieves a boolean preference.
* @param {String} key The preference to fetch.
* @return {Boolean} The preference. If not set, false.
*/
@@ -244,15 +261,20 @@
/**
* Stores a preference.
- * @param {String | Object} key The pref to store.
- * @param {String} val The values to store.
+ * Note: If the gadget needs to store an Array it should use setArray instead of
+ * this call.
+ * Note: The gadget must require the feature setprefs in
+ * order to use this call.
+ *
+ * @param {String} key The pref to store.
+ * @param {Object} val The values to store.
*/
gadgets.Prefs.prototype.set = function(key, value) {
throw new Error("setprefs feature required to make this call.");
};
/**
- * Retrieves the named preference as an array.
+ * Retrieves an array preference.
* @param {String} key The preference to fetch.
* @return {Array.<String>} The preference. If not set, an empty array.
* UserPref values that were not declared as lists will be treated as
@@ -272,9 +294,11 @@
};
/**
- * Stores a preference from the given list.
+ * Stores an array preference. The gadget must require the feature setprefs in
+ * order to use this call.
+ *
* @param {String} key The pref to store.
- * @param {Array.<String | Number>} val The values to store.
+ * @param {Array} val The values to store.
*/
gadgets.Prefs.prototype.setArray = function(key, val) {
throw new Error("setprefs feature required to make this call.");
@@ -291,10 +315,13 @@
};
/**
+ * <p>
* The regex pulls out the text before and after the positional argument
* and digs down for a possible example value in case no actual value
* was provided. It is used by the function getMsgFormatted.
+ * </p>
*
+ * <pre>
* Example: "Foo <ph name="number"><ex>bar</ex>%1</ph> baz."
* 0 = "Foo <ph name="number"><ex>bar</ex>%1</ph> baz." : match for the
* whole regex.
@@ -310,9 +337,11 @@
*
* 5 = " baz." : matches final (.*) in regex
*
- * TODO: this may need to be a single line even though it's > 80 characters
- * because some browsers may not properly interepret the line continuation.
+ * </pre>
+ * @private
*/
+ // TODO: this may need to be a single line even though it's > 80 characters
+ // because some browsers may not properly interepret the line continuation.
gadgets.Prefs.MESSAGE_SUBST_REGEX =
/(.*)(\<ph.*?\>\s*(\<ex\>(.*?)\<\/ex\>)?\s*%1\s*\<\/ph\>)(.*)/;
@@ -323,7 +352,7 @@
* Eventually we may provide controls to return different default messages.
*
* @param {String} key The message to fetch.
- * @param {String} subst ????
+ * @param {String} opt_subst An optional string to substitute into the message.
* @return {String} The formatted string.
*/
gadgets.Prefs.prototype.getMsgFormatted = function(key, opt_subst) {
@@ -342,6 +371,8 @@
};
/**
+ * Gets the current country, returned as ISO 3166-1 alpha-2 code.
+ *
* @return {String} The country for this module instance.
*/
gadgets.Prefs.prototype.getCountry = function() {
@@ -349,6 +380,9 @@
};
/**
+ * Gets the current language the gadget should use when rendering, returned as a
+ * ISO 639-1 language code.
+ *
* @return {String} The language for this module instance.
*/
gadgets.Prefs.prototype.getLang = function() {
@@ -356,6 +390,8 @@
};
/**
+ * Gets the module id for the current instance.
+ *
* @return {String | Number} The module id for this module instance.
*/
gadgets.Prefs.prototype.getModuleId = function() {
Modified: incubator/shindig/trunk/features/core/util.js
URL: http://svn.apache.org/viewvc/incubator/shindig/trunk/features/core/util.js?rev=613344&r1=613343&r2=613344&view=diff
==============================================================================
--- incubator/shindig/trunk/features/core/util.js (original)
+++ incubator/shindig/trunk/features/core/util.js Fri Jan 18 18:03:40 2008
@@ -15,7 +15,7 @@
var gadgets = gadgets || {};
/**
- * General purpose utilities.
+ * @fileoverview General purpose utilities that gadgets can use.
*/
gadgets.util = function() {
/**
@@ -40,113 +40,112 @@
}
var parameters = null;
-
- /**
- * @return {Object} Parameters passed into the query string.
- */
- function getUrlParameters() {
- if (parameters !== null) {
- return parameters;
- }
- parameters = {};
- var pairs = parseUrlParams();
- var unesc = window.decodeURIComponent ? decodeURIComponent : unescape;
- for (var i = 0, j = pairs.length; i < j; ++i) {
- var pos = pairs[i].indexOf('=');
- if (pos === -1) {
- continue;
- }
- var argName = pairs[i].substring(0, pos);
- var value = pairs[i].substring(pos + 1);
- // difference to IG_Prefs, is that args doesn't replace spaces in argname:
- // unclear on if it should do: argname = argname.replace(/\+/g, " ");
- value = value.replace(/\+/g, " ");
- parameters[argName] = unesc(value);
- }
- return parameters;
- }
-
- /**
- * Creates a closure which is suitable for passing as a callback.
- *
- * @param {Object} scope The execution scope. May be null if there is no
- * need to associate a specific instance of an object with this callback.
- * @param {Function} callback The callback to invoke when this is run.
- * any arguments passed in will be passed after your initial arguments.
- * @param {Object} var_args Any number of arguments may be passed to the
- * callback. They will be received in the order they are passed in.
- */
- function makeClosure(scope, callback, var_args) {
- // arguments isn't a real array, so we copy it into one.
- var tmpArgs = [];
- for (var i = 2, j = arguments.length; i < j; ++i) {
- tmpArgs.push(arguments[i]);
- }
- return function() {
- // append new arguments.
- for (var i = 0, j = arguments.length; i < j; ++i) {
- tmpArgs.push(arguments[i]);
- }
- callback.apply(scope, tmpArgs);
- };
- }
-
var features = {};
-
- /**
- * @param {String} feature The feature to get parameters for.
- * @return {Object} The parameters for the given feature, or null.
- */
- function getFeatureParameters(feature) {
- return typeof features[feature] === "undefined" ? null : features[feature];
- }
-
- /**
- * @param {String} feature The feature to test for.
- * @return {Boolean} True if the feature is supported.
- */
- function hasFeature(feature) {
- return typeof features[feature] === "undefined";
- }
-
var onLoadHandlers = [];
- /**
- * Registers an onload handler.
- * @param {Function} callback The handler to run.
- */
- function registerOnLoadHandler(callback) {
- onLoadHandlers.push(callback);
- }
+ return /** @scope gadgets.util */ {
- /**
- * Runs all functions registered via registerOnLoadHandler.
- */
- function runOnLoadHandlers() {
- for (var i = 0, j = onLoadHandlers.length; i < j; ++i) {
- onLoadHandlers[i]();
- }
- }
+ /**
+ * Gets the url parameters.
+ *
+ * @return {Object} Parameters passed into the query string.
+ */
+ getUrlParameters : function () {
+ if (parameters !== null) {
+ return parameters;
+ }
+ parameters = {};
+ var pairs = parseUrlParams();
+ var unesc = window.decodeURIComponent ? decodeURIComponent : unescape;
+ for (var i = 0, j = pairs.length; i < j; ++i) {
+ var pos = pairs[i].indexOf('=');
+ if (pos === -1) {
+ continue;
+ }
+ var argName = pairs[i].substring(0, pos);
+ var value = pairs[i].substring(pos + 1);
+ // difference to IG_Prefs, is that args doesn't replace spaces in
+ // argname. Unclear on if it should do:
+ // argname = argname.replace(/\+/g, " ");
+ value = value.replace(/\+/g, " ");
+ parameters[argName] = unesc(value);
+ }
+ return parameters;
+ },
- /**
- * @param {Object} featureData The features that are supported, and
- * their parameters.
- */
- function init(featureData) {
- features = featureData;
- }
+ /**
+ * Creates a closure which is suitable for passing as a callback.
+ *
+ * @param {Object} scope The execution scope. May be null if there is no
+ * need to associate a specific instance of an object with this
+ * callback.
+ * @param {Function} callback The callback to invoke when this is run.
+ * any arguments passed in will be passed after your initial arguments.
+ * @param {Object} var_args Any number of arguments may be passed to the
+ * callback. They will be received in the order they are passed in.
+ */
+ makeClosure : function (scope, callback, var_args) {
+ // arguments isn't a real array, so we copy it into one.
+ var tmpArgs = [];
+ for (var i = 2, j = arguments.length; i < j; ++i) {
+ tmpArgs.push(arguments[i]);
+ }
+ return function() {
+ // append new arguments.
+ for (var i = 0, j = arguments.length; i < j; ++i) {
+ tmpArgs.push(arguments[i]);
+ }
+ callback.apply(scope, tmpArgs);
+ };
+ },
+
+ /**
+ * Gets the feature parameters.
+ *
+ * @param {String} feature The feature to get parameters for.
+ * @return {Object} The parameters for the given feature, or null.
+ */
+ getFeatureParameters : function (feature) {
+ return typeof features[feature] === "undefined"
+ ? null : features[feature];
+ },
+
+ /**
+ * Returns whether the current feature is supported.
+ *
+ * @param {String} feature The feature to test for.
+ * @return {Boolean} True if the feature is supported.
+ */
+ hasFeature : function (feature) {
+ return typeof features[feature] === "undefined";
+ },
+
+ /**
+ * Registers an onload handler.
+ * @param {Function} callback The handler to run.
+ */
+ registerOnLoadHandler : function (callback) {
+ onLoadHandlers.push(callback);
+ },
+
+ /**
+ * Runs all functions registered via registerOnLoadHandler.
+ * @private Only to be used by the container, not gadgets.
+ */
+ runOnLoadHandlers : function () {
+ for (var i = 0, j = onLoadHandlers.length; i < j; ++i) {
+ onLoadHandlers[i]();
+ }
+ },
- // Export public API.
- return {
- getUrlParameters: getUrlParameters,
- getFeatureParameters: getFeatureParameters,
- hasFeature: hasFeature,
- makeClosure: makeClosure,
- registerOnLoadHandler: registerOnLoadHandler,
-
- // only used by container
- runOnLoadHandlers: runOnLoadHandlers,
- init: init
+ /**
+ * @param {Object} featureData The features that are supported, and
+ * their parameters.
+ * @private Only to be used by the container, not gadgets.
+ */
+ init : function (featureData) {
+ features = featureData;
+ }
};
}();