From 4ab05384ea181aff4e789094c332a658554c5abe Mon Sep 17 00:00:00 2001 From: Charles du Jeu Date: Sun, 7 Dec 2008 18:08:50 +0000 Subject: [PATCH] API Documentation git-svn-id: https://svn.argeo.org/slc/trunk@1937 4cfe0d0a-d680-48aa-b62c-e0a02a3f76cc --- .../source/class/org/argeo/ria/Application.js | 2 +- .../source/class/org/argeo/ria/__init__.js | 15 ++++ .../argeo/ria/components/ILoadStatusable.js | 15 ++-- .../org/argeo/ria/components/IPerspective.js | 20 +++++- .../class/org/argeo/ria/components/IView.js | 36 +++++++--- .../class/org/argeo/ria/components/Logger.js | 22 +++--- .../class/org/argeo/ria/components/Modal.js | 31 +++++--- .../org/argeo/ria/components/ViewPane.js | 57 ++++++++++++--- .../org/argeo/ria/components/ViewSelection.js | 32 +++++++++ .../org/argeo/ria/components/ViewsManager.js | 38 +++++++++- .../org/argeo/ria/components/XmlRenderer.js | 19 ++++- .../org/argeo/ria/components/__init__.js | 5 ++ .../class/org/argeo/ria/event/Command.js | 67 +++++++++++++++++- .../org/argeo/ria/event/CommandsManager.js | 70 +++++++++++++++++-- .../class/org/argeo/ria/event/ReloadEvent.js | 27 ++++--- .../class/org/argeo/ria/event/__init__.js | 5 ++ .../org/argeo/ria/remote/RequestManager.js | 60 +++++++++++++++- .../class/org/argeo/ria/remote/__init__.js | 4 ++ .../class/org/argeo/ria/test/__init__.js | 4 ++ .../class/org/argeo/ria/util/Element.js | 12 ++-- .../class/org/argeo/ria/util/__init__.js | 5 ++ .../class/org/argeo/slc/web/Perspective.js | 4 +- 22 files changed, 476 insertions(+), 74 deletions(-) create mode 100644 org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/__init__.js create mode 100644 org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/__init__.js create mode 100644 org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/event/__init__.js create mode 100644 org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/remote/__init__.js create mode 100644 org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/test/__init__.js create mode 100644 org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/util/__init__.js diff --git a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/Application.js b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/Application.js index d754a1978..5544aa9ae 100644 --- a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/Application.js +++ b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/Application.js @@ -15,7 +15,7 @@ ************************************************************************ */ /** - * This is the main application class of your custom application "slc" + * This is the main application class of an Argeo RIA. */ qx.Class.define("org.argeo.ria.Application", { diff --git a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/__init__.js b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/__init__.js new file mode 100644 index 000000000..5ff6b2127 --- /dev/null +++ b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/__init__.js @@ -0,0 +1,15 @@ +/** + * Generic package for the Argeo Rich Internet Application based on qooxdoo (www.qooxdoo.org). + * This is an empty application in itself, since it requires at least a basic implementation to be useful. + * + * + * The skeleton of an ArgeoRIA is the following : + * + * + GUI Application containing a menubar, a toolbar, and an empty space for custom Perspective. + * + * + Various managers : org.argeo.ria.components.ViewsManager for manipulating IView (VIEW), org.argeo.ria.event.CommandsManager + * for automatically wiring commands inside the application (CONTROLLER), and org.argeo.ria.remote.RequestManager for accessing the data (MODEL). + * + * + A simple configuration will allow to start your own Perspective inside the application. + * + */ \ No newline at end of file diff --git a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/ILoadStatusable.js b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/ILoadStatusable.js index 11f4e10ec..dcb95547f 100644 --- a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/ILoadStatusable.js +++ b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/ILoadStatusable.js @@ -1,12 +1,19 @@ /** - * @author Charles du Jeu * + * Any component implementing this interface will generally be a user-interface indicating + * a "loading" status (button enabled/disabled, animated loading gif, etc...). + * The RequestManager can handle such an array of ILoadStatusable at the beginning/end of a Request. + * + * @author Charles du Jeu */ qx.Interface.define("org.argeo.ria.components.ILoadStatusable", { members : { - setOnLoad : function(status){ - return true; - } + /** + * Sets the current status of the component. + * @param status {boolean} load status + * @return {Boolean} + */ + setOnLoad : function(status){return true;} } }); \ No newline at end of file diff --git a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/IPerspective.js b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/IPerspective.js index cf19ee12d..88d3e870d 100644 --- a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/IPerspective.js +++ b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/IPerspective.js @@ -1,11 +1,29 @@ /** - * @author Charles du Jeu + * This interface defines the main methods of an application Perpective. + * See the org.argeo.ria package documentation for more info on how to build an Application + * with this framework. * + * @author Charles du Jeu */ qx.Interface.define("org.argeo.ria.components.IPerspective", { members : { + /** + * Initialize the available zones that will later contain IView implementations. + * This method is in charge of your panel to the main application zone + * (just below the toolbar). + * + * @param viewsManager {org.argeo.components.ViewsManager} the pane manager + * + */ initViewPanes : function(viewsManager){return true;}, + /** + * Once the zones are available and initialized, initialize the views here + * and add them to viewPanes. Trigger initial data loading, etc. + * + * @param viewsManager {org.argeo.components.ViewsManager} the pane manager + * + */ initViews : function(viewsManager){return true} } }); \ No newline at end of file diff --git a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/IView.js b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/IView.js index 619aecad4..3d3cd1aa3 100644 --- a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/IView.js +++ b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/IView.js @@ -1,6 +1,13 @@ /** - * @author Charles du Jeu + * Interface for a standard 'view' of an argeo RIA. A view is an independant applet that + * will be integrated inside a ViewPane. + * + * The typical lifecycle of an IView will be the following : + *
+ init(viewPane) : initialize basic GUI in the viewPane + *
+ getCommands() : wire the commands and add them to the toolbars/menubars + *
+ load(data) : loads the data itself. * + * @author Charles du Jeu */ qx.Interface.define("org.argeo.ria.components.IView", { @@ -9,14 +16,23 @@ qx.Interface.define("org.argeo.ria.components.IView", { }, members : { - init : function(viewPane){ - return true; - }, - load : function(data){ - return true; - }, - addScroll : function(){ - return true; - } + /** + * The implementation should contain the GUI initialisation. + * @param viewPane {org.argeo.ria.components.ViewPane} The pane manager + * @return {Boolean} + */ + init : function(viewPane){return true;}, + /** + * The implementation should contain the real data loading (i.o. query...) + * @param data {mixed} Any data in any format + * @return {Boolean} + */ + load : function(data){return true;}, + /** + * Whether this component is already contained in a scroller + * (return false) or not (return true). + * @return {Boolean} + */ + addScroll : function(){return true;} } }); \ No newline at end of file diff --git a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/Logger.js b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/Logger.js index ab9a7a29c..9507d76ee 100644 --- a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/Logger.js +++ b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/Logger.js @@ -1,12 +1,9 @@ -/* ************************************************************************ - - Copyright: 2008 Argeo - - License: - - Authors: Charles du Jeu - -************************************************************************ */ +/** + * A modal window like console for the logs. + * Also opens a small alert window (qooxdoo, not native) on errors. + * + * @author : Charles du Jeu + */ qx.Class.define("org.argeo.ria.components.Logger", { type : "singleton", @@ -69,6 +66,10 @@ qx.Class.define("org.argeo.ria.components.Logger", }, members : { + /** + * Adds a log in the GUI component. + * @param entry {Map} A log entry + */ process : function(entry){ var wrapper = qx.log.appender.Util.toHtml(entry); var label = new qx.ui.basic.Label('
'+wrapper.innerHTML+'
'); @@ -80,6 +81,9 @@ qx.Class.define("org.argeo.ria.components.Logger", } this._logPane.addAt(label, 0); }, + /** + * Shows the GUI console and center it. + */ toggle : function(){ this.show(); this.center(); diff --git a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/Modal.js b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/Modal.js index 690659943..2c8aef04d 100644 --- a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/Modal.js +++ b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/Modal.js @@ -1,16 +1,18 @@ -/* ************************************************************************ - - Copyright: 2008 Argeo - - License: - - Authors: Charles du Jeu - -************************************************************************ */ +/** + * Generic modal popup window. + * It is layed out with a dock layout. When adding components to it, they are added as "center". + * @author Charles du Jeu + */ qx.Class.define("org.argeo.ria.components.Modal", { extend : qx.ui.window.Window, + /** + * + * @param caption {String} Title of the window + * @param icon {String} Icon of the window + * @param text {String} Default content of the window. + */ construct : function(caption, icon, text){ this.base(arguments); this.set({ @@ -34,12 +36,23 @@ qx.Class.define("org.argeo.ria.components.Modal", }, members : { + /** + * Display text inside the popup + * @param text {String} A string content for the popup + */ addLabel:function(text){ this.add(new qx.ui.basic.Label(text), {edge:'center', width:'100%'}); }, + /** + * Display a component (panel) in the center of the popup + * @param panel {qx.ui.core.Widget} A gui component (will be set at width 100%). + */ addContent: function(panel){ this.add(panel, {edge:'center', width:'100%'}); }, + /** + * Automatically attach to the application root, then show. + */ attachAndShow:function(){ org.argeo.ria.components.ViewsManager.getInstance().getApplicationRoot().add(this); this.show(); diff --git a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/ViewPane.js b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/ViewPane.js index 25e8f10e6..485a264c0 100644 --- a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/ViewPane.js +++ b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/ViewPane.js @@ -1,17 +1,21 @@ /** + * A standard view container, referenced in the application by its unique id. + * It is managed by the ViewsManager singleton that works as the "View" part of an MVC model. + * @see org.argeo.ria.components.ViewsManager * @author Charles */ -/** - * This is the main application class of your custom application "sparta" - */ qx.Class.define("org.argeo.ria.components.ViewPane", { extend : qx.ui.container.Composite, implement : [org.argeo.ria.components.ILoadStatusable], - construct : function(application, viewId, viewTitle, splitPaneData){ + /** + * @param viewId {String} Unique id of this viewPane + * @param viewTitle {String} Readable Title of this viewPane + * @param splitPaneData {Map} Additionnal data to be used by splitpanes implementations. + */ + construct : function(viewId, viewTitle, splitPaneData){ this.base(arguments); - this.setApplication(application); this.setViewId(viewId); this._defaultViewTitle = viewTitle; this.setViewTitle(viewTitle); @@ -25,13 +29,31 @@ qx.Class.define("org.argeo.ria.components.ViewPane", properties : { - application : {init : null}, + /** + * Unique id of the pane + */ viewId : {init:""}, + /** + * Human-readable title for this view + */ viewTitle : {init:"", event:"changeViewTitle"}, - viewSelection : { nullable:false }, - ownScrollable : {init: false}, - splitPaneData : {init : null}, - commands : {init : null, nullable:true} + /** + * Selection model for this view + */ + viewSelection : { nullable:false, check:"org.argeo.ria.components.ViewSelection" }, + /** + * Has its own scrollable content + */ + ownScrollable : {init: false, check:"Boolean"}, + /** + * Data concerning the split pane + */ + splitPaneData : {init : null, check:"Map"}, + /** + * Map of commands definition + * @see org.argeo.ria.event.Command + */ + commands : {init : null, nullable:true, check:"Map"} }, /* @@ -42,6 +64,9 @@ qx.Class.define("org.argeo.ria.components.ViewPane", members : { + /** + * Creates a standard GUI for the viewPane, including a container for an IView. + */ createGui : function(){ this.setLayout(new qx.ui.layout.VBox()); this.header = new qx.ui.container.Composite(); @@ -84,6 +109,10 @@ qx.Class.define("org.argeo.ria.components.ViewPane", */ }, + /** + * Sets the content of this pane. + * @param content {org.argeo.ria.components.IView} An IView implementation + */ setContent : function(content){ var addScrollable = (content.addScroll?content.addScroll():false); if(addScrollable){ @@ -96,6 +125,11 @@ qx.Class.define("org.argeo.ria.components.ViewPane", } }, + /** + * Implementation of the ILoadStatusable interface. + * @see org.argeo.ria.components.ILoadStatusable + * @param load {Boolean} The loading status + */ setOnLoad : function(load){ if(!this.loadImage){ this.loadImage = new qx.ui.basic.Image('resource/slc/ajax-loader.gif'); @@ -107,6 +141,9 @@ qx.Class.define("org.argeo.ria.components.ViewPane", } }, + /** + * Removes and destroy the IView content of this viewPane. + */ empty: function(){ if(this.getOwnScrollable() && this.scrollable){ this.remove(this.scrollable); diff --git a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/ViewSelection.js b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/ViewSelection.js index 8f81f0a76..6c3e873ab 100644 --- a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/ViewSelection.js +++ b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/ViewSelection.js @@ -1,7 +1,15 @@ +/** + * Generic selection model associated to an IView content opened in a given ViewPane. + * It contains in an array any row/data/node, and triggers changeSelection data events. + * @author Charles du Jeu + */ qx.Class.define("org.argeo.ria.components.ViewSelection", { extend : qx.core.Object, + /** + * @param viewId {String} The ViewPane unique id + */ construct : function(viewId){ this.base(arguments); this.nodes = []; @@ -9,6 +17,9 @@ qx.Class.define("org.argeo.ria.components.ViewSelection", }, properties : { + /** + * The viewPane unique id + */ viewId : { check : "String", nullable: false @@ -16,6 +27,9 @@ qx.Class.define("org.argeo.ria.components.ViewSelection", }, events : { + /** + * Triggered each time the selection changes. + */ "changeSelection" : "qx.event.type.Data" }, @@ -27,24 +41,42 @@ qx.Class.define("org.argeo.ria.components.ViewSelection", members : { + /** + * Empty the selection + */ clear : function(){ this.nodes = []; this.triggerEvent(); }, + /** + * Add a row or xml node or whatever + * @param node {mixed} Data to add to the selection + */ addNode : function(node) { this.nodes.push(node); this.triggerEvent(); }, + /** + * The number of rows/nodes selected + * @return {Integer} + */ getCount : function() { return this.nodes.length; }, + /** + * Returns the content of the selection + * @return {Array} + */ getNodes : function(){ return this.nodes; }, + /** + * Creates and fire a data event changeSelection + */ triggerEvent : function(){ this.fireDataEvent("changeSelection", this); } diff --git a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/ViewsManager.js b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/ViewsManager.js index 2678eba51..2b0815d5e 100644 --- a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/ViewsManager.js +++ b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/ViewsManager.js @@ -1,4 +1,8 @@ /** + * The main "view" manager (in a standard MVC conception) of the application. + * It register various containers org.argeo.ria.components.viewPane and feed them with org.argeo.ria.components.IView implementations. + * It is a singleton and can thus be called by any part of the application. + * * @author Charles du Jeu */ qx.Class.define("org.argeo.ria.components.ViewsManager", @@ -7,14 +11,27 @@ qx.Class.define("org.argeo.ria.components.ViewsManager", extend : qx.core.Object, properties : { + /** + * The application root (like Application.getRoot()), used to attach and show modal windows. + */ applicationRoot : {init : null}, + /** + * The main container for the org.argeo.ria.components.ViewPane instances. + */ viewPanesContainer : {init: null} }, construct : function(){ this.views = {}; }, members : { - + /** + * Initialize and load a given IView implementation into a viewPane. + * The IView itself is returned. + * + * @param classObj {Clazz} The class object to instantiate + * @param viewPaneId {String} The unique ID of the view pane + * @return {org.argeo.ria.components.IView} + */ initIViewClass: function(classObj, viewPaneId){ //var iView = eval("new "+iViewClass+"()"); //var classObj = qx.Class.getByName(iViewClass); @@ -31,19 +48,38 @@ qx.Class.define("org.argeo.ria.components.ViewsManager", return iView; }, + /** + * Registers a new viewPane + * @param viewPane {org.argeo.ria.components.ViewPane} The new ViewPane instance + */ registerViewPane : function(viewPane){ this.views[viewPane.getViewId()] = viewPane; viewPane.getViewSelection().addListener("changeSelection", function(e){ org.argeo.ria.event.CommandsManager.getInstance().refreshCommands(e.getData()); }); }, + /** + * Returns a viewPane by its unique id. + * @param viewPaneId {String} The unique id + * @return {org.argeo.ria.components.ViewPane} + */ getViewPaneById : function(viewPaneId){ if(this.views[viewPaneId]) return this.views[viewPaneId]; throw new Error("Cannot find view '"+viewPaneId+"'"); }, + /** + * Returns a viewPane current viewSelection object + * @param viewPaneId {String} The unique id. + * @return {org.argeo.ria.components.ViewSelection} + */ getViewPaneSelection : function(viewPaneId){ return this.getViewPaneById(viewPaneId).getViewSelection(); }, + /** + * Changes a viewPane title dynamically. + * @param viewPaneId {String} ViewPane unique Id. + * @param viewTitle {String} the new title for this viewPane. + */ setViewPaneTitle : function(viewPaneId, viewTitle){ this.getViewPaneById(viewPaneId).setViewTitle(viewTitle); } diff --git a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/XmlRenderer.js b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/XmlRenderer.js index e3c557912..68d287eb9 100644 --- a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/XmlRenderer.js +++ b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/XmlRenderer.js @@ -1,3 +1,10 @@ +/** + * Basic helper for SLC XML results to be displayed in a qx.ui.table. + * Overrides the html of the standard qx.ui.table.cellrenderer.String + * + * TODO : put in org.argeo.slc.ria package + * + */ qx.Class.define("org.argeo.ria.components.XmlRenderer", { extend : qx.ui.table.cellrenderer.String, @@ -10,8 +17,11 @@ qx.Class.define("org.argeo.ria.components.XmlRenderer", members : { - // overridden - // TODO : Put this in org.argeo.slc.ria + /** + * Overrides the parent method. + * @param cellInfo {Map} The current cell data + * @return {String} + */ _getContentHtml : function(cellInfo) { var xmlNode = cellInfo.rowData; if(!xmlNode) return ""; @@ -47,6 +57,11 @@ qx.Class.define("org.argeo.ria.components.XmlRenderer", }, // overridden + /** + * Overrides parent method + * @param cellInfo {Map} Current cell data + * @return {String} + */ _getCellClass : function(cellInfo) { return this.base(arguments, cellInfo); } diff --git a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/__init__.js b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/__init__.js new file mode 100644 index 000000000..3f9efafa7 --- /dev/null +++ b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/components/__init__.js @@ -0,0 +1,5 @@ +/** + * Package containing GUI components and main interfaces for GUI components to + * be used by any argeo RIA application. + * + */ \ No newline at end of file diff --git a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/event/Command.js b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/event/Command.js index b18918963..0026170ad 100644 --- a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/event/Command.js +++ b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/event/Command.js @@ -1,20 +1,49 @@ -qx.Class.define("org.argeo.ria.event.Command", +/** + * The standard command for all actions. It registers keyboard shortcuts, centralizes + * command state, callback, etc. It is defined by command definitions that can be found + * in the CommandsManager. + */ + qx.Class.define("org.argeo.ria.event.Command", { extend : qx.event.Command, implement : [org.argeo.ria.components.ILoadStatusable], properties : { + /** + * Unique id of the command + */ id : {init:""}, + /** + * Label of the command + */ label : {init:""}, + /** + * Icon of the command + */ icon : {init:""}, + /** + * Sub menu if needed + */ menu : { nullable: true, event : "changeMenu" }, + /** + * Callback associated to the submenu of the command + */ menuCallback : {nullable:true}, + /** + * Context used when triggering menuCallback + */ menuContext : {nullable:true} }, + /** + * @param id {String} Id of the command + * @param label {String} Label of the command + * @param icon {String} Icon of the command + * @param shortcut {String} Keyboard Shortcut (like alt+o, ctrl+z, etc..) + */ construct : function(id, label, icon, shortcut){ this.base(arguments, shortcut); this.setId(id); @@ -24,6 +53,10 @@ qx.Class.define("org.argeo.ria.event.Command", members : { + /** + * Create a Button that suits a qx.ui.menu.MenuBar linked to this command + * @return {qx.ui.menu.Button} + */ getMenuButton : function(){ var button = new qx.ui.menu.Button( this.getLabel(), @@ -40,6 +73,10 @@ qx.Class.define("org.argeo.ria.event.Command", return button; }, + /** + * Create a Button that suits a qx.ui.toolbar.Toolbar part linked to this command. + * @return {qx.ui.toolbar.MenuButton} + */ getToolbarButton : function(){ var button; if(this.getMenu()){ @@ -66,6 +103,10 @@ qx.Class.define("org.argeo.ria.event.Command", return button; }, + /** + * Clones the command menu + * @return {qx.ui.menu.Menu} + */ getMenuClone : function(){ if(!this.menuClone){ this.menuClone = new qx.ui.menu.Menu(); @@ -74,11 +115,21 @@ qx.Class.define("org.argeo.ria.event.Command", return this.menuClone; }, + /** + * Remove all existing menus and their clones. + */ clearMenus : function(){ this.getMenu().removeAll(); this.getMenuClone().removeAll(); }, + /** + * Add button to a given submenu. + * @param label {String} The label of the button + * @param icon {String} The icon of the button + * @param commandId {String} The associated command id. + * @param menu {qx.ui.menu.Menu} The menu to which add the button + */ addSubMenuButton : function(label, icon, commandId, menu){ var button = new qx.ui.menu.Button(label, icon); button.setUserData("commandId", commandId); @@ -91,19 +142,31 @@ qx.Class.define("org.argeo.ria.event.Command", } }, + /** + * Triggers the menuCallback property in the right context. + * @param event {qx.event.type.Event} The firing event. + */ executeSubMenuCallback : function(event){ var button = event.getTarget(); var callback = this.getMenuCallback(); callback = qx.lang.Function.bind(callback, this.getMenuContext() || this); callback(button.getUserData("commandId")); }, - + /** + * Adds a tooltip to a button. + * @param element {qx.ui.core.Widget} The element to which the command tooltip is added. + */ addTooltip : function(element){ if(this.getShortcut() != null){ element.setToolTip(new qx.ui.tooltip.ToolTip(this.getShortcut())); } }, + /** + * Implementation of the ILoadStatusable interface. + * Sets the whole command enabled if not loading and disabled if loading. + * @param status {Boolean} The loading status of the button. + */ setOnLoad : function(status){ this.setEnabled(!status); } diff --git a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/event/CommandsManager.js b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/event/CommandsManager.js index 280df7578..7bd0957dd 100644 --- a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/event/CommandsManager.js +++ b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/event/CommandsManager.js @@ -1,6 +1,10 @@ /** - * @author Charles + * The main controller (in a standard MVC point of view) of the application. It is a singleton + * thus can be called by any part of the application. + * This will wire all the commands that can be defined dynamically by any IView, and add their + * corresponding buttons to the application menubar and toolbars. * + * @author Charles du Jeu */ qx.Class.define("org.argeo.ria.event.CommandsManager", { @@ -15,6 +19,10 @@ qx.Class.define("org.argeo.ria.event.CommandsManager", properties : { + /** + * Commands definitions + * @see org.argeo.ria.event.Command for the definition Map details. + */ definitions : { init : { "stop" : { @@ -65,12 +73,18 @@ qx.Class.define("org.argeo.ria.event.CommandsManager", } } }, + /** + * For internal use + */ initialDefinitions : { init : {} } }, events : { + /** + * Triggered when the whole commands list is changed. + */ "changedCommands" : "qx.event.type.Event" }, @@ -82,6 +96,9 @@ qx.Class.define("org.argeo.ria.event.CommandsManager", members : { + /** + * Creates all the objects (if they are not already existing) from the definitions maps. + */ createCommands : function(){ this.menus = {}; this.toolbars = {}; @@ -116,7 +133,11 @@ qx.Class.define("org.argeo.ria.event.CommandsManager", } this.setDefinitions(defs); }, - + + /** + * Refresh the current commands status depending on the viewSelection. + * @param viewSelection {org.argeo.ria.components.ViewSelection} The current ViewSelection + */ refreshCommands : function(viewSelection){ var defs = this.getDefinitions(); var xmlNodes = null; @@ -131,6 +152,10 @@ qx.Class.define("org.argeo.ria.event.CommandsManager", } }, + /** + * Record a menubar for the application + * @param menuBar {qx.ui.menubar.MenuBar} The application menubar + */ registerMenuBar : function(menuBar){ this.addListener("changedCommands", function(){ this.createMenuButtons(menuBar); @@ -138,6 +163,10 @@ qx.Class.define("org.argeo.ria.event.CommandsManager", this.createMenuButtons(menuBar); }, + /** + * Record a toolbar for the application + * @param toolBar {qx.ui.toolbar.ToolBar} The application toolbar + */ registerToolBar : function(toolBar){ this.addListener("changedCommands", function(){ this.createToolbarParts(toolBar); @@ -145,6 +174,10 @@ qx.Class.define("org.argeo.ria.event.CommandsManager", this.createToolbarParts(toolBar); }, + /** + * Creates the real buttons and add them to the passed menuBar. + * @param menuBar {qx.ui.menubar.MenuBar} The application menubar + */ createMenuButtons : function(menuBar){ menuBar.removeAll(); var anchors = {}; @@ -170,6 +203,11 @@ qx.Class.define("org.argeo.ria.event.CommandsManager", menuBar.add(anchors.last); } }, + + /** + * Creates the real buttons and add them to the passed toolbar. + * @param toolbar {qx.ui.toolbar.ToolBar} The application toolbar + */ createToolbarParts : function(toolbar){ toolbar.removeAll(); for(var key in this.toolbars){ @@ -180,6 +218,11 @@ qx.Class.define("org.argeo.ria.event.CommandsManager", }); } }, + /** + * Creates a context menu from an array of commands ids. + * @param commandIdsArray {Array} An array of string + * @return {qx.ui.menu.Menu} + */ createMenuFromIds : function(commandIdsArray){ var defs = this.getDefinitions(); var contextMenu = new qx.ui.menu.Menu(); @@ -192,7 +235,11 @@ qx.Class.define("org.argeo.ria.event.CommandsManager", } return contextMenu; }, - + /** + * Add a new set of commands definitions + * @param definitions {Map} a set of commands definitions. + * @param callbackContext {qx.ui.core.Object} The context used inside the commands callbacks. + */ addCommands : function(definitions, callbackContext){ var crtDefs = this.getDefinitions(); for(var key in definitions){ @@ -202,6 +249,10 @@ qx.Class.define("org.argeo.ria.event.CommandsManager", this.setDefinitions(crtDefs); this.fireEvent("changedCommands"); }, + /** + * Removes a whole set of commands by their definitions maps. + * @param definitions {Map} a set of commands definitions + */ removeCommands : function(definitions){ var crtDefs = this.getDefinitions(); var initDefs = this.getInitialDefinitions(); @@ -216,19 +267,30 @@ qx.Class.define("org.argeo.ria.event.CommandsManager", this.setDefinitions(crtDefs); this.fireEvent("changedCommands"); }, - + /** + * Executes a command by its id. + * @param commandId {String} The command id. + */ executeCommand : function(commandId){ var defs = this.getDefinitions(); if(defs[commandId] && defs[commandId].command.getEnabled()){ defs[commandId].command.execute(); } }, + /** + * Retrieves a command by its id. + * @param commandId {String} The command id. + */ getCommandById : function(commandId){ var defs = this.getDefinitions(); if(defs[commandId] && defs[commandId].command){ return defs[commandId].command; } }, + /** + * Add a standard context menu to a toolbar for button look and feel (show icon, text, both). + * @param toolbar {qx.ui.toolbar.ToolBar} The toolbar + */ addToolbarContextMenu : function(toolbar){ var menu = new qx.ui.menu.Menu(); var icon = new qx.ui.menu.RadioButton("Show Icons"); diff --git a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/event/ReloadEvent.js b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/event/ReloadEvent.js index d86b0d1fe..2877a7335 100644 --- a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/event/ReloadEvent.js +++ b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/event/ReloadEvent.js @@ -1,12 +1,8 @@ -/* ************************************************************************ - - Copyright: 2008 Argeo - - License: - - Authors: Charles du Jeu - -************************************************************************ */ +/** + * This can be triggered at the end of a IO Request. In that case, it contains + * a data type as an identifier, and the request response itself. + * Can be used this way to listen for data changes from various parts of the application. + */ qx.Class.define("org.argeo.ria.event.ReloadEvent", { extend : qx.event.type.Event, @@ -15,13 +11,24 @@ qx.Class.define("org.argeo.ria.event.ReloadEvent", this.base(arguments); }, members : { + /** + * Basic initialisation of event + * @param dataType {String} a unique data identifier + * @param content {mixed} the retrieved data + */ init: function(dataType, content){ this.setDataType(dataType); this.setContent(content); } }, properties :{ - dataType : {init:null}, + /** + * A unique data identifier + */ + dataType : {init:null, check:"String"}, + /** + * The new data content + */ content : {init:null} } }); \ No newline at end of file diff --git a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/event/__init__.js b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/event/__init__.js new file mode 100644 index 000000000..417cbb5f4 --- /dev/null +++ b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/event/__init__.js @@ -0,0 +1,5 @@ +/** + * Event utilities, this package is the "controller" part of the application (in an classic MVC view). + * The commandsManager singleton is in charge of wiring all the commands inside the application. + * + */ \ No newline at end of file diff --git a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/remote/RequestManager.js b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/remote/RequestManager.js index d6173b62a..0b79b272d 100644 --- a/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/remote/RequestManager.js +++ b/org.argeo.slc.webapp/src/main/webapp/source/class/org/argeo/ria/remote/RequestManager.js @@ -1,9 +1,22 @@ +/** + * A management class for all request sent to the server + * Basically, to access the server, always get a new Request object from this class. + * It will then trigger various user-interface events during the Request lifecycle. + * + * For the moment, it's about the "Stop" button command, handling any passed ILoadStatusable states, + * and logging the Request status/errors. + * + * @author Charles du Jeu + */ qx.Class.define("org.argeo.ria.remote.RequestManager", { type : "singleton", extend : qx.core.Object, events : { + /** + * Triggered on the user demand at the end of the Request + */ "reload" : "org.argeo.ria.event.ReloadEvent" }, @@ -12,11 +25,26 @@ qx.Class.define("org.argeo.ria.remote.RequestManager", }, members : { - + /** + * Sets the unique "stop" command of the application. + * @param stopCommand {org.argeo.ria.event.Command} The command + */ setStopCommand : function(stopCommand){ this.command = stopCommand; }, + /** + * Creates a Request and handle various parts of its lifecycle. + * @see org.argeo.ria.event.ReloadEvent + * @see org.argeo.ria.components.ILoadStatusable + * + * @param url {String} The server url + * @param method {String} Connexion method (POST, GET, etc.) + * @param responseType {String} Expected response mime type (application/xml, etc...). + * @param fireReloadEventType {String} On user-demand, if this parameter is not null, a org.argeo.ria.event.ReloadEvent will be triggered when the request is completed. + * @param iLoadStatusables {Array} An array of ILoadStatusable implementations that need to be updated by the Request state (loading/ended). + * @return {qx.io.remote.Request} + */ getRequest : function(url, method, responseType, fireReloadEventType, iLoadStatusables){ var request = new qx.io.remote.Request(url, method, responseType); if(iLoadStatusables){ @@ -35,20 +63,37 @@ qx.Class.define("org.argeo.ria.remote.RequestManager", return request; }, + /** + * Creates a ReloadEvent and fire it. + * @param dataType {String} The data type + * @param content {mixed} The content of the request response. + */ fireReloadEvent : function(dataType, content){ this.fireEvent("reload", org.argeo.ria.event.ReloadEvent, [dataType, content]); }, + /** + * Triggered when request is created + * @param e {qx.event.type.Event} The event + */ requestCreated : function(e){ var request = e.getTarget(); this.enableCommand(request); }, + /** + * Triggered when request is completed normally + * @param e {qx.event.type.Event} The event + */ requestCompleted : function(e){ var request = e.getTarget(); this.disableCommand(request); }, + /** + * Triggered when request is completed abnormally + * @param e {qx.event.type.Event} The event + */ requestTerminated : function(e){ var request = e.getTarget(); var errorType = e.getType(); @@ -64,6 +109,10 @@ qx.Class.define("org.argeo.ria.remote.RequestManager", this.error(message); }, + /** + * Triggered by a request creation. Update the GUI parts according to its status. + * @param request {qx.io.remote.Request} The current Request + */ disableCommand : function(request){ this.command.setEnabled(false); if(request.getUserData("iLoadStatusables")){ @@ -75,6 +124,10 @@ qx.Class.define("org.argeo.ria.remote.RequestManager", } }, + /** + * Triggered by a request ending. Update the GUI parts according to its status. + * @param request {qx.io.remote.Request} The current Request + */ enableCommand : function(request){ this.command.setEnabled(true); if(request.getUserData("iLoadStatusables")){ @@ -86,6 +139,11 @@ qx.Class.define("org.argeo.ria.remote.RequestManager", this.command.addListener("execute", listener, request); }, + /** + * Update the ILoadStatusable implementations + * @param iLoadStatusables {Array} An array of ILoadStatusable + * @param loadStatus {Boolean} The current status of a request + */ updateGuiParts : function(iLoadStatusables, loadStatus){ for(var i=0;i