Author: erinnp
Date: Thu Jul 18 17:25:34 2013
New Revision: 1504554
URL: http://svn.apache.org/r1504554
Log:
continuing core jsdoc documentation
Modified:
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/main.js
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_ajax.js
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_api.js
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_log.js
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_providers.js
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_view_manager.js
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_widget.js
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_widget_manager.js
Modified:
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/main.js
URL:
http://svn.apache.org/viewvc/rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/main.js?rev=1504554&r1=1504553&r2=1504554&view=diff
==============================================================================
--- rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/main.js
(original)
+++ rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/main.js
Thu Jul 18 17:25:34 2013
@@ -18,31 +18,40 @@
*/
/**
- * @namespace rave
+ * The rave core module.
+ *
+ * @module rave
+ * @mixes module:rave_event_manager
+ * @mixes module:rave_widget_manager
+ * @mixes module:rave_state_manager
+ * @mixes module:rave_view_manager
*/
define(['underscore', 'core/rave_widget_manager', 'core/rave_api',
'core/rave_widget', 'core/rave_log',
'core/rave_event_manager', 'core/rave_view_manager',
'core/rave_state_manager'],
function (_, widgetManager, api, RegionWidget, log, eventManager,
viewManager, stateManager) {
- var rave = {};
+ var exports = {};
/**
- * @
+ * @see module:rave_api
*/
- rave.api = api;
- rave.RegionWidget = RegionWidget;
- rave.log = log;
+ exports.api = api;
-
- _.extend(rave, eventManager);
- _.extend(rave, viewManager);
- _.extend(rave, widgetManager);
+ /**
+ * @see module:rave_widget
+ */
+ exports.RegionWidget = RegionWidget;
/**
- * @mixes rave_state_manager
+ * @see module:rave_log
*/
- _.extend(rave, stateManager);
+ exports.log = log;
+
+ _.extend(exports, eventManager);
+ _.extend(exports, viewManager);
+ _.extend(exports, widgetManager);
+ _.extend(exports, stateManager);
- return rave;
+ return exports;
}
)
Modified:
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_ajax.js
URL:
http://svn.apache.org/viewvc/rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_ajax.js?rev=1504554&r1=1504553&r2=1504554&view=diff
==============================================================================
---
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_ajax.js
(original)
+++
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_ajax.js
Thu Jul 18 17:25:34 2013
@@ -28,7 +28,6 @@ define(['jquery'], function ($) {
* By default rave uses jquery as its ajax library. If you want to use
another ajax library overlay this file
* and return a function that conforms with the api of jquery's ajax()
function.
* @exports rave_ajax
- * @borrows $.ajax as rave_ajax
* @see {@link http://api.jquery.com/jQuery.ajax/ $.ajax}
*/
var ajax = $.ajax;
Modified:
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_api.js
URL:
http://svn.apache.org/viewvc/rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_api.js?rev=1504554&r1=1504553&r2=1504554&view=diff
==============================================================================
---
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_api.js
(original)
+++
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_api.js
Thu Jul 18 17:25:34 2013
@@ -835,11 +835,11 @@ define(['underscore', 'core/rave_ajax',
};
})();
- /**
- * @exports rave_api
- */
- return {
+
+ var exports = {
rest: restApi,
rpc: rpcApi
};
+
+ return exports;
})
\ No newline at end of file
Modified:
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_log.js
URL:
http://svn.apache.org/viewvc/rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_log.js?rev=1504554&r1=1504553&r2=1504554&view=diff
==============================================================================
---
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_log.js
(original)
+++
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_log.js
Thu Jul 18 17:25:34 2013
@@ -24,11 +24,14 @@ define([], function(){
/**
* Safely wraps console.log to prevent errors on browsers without console
support.
- * @exports rave_log
+ * @alias module:rave_log
+ * @param msg {*} message to be passed to console.log
*/
- return function(msg){
+ var log = function(msg){
if (console && console.log) {
console.log(msg);
}
}
+
+ return log;
})
Modified:
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_providers.js
URL:
http://svn.apache.org/viewvc/rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_providers.js?rev=1504554&r1=1504553&r2=1504554&view=diff
==============================================================================
---
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_providers.js
(original)
+++
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_providers.js
Thu Jul 18 17:25:34 2013
@@ -28,11 +28,19 @@
* @requires rave_opensocial
*/
define(['core/rave_wookie', 'core/rave_opensocial'], function(wookie, os){
+ var exports = {};
+
/**
- * @exports rave_providers
+ * Rave wookie provider module
+ * @see module:rave_wookie
*/
- return{
- w3c:wookie,
- opensocial:os
- }
+ exports.w3c = wookie;
+
+ /**
+ * Rave opensocial provider module.
+ * @see module:rave_opensocial
+ */
+ exports.opensocial = os;
+
+ return exports;
})
Modified:
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_view_manager.js
URL:
http://svn.apache.org/viewvc/rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_view_manager.js?rev=1504554&r1=1504553&r2=1504554&view=diff
==============================================================================
---
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_view_manager.js
(original)
+++
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_view_manager.js
Thu Jul 18 17:25:34 2013
@@ -17,6 +17,10 @@
* under the License.
*/
+/**
+ * Manages rave the registering and rendering of view objects.
+ * @module rave_view_manager
+ */
define(['underscore'], function(_){
//hash of registered views by name
var registeredViews = {}
@@ -25,20 +29,76 @@ define(['underscore'], function(_){
var exports = {};
- /*
- key: view name
- view: any object that manages and renders a view. At minimum must have
render and destroy methods. render should return 'this'
+ /**
+ *
+ * @typedef View
+ * @desc A view object may be either an object literal with the following
properties, or a
+ * constructor for an object that has these properties on its prototype.
+ * @property render {function} When invoked will display the view on the
page.
+ * Must return a reference to 'this'.
+ * @property [getWidgetSite] {function} Optional. Required if the view
will be used as a container
+ * for regionWidgets. Must return an HTMLElement into which the
regionWidget will be rendered.
+ * @property destroy {function} When invoked will hide the view on the
page and do any
+ * necessary clean up.
+ * @see module:rave_view_manager
+ * @see module:rave_widget
+ *
+ * @example
+ * view1 = {
+ * render: function(){
+ * $('#mydiv').show();
+ * return this;
+ * },
+ * getWidgetSite: function(){
+ * return $('#myDiv')[0];
+ * },
+ * destroy: function(){
+ * $('#mydiv').hide();
+ * }
+ * }
+ *
+ * view2 = function(){
+ * this.div = $('<div>').addClass('popup');
+ * }
+ * view2.prototype.render = function(){
+ * this.div.show();
+ * return this;
+ * }
+ * view2.prototype.getWidgetSite = function(){
+ * return this.div[0];
+ * }
+ * view2.prototype.destroy = function(){
+ * this.div.remove();
+ * }
+ */
+
+ /**
+ * Registers a view object by its name.
+ * @param key {string} name of view
+ * @param view {View}
*/
exports.registerView = function (key, view) {
registeredViews[key.toLowerCase()] = view;
}
+ /**
+ * Gets a registered view object
+ * @param key {string}
+ * @return {View}
+ */
exports.getView = function (key) {
return registeredViews[key.toLowerCase()];
}
+ /**
+ * Invokes the render function of a registered view. Any remaining
arguments are applied to
+ * the render function. A _uid property is set on the view object, which
can also be used to retrieve
+ * view object.
+ * @param key {string}
+ * @param args [...] {*} Any arguments following the key will be applied
to the view's render function.
+ * @return {View} A reference to the rendered view object
+ */
exports.renderView = function (key) {
- //apply remaining arguments to the view function - you know best!
var args = _.toArray(arguments).slice(1);
var view = exports.getView(key);
@@ -56,10 +116,20 @@ define(['underscore'], function(_){
return view;
}
+ /**
+ * Retrieves a rendered view based on it's _uid property.
+ * @param _uid {string}
+ * @return {View}
+ */
exports.getRenderedView = function (_uid) {
return renderedViews[_uid];
}
+ /**
+ * Invokes the destroy method on a registered view object
+ * @param view {View|string} Accepts a reference to the view object
+ * or its _uid property, by which the view object is retrieved and
destroyed
+ */
exports.destroyView = function (view) {
var args = _.toArray(arguments).slice(1);
@@ -71,7 +141,10 @@ define(['underscore'], function(_){
view.destroy(args);
}
- //reset internal data - used for testing cleanup
+ /**
+ * Resets the view registry. Intended only for testing internal use.
+ * @private
+ */
exports.reset = function () {
registeredViews = {};
}
Modified:
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_widget.js
URL:
http://svn.apache.org/viewvc/rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_widget.js?rev=1504554&r1=1504553&r2=1504554&view=diff
==============================================================================
---
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_widget.js
(original)
+++
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_widget.js
Thu Jul 18 17:25:34 2013
@@ -17,6 +17,12 @@
* under the License.
*/
+/**
+ * @module rave_widget
+ * @requires rave_api
+ * @requires rave_view_manager
+ * @requires rave_providers
+ */
define(['underscore', 'core/rave_api', 'core/rave_view_manager',
'core/rave_providers'],
function (_, api, viewManager, providers) {
@@ -24,8 +30,16 @@ define(['underscore', 'core/rave_api', '
return providers[name.toLowerCase()];
}
- /*
- rave widget constructor
+ /**
+ * Constructor for the rave RegionWidget object
+ * @param definition {object} json object defining the regionWidget
+ * @param definition.type {string} string corresponding to the
regionWidget provider ('opensocial' | 'w3c').
+ * Lookup of provider is case-insensitive.
+ * @throws Will throw an error if definition.type does not match a
registered provider, as defined in
+ * rave_providers (case-insensitive).
+ * @constructor
+ * @alias module:rave_widget
+ * @see module:rave_providers
*/
var Widget = function (definition) {
var provider = definition.type;
@@ -42,10 +56,29 @@ define(['underscore', 'core/rave_api', '
this._provider.initWidget(this);
}
+ /**
+ * Extends the regionWidget's prototype. Convenience function for
adding functionality
+ * to the regionWidget interface
+ * @param mixin {object}
+ */
Widget.extend = function (mixin) {
_.extend(this.prototype, mixin);
}
+ /**
+ * Renders the regionWidget onto the page into the given dom element.
This will delegate to
+ * the regionWidget's provider.
+ * @param [el] {(HTMLElement | string)} DOM element into which the
widget iframe will be rendered. If the
+ * argument is an HTMLElement, the regionWidget will be rendered
directly into that element. If it is a
+ * string, it will delegate to the rave_view_manager - rendering the
registered view, and rendering the
+ * regionWidget into the return value of that views getWidgetSite
method.
+ * A regionWidget keeps a handle on the dom element it was rendered
into, so after the first render
+ * if this argument is omitted, the region will re-render into that
element.
+ * @param [opts] {object} Render options which are passed to the
provider's renderWidget method.
+ * Supported options are therefore provider-specific.
+ * @return this
+ * @see module:rave_view_manager
+ */
Widget.prototype.render = function (el, opts) {
//if we receive only one argument, and the first arg is not a
string or dom element, assume it is an opts object
//and el should default to the widgets current render element
@@ -69,10 +102,19 @@ define(['underscore', 'core/rave_api', '
return this;
}
+ /**
+ * Prints error messages into the given dom element.
+ * @param el {HTMLElement}
+ * @param errors {string}
+ */
Widget.prototype.renderError = function (el, errors) {
el.innerHTML = 'Error rendering widget.' + "<br /><br />" + errors;
}
+ /**
+ * Sets the collapsed property of the regionWidget object to true, and
persists state to the server.
+ * Does not cause any dom manipulation.
+ */
Widget.prototype.hide = function () {
this.collapsed = true;
@@ -82,6 +124,10 @@ define(['underscore', 'core/rave_api', '
});
}
+ /**
+ * Sets the collapsed property of the regionWidget object to false,
and persists state to the server.
+ * Does not cause any dom manipulation.
+ */
Widget.prototype.show = function () {
this.collapsed = false;
@@ -91,6 +137,11 @@ define(['underscore', 'core/rave_api', '
});
}
+ /**
+ * Unrenders the regionWidget from the page, and persists state to the
server. If the regionWidget was
+ * rendered into a view, also invokes
module:rave_view_manager.destroyView method on that view.
+ * @param [opts] {object} options object that is passed to the
provider's close widget method.
+ */
Widget.prototype.close = function (opts) {
this._provider.closeWidget(this, opts);
if (this._view) {
@@ -102,6 +153,19 @@ define(['underscore', 'core/rave_api', '
});
}
+ /**
+ * A callback invoked after a successful call to the jsonRpc api.
+ * @callback apiSuccessCallback
+ * @param jsonRpcResult {object} - json rpc api result object.
+ */
+
+ /**
+ * Makes api calls to persists move state to the server. Moves
regionWidget object from one page to another.
+ * Does not cause any dom manipulation.
+ * @param toPageId {string}
+ * @param [cb] {apiSuccessCallback} - callback function that will be
invoked only if the state is successfully
+ * saved to the server.
+ */
Widget.prototype.moveToPage = function (toPageId, cb) {
api.rpc.moveWidgetToPage({
toPageId: toPageId,
@@ -110,6 +174,13 @@ define(['underscore', 'core/rave_api', '
});
}
+ /**
+ * Makes api calls to persist move state to the server. Moves the
regionWidget object between regions on a page.
+ * Does not cause any dom manipulation.
+ * @param fromRegionId {string}
+ * @param toRegionId {string}
+ * @param toIndex {string}
+ */
Widget.prototype.moveToRegion = function (fromRegionId, toRegionId,
toIndex) {
api.rpc.moveWidgetToRegion({
regionWidgetId: this.regionWidgetId,
@@ -119,11 +190,29 @@ define(['underscore', 'core/rave_api', '
});
}
+ /**
+ * Regionwidget userPref object
+ * @typedef Pref
+ * @property name {string} Preference name
+ * @property value {*} Preference value
+ */
+
+ /**
+ * Updates the regionWidget's userPrefs object, updating a single
preference, and persists state to server.
+ * Does not cause any dom manipulation.
+ * @param name {string}
+ * @param val {*} new preference value
+ */
Widget.prototype.savePreference = function (name, val) {
this.userPrefs[name] = val;
api.rest.saveWidgetPreference({regionWidgetId:
this.regionWidgetId, prefName: name, prefValue: val});
}
+ /**
+ * Updates the regionWidget's userPrefs property, overwriting the
entire object, and persists state to the
+ * server. Does not cause any dom manipulation.
+ * @param updatedPrefs {Array.<Pref>} Array of new preference objects
+ */
Widget.prototype.savePreferences = function (updatedPrefs) {
this.userPrefs = updatedPrefs;
api.rest.saveWidgetPreferences({regionWidgetId:
this.regionWidgetId, userPrefs: updatedPrefs});
Modified:
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_widget_manager.js
URL:
http://svn.apache.org/viewvc/rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_widget_manager.js?rev=1504554&r1=1504553&r2=1504554&view=diff
==============================================================================
---
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_widget_manager.js
(original)
+++
rave/trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_widget_manager.js
Thu Jul 18 17:25:34 2013
@@ -19,14 +19,27 @@
/**
* Manages region widgets on a page, including registration and retrieval
+ *
+ * @module rave_widget_manager
*/
define(['underscore', 'core/rave_widget'], function (_, regionWidget) {
var regionWidgets = {};
- var rave = {};
+ var exports = {};
+ /**
+ * @typedef RegionWidget
+ * @see module:rave_widget
+ */
+
+ /**
+ * Accepts a regionWidget definition object. Instantiates a new
RegionWidget object and registers it with rave.
+ * @param regionId {(string | number)}
+ * @param definition {object} json object defining the regionWidget
+ * @return {RegionWidget}
+ */
//TODO: regionId isn't really needed, but the script text is hard coded
and I don't want to mess with it yet
- rave.registerWidget = function (regionId, definition) {
+ exports.registerWidget = function (regionId, definition) {
//make regionId optional
if (!definition) {
definition = regionId;
@@ -39,23 +52,50 @@ define(['underscore', 'core/rave_widget'
}
//uregister a regionwidget, identified by a RegionWidget object, a widget
definition, or just an id
- rave.unregisterWidget = function (widget) {
+ /**
+ * Unregister a regionWidget from rave. Accepts a reference to the
RegionWidget object, or the regionWidet's id.
+ * @param widget {(RegionWidget | string)} The currently registered
regionWidget. Must be a reference to the
+ * RegionWidget object, or a valid id of a registered regionWidget.
+ */
+ exports.unregisterWidget = function (widget) {
var regionWidgetId = widget.regionWidgetId || widget;
delete regionWidgets[regionWidgetId];
}
- //convenience method to render all registered widgets
- rave.renderWidgets = function (el, opts) {
- _.invoke(rave.getWidgets(), 'render', el, opts);
+ /**
+ * Convenience method to render all registered regionWidgets. Delegates to
{@link module:rave_widget#render}. In most cases,
+ * you would pass el as a string, rendering each widget into a new
instance of a registered view.
+ * @param el {(HTMLElement | string)} Element or view to render all
widgets into.
+ * @param opts {object} options to pass to the regionWidgets' render
method.
+ */
+ exports.renderWidgets = function (el, opts) {
+ _.invoke(exports.getWidgets(), 'render', el, opts);
}
- //get registered widget by regionWidgetId
- rave.getWidget = function (regionWidgetId) {
+ /**
+ * Get registered regionWidget by id.
+ * @param regionWidgetId {string}
+ * @return {RegionWidget}
+ */
+ exports.getWidget = function (regionWidgetId) {
return regionWidgets[regionWidgetId];
}
- rave.getWidgets = function (filter) {
+ /**
+ * Get all registered regionWidgets, optionally filtered by a query object.
+ * @param [filter] {object} Filter object may have any number of key /
value pairs. Method will return only those
+ * regionWidgets that match ALL key / value pairs on the filter. Does not
support nested properties.
+ * @return {Array.<RegionWidget>}
+ * @example
+ *
+ * registerWidget({id: '1', regionId: '1'});
+ * registerWidget({id: '2', regionId: '2'});
+ *
+ * getWidgets(); //returns both regionWidgets
+ * getWidgets({regionId: '2'}); //returns only the second regionWidget
+ */
+ exports.getWidgets = function (filter) {
var widgets = _.toArray(regionWidgets);
if (filter) {
widgets = _.where(widgets, filter);
@@ -63,5 +103,5 @@ define(['underscore', 'core/rave_widget'
return widgets;
}
- return rave;
+ return exports;
})
