rave-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Erin Noe-Payne" <eri...@mitre.org>
Subject Re: Review Request: RAVE-914: isolate rave_core from rave_portal in javascript
Date Mon, 18 Mar 2013 22:29:56 GMT

-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/9993/
-----------------------------------------------------------

(Updated March 18, 2013, 10:29 p.m.)


Review request for rave.


Description (updated)
-------

**Patch will be updated with tests shortly.**

Rave Core JS 
** GOALS - 
rave core should have clear dependency tree; it should have no external dependencies outside
of underscorejs.
rave core should be separate from the portal; it should be lightweight, built to provide rave's
core functionality of managing and rendering sets of widgets and no extra overhead related
to the portal.
rave core should be extensible. As in implementer you should NEVER need to overlay a file
(rave_ajax.js is the only exception) in order to get required functionality. You should be
able to build a portal or website around rave core entirely through its api / extending its
objects. 
Please review with this in mind!

File: rave_ajax.js
namespace: rave.ajax
dependencies: jQuery
description: 
Wraps jQuery's $.ajax function, isolating rave core's dependency on jQuery to this one file.
 Any implementer who wishes to use another ajax library will overlay rave_ajax.js, and wrap
their ajax library of choice so that it maches the api of $.ajax.


File: rave_api
namespace: rave.api
dependencies: rave.ajax
description: 
Defines functions to access rave's rest & rpc apis. This file manages all ajax interaction
with the server. It should depend only on the rave.ajax namespace. It should provide callbacks
for any interaction that needs them, and should have know knowledge of further results(i.e.
if errors should be displayed to a user on a failed call, it is on the calling library to
implement - no ui or core interaction should be invoked from rave_api.  Besides factoring
out dependencies there have been no major changes to the rave.api spec.


File: rave_core.js
namespace: rave
dependencies: rave.api, rave.RegionWidget
description: 
Defines rave's core functionality. Manages registration of widgets, widget providers, views
(agnostic).

rave.registerProvider(name, provider)
- name String the name of the provider, such as 'open social' or 'wookie'. This should correspond
to the string provided by a widget definition's TYPE field (case insensitive)
- provider Object widget provider object, implementing those methods expected by the rave.RegionWidget
interface.
- returns Object returns the provider object

rave.getProvider(name)
- name String the name of the provider (case insensitive)
- returns Object widget provider object

rave.registerWidget([regionId], definition)
- *deprecated* [regionId] Number or String the regionId of the widget. This parameter is not
used and is deprecated. Currently supported until the rave rendering is updated.
- definition Object the widget definition as provided by rave's RegionWidgetRenderer class
- returns Object rave.RegionWidget instance

rave.getWidget(regionWidgetId)
-regionWidgetId String
-returns rave.RegionWidget instance

rave.getWidgets()
-returns Array of rave.RegionWidget instances for the registered widgets


rave.unregisterWidget(regionWidget)
- regionWidget 	String the regionWidgetId of the widget to unregister OR
			Object the rave.RegionWidget instance

rave.registerView(name, view)
- name String key to register the view under (case insensitive)
- view Object an agnostic view object implementing those methods expected by the rave View
specification  OR
	Function constructor for a view object implementing those methods expected by the rave View
specification 

rave.getView(name)
- name String key view was registered under (case insensitive)
- returns Object registered view object OR
	Function registered view constructor

rave.renderView(name, [args...])
If the registered view is a constructor function, first instantiates a new instances of the
view. Then invokes the render function of the view, passing it any remaining arguments.
- name String key view was registered under
- args * any remaining args are passed to the registered view's render function
- returns Object the rendered view instance. view._uid will be defined on the view - this
is a unique identifying string that can be used to retrieve and destroy the rendered view.

rave.getRenderedView(_uid)
- _uid String unique identifier string as defined on the view._uid that is returned from rave.renderView
- returns Object rendered view instance

rave.destroyView(_uid, [args…])
invokes the destory() method on the view object, passing it any remaining arguments.
- _uid String unique identifier string as defined on the view._uid that is returned from rave.renderView
- args * any remaining args are passed to the registered view's destroy function

rave.setDefaultGadgetSize([width], [height])
*deprecated* I think this method should be deprecated in favor of css rules to manage gadget
size.
- width Int width in pixels of default gadget size. Undefined value will have no effect.
- height Int height in pixels of default gadget size. Undefined value will have no effect.

rave.setDefaultGadgetView(viewName)
Invokes each provider's setDefaultGadgetView method.
- viewName String default view that widgets should be rendered into one is not specified.


rave.registerOnInitHandler(handler)
registers a function that will be invoked after rave.init() has been called. onInit handlers
will be called in the order they were registered
- handler Function function to invoke

rave.init()
function to be called once all rave resources and extensions are loaded. Kicks off initializing
of providers, widget objects, and any registered onInit handlers

rave.log([args…])
utility function wrapping console.log that can safely be called without throwing an error
in any browser environment.
- args * arguments that will be passed to console.log if it exists

rave.getManagedHub()
Instantiates (if needed) and returns an OpenAjax.hub.ManagedHub instance
- returns Object an OpenAjax.hub.ManagedHub instance

File: rave_widget
namespace: rave.RegionWidget
dependencies: rave.api
description: 
Defines rave.RegionWidget as an abstract class that provides a common interface & functionality
for any registered rave widget.

rave.RegionWidget(definition) 
constructor for abstract RegionWidget objects. All attributes from the definition are placed
on the instance.
Ex: var widget = new rave.RegionWidget({type: 'opensocial', name: 'myWidget'};
widget.name == 'myWidget' //true
In general you will not call this constructor directly - instead you will use rave.registerWidget()
to create new RegionWidgets and use rave.getWidget() / rave.getWidgets() to access the RegionWidget
instances.
- definition Object the widget definition as provided by rave's RegionWidgetRenderer class
- returns Object rave.RegionWidget object instance

rave.RegionWidget.extend(mixin)
convenience function to extend RegionWidget's prototype for adding custom functionality
- mixin Object key / value pairs to extend the RegionWidget prototype

rave.RegionWidget.prototype.render(el, opts)
Renders a region widget instance into a dom element. Invokes the widget providers renderWidget
method.
- el DomElement the DOM element into which the widget's iframe will be injected and rendered
OR
	String if a string is provided as the element, rave will look for a registered view by that
string. It will render that view and inject the widget into the dom element returned by the
view's getWidgetSite() method
- opts Object options object that is passed to the registered widget provider's renderWidget
method
- returns Object this. Returns the regionWidget instance for chaining.

rave.RegionWidget.prototype.close(el, opts)
Closes the region widget and removes the region widget from the page (persisted back to rave).
If the widget was rendered within a view, destroys that view. Invokes the widget providers
closeWidget function.
- opts * options object that is passed to the widget provider's closeWidget function

rave.RegionWidget.prototype.show()
Changes the widget's collapsed state and persists to the rave api. Does not take any ui actions
- it is on the implementer to bind ui interactions and use this method to persist show / hide
state.

rave.RegionWidget.prototype.hide()
Changes the widget's collapsed state and persists to the rave api. Does not take any ui actions
- it is on the implementer to bind ui interactions and use this method to persist show / hide
state.

rave.RegionWidget.prototype.moveToPage(toPageId, [cb])
Changes the widget's pageId and and persists to the rave api. Does not take any ui actions
- it is on the implementer to bind ui interactions and use this method to persist widget location
state.
- toPageId String or Int id of page that the widget is being moved to
- cb Function callback function to be invoked after persist is completed

rave.RegionWidget.prototype.moveToRegion(fromRegionId, toRegionId, toIndex)
Changes the widget's region and index and and persists to the rave api. Does not take any
ui actions - it is on the implementer to bind ui interactions and use this method to persist
widget location state.
-fromRegionId String or Int id of regionId the widget is being moved from
-toRegionId String or Int id of regionId the widget is being moved to
-toIndex String or Int id of index within the region the widget is being moved to

rave.RegionWidget.prototype.savePreferences(updatedPrefs)
Overwrites the widget's userPrefs object and persists to the rave api. Does not take any ui
actions - it is on the implementer to bind ui interactions and use this method to persist
user prefs state.

File: rave_opensocial, rave_wookie
namespace: n/a
dependencies: rave, opensocial & wookie implementations, respectively
description: 
These files provide implementations of the abstract rave.RegionWidget interface for open social
and wookie widgets. They do not attach anything to the rave namspace, but call rave.registerProvider
directly. 

Specifications - 

Rave Provider
The object handed to rave.registerProvider must conform to the following specification or
there will be errors
usage: rave.registerProvider('providerName', provider);
requirements: 

provider.init()
Should run any setup needed to implement the provider. This method is invoked by rave.init()
and will run before any rave.RegionWidget instances are instantiated. 

provider.initWidget(widget)
Should do any work to preload caches or prepare for widget. This method does NOT render the
widget, but does any work that can happen early.
-widgetDefinition Object rave.RegionWidget instance. 

provider.renderWidget(widget, el, [opts])
Provider-specific implementation needed to render a widget into a dom element
- widget Object rave.RegionWidget instance.
- el DomElement
- opts Object bag of options that are passed from rave.renderWidget()

provider.closeWidget(widget, [opts])
Provider-specific implementation needed to close a widget
- widget Object rave.RegionWidget instance.
- opts Object bag of options that are passed from rave.closeWidget()

provider.setDefaultGadgetSize(width, height)
Provider specific implementation needed to set default size of widget
- width Int width in pixels
- height Int height in pixels

provider.setDefaultView(view)
Provider specific implementation for setting the default view a widget should be rendered
into
- view String view name

Rave View
The argument handed to rave.registerView. Rave is completely agnostic of any dependencies,
libraries, mv* frameworks, etc. It simply expects the view to be either…
an object that implements the following methods, or…
a constructor function that instatiates objects which implement the following methods
usage: rave.registerView('myView', {render: function(){...}, getWidgetSite: function(){...},
destroy: function(){...});
requirements: 

view.render([args…])
Renders the view into the ui. Can take any number & type of arguments, which are simply
passed from rave.renderView
-returns Object the render function MUST return itself (i.e. return this;)

view.getWidgetSite()
OPTIONAL. This method is required only if it will ever be used for rendering a widget. Meaning
either a call from widget.render('viewName'), or if it will be exposed to opensocial open
views spec.
- returns DomElement a raw DomElement (not a query object) which the widget iframe will be
inserted into

view.destroy([args…])
Performs any teardown necessary to unrender the view. Can take any number & type of arguments,
which are simply passed from rave.destoryView().


This addresses bug Rave-914.
    https://issues.apache.org/jira/browse/Rave-914


Diffs
-----

  trunk/rave-portal-resources/pom.xml 1457969 
  trunk/rave-portal-resources/src/main/resources/wro.xml 1457969 
  trunk/rave-portal-resources/src/main/webapp/WEB-INF/jsp/views/mobile_home.jsp 1457969 
  trunk/rave-portal-resources/src/main/webapp/WEB-INF/jsp/views/page.jsp 1457969 
  trunk/rave-portal-resources/src/main/webapp/WEB-INF/tags/rave_js.tag 1457969 
  trunk/rave-portal-resources/src/main/webapp/WEB-INF/tags/region_widget.tag 1457969 
  trunk/rave-portal-resources/src/main/webapp/static/css/rave-css.less 1457969 
  trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_ajax.js PRE-CREATION

  trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_api.js PRE-CREATION

  trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_core.js PRE-CREATION

  trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_opensocial.js PRE-CREATION

  trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_widget.js PRE-CREATION

  trunk/rave-portal-resources/src/main/webapp/static/script/core/rave_wookie.js PRE-CREATION

  trunk/rave-portal-resources/src/main/webapp/static/script/portal/rave_admin.js PRE-CREATION

  trunk/rave-portal-resources/src/main/webapp/static/script/portal/rave_backbone.js PRE-CREATION

  trunk/rave-portal-resources/src/main/webapp/static/script/portal/rave_forms.js PRE-CREATION

  trunk/rave-portal-resources/src/main/webapp/static/script/portal/rave_layout.js PRE-CREATION

  trunk/rave-portal-resources/src/main/webapp/static/script/portal/rave_models.js PRE-CREATION

  trunk/rave-portal-resources/src/main/webapp/static/script/portal/rave_person_profile.js
PRE-CREATION 
  trunk/rave-portal-resources/src/main/webapp/static/script/portal/rave_portal.js PRE-CREATION

  trunk/rave-portal-resources/src/main/webapp/static/script/portal/rave_store.js PRE-CREATION

  trunk/rave-portal-resources/src/main/webapp/static/script/portal/rave_ui.js PRE-CREATION

  trunk/rave-portal-resources/src/main/webapp/static/script/rave.js 1457969 
  trunk/rave-portal-resources/src/main/webapp/static/script/rave_admin.js 1457969 
  trunk/rave-portal-resources/src/main/webapp/static/script/rave_api.js 1457969 
  trunk/rave-portal-resources/src/main/webapp/static/script/rave_backbone.js 1457969 
  trunk/rave-portal-resources/src/main/webapp/static/script/rave_forms.js 1457969 
  trunk/rave-portal-resources/src/main/webapp/static/script/rave_layout.js 1457969 
  trunk/rave-portal-resources/src/main/webapp/static/script/rave_models.js 1457969 
  trunk/rave-portal-resources/src/main/webapp/static/script/rave_opensocial.js 1457969 
  trunk/rave-portal-resources/src/main/webapp/static/script/rave_person_profile.js 1457969

  trunk/rave-portal-resources/src/main/webapp/static/script/rave_store.js 1457969 
  trunk/rave-portal-resources/src/main/webapp/static/script/rave_ui.js 1457969 
  trunk/rave-portal-resources/src/main/webapp/static/script/rave_wookie.js 1457969 
  trunk/rave-portal-resources/src/test/js/rave_api_spec.js PRE-CREATION 

Diff: https://reviews.apache.org/r/9993/diff/


Testing
-------


Thanks,

Erin Noe-Payne


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message