From e3ae72208feba2b542520878574d49ac16917573 Mon Sep 17 00:00:00 2001 From: Charles du Jeu Date: Tue, 10 Mar 2009 10:53:52 +0000 Subject: [PATCH] API Documentation git-svn-id: https://svn.argeo.org/slc/trunk@2244 4cfe0d0a-d680-48aa-b62c-e0a02a3f76cc --- .../org/argeo/slc/ria/NewLauncherApplet.js | 28 +++++++++++- .../argeo/slc/ria/execution/BatchEntrySpec.js | 19 +++++++- .../class/org/argeo/slc/ria/execution/Flow.js | 19 ++++++++ .../org/argeo/slc/ria/execution/Module.js | 15 +++++-- .../class/org/argeo/slc/ria/execution/Spec.js | 4 ++ .../org/argeo/slc/ria/execution/SpecEditor.js | 21 ++++++--- .../org/argeo/slc/ria/execution/Value.js | 26 +++++++++++ .../argeo/ria/components/DynamicTreeFolder.js | 45 ++++++++++++++++++- 8 files changed, 165 insertions(+), 12 deletions(-) diff --git a/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/NewLauncherApplet.js b/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/NewLauncherApplet.js index 4fb4c3048..037e7b79a 100644 --- a/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/NewLauncherApplet.js +++ b/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/NewLauncherApplet.js @@ -25,7 +25,10 @@ qx.Class.define("org.argeo.slc.ria.NewLauncherApplet", check:"org.argeo.ria.components.ViewSelection" }, instanceId : {init:""}, - instanceLabel : {init:""}, + instanceLabel : {init:""}, + /** + * A boolean registering whether the SpecEditor must autoOpen or not when a spec is added to the Batch. + */ autoOpen : { init : true, check : "Boolean" @@ -183,6 +186,10 @@ qx.Class.define("org.argeo.slc.ria.NewLauncherApplet", }, statics : { + /** + * Loader for the "flow" level : takes a folder containing "moduleData" and create its children. + * @param folder {qx.ui.tree.TreeFolder} A Tree folder containing in the key "moduleData" of its user data a map containing the keys {name,version} + */ flowLoader : function(folder){ var moduleData = folder.getUserData("moduleData"); //var req = org.argeo.ria.remote.RequestManager.getInstance().getRequest("../argeo-ria-src/stub.xml", "GET", "application/xml"); @@ -202,6 +209,10 @@ qx.Class.define("org.argeo.slc.ria.NewLauncherApplet", req.send(); }, + /** + * Loader for the "modules" level : takes any tree folder, currently the root folder. + * @param folder {qx.ui.tree.TreeFolder} The root folder + */ modulesLoader : function(folder){ var req = org.argeo.slc.ria.SlcApi.getListModulesService(); req.addListener("completed", function(response){ @@ -428,7 +439,12 @@ qx.Class.define("org.argeo.slc.ria.NewLauncherApplet", splitPane.add(this.tree, 0); splitPane.add(this.listPane, 1); }, - + + /** + * Adds a given ExecutionFlow to the batch + * @param target {mixed} The dropped target, can be a TreeFile (add) or a ListItem (reorder). + * @param after {qx.ui.form.ListItem} Optional list item : if set, the flow will be added as a new list item positionned after this one. + */ _addFlowToBatch : function(target, after){ //this.debug(target); if(!target){ @@ -483,6 +499,10 @@ qx.Class.define("org.argeo.slc.ria.NewLauncherApplet", if(menu.length) command.setEnabled(true); }, + /** + * Create XMLString to send for execution + * @return {String} + */ currentBatchToXml : function(){ var selection = this.list.getChildren(); var xmlString = ""; @@ -493,6 +513,10 @@ qx.Class.define("org.argeo.slc.ria.NewLauncherApplet", return xmlString; }, + /** + * Called at execution + * @param agentUuid {String} The id of the target agent + */ executeBatchOnAgent : function(agentUuid){ //var xmlString = agentUuid + this.currentBatchToXml(); var xmlString = ""+this.currentBatchToXml()+""; diff --git a/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/BatchEntrySpec.js b/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/BatchEntrySpec.js index 9d1508a2b..3511ac5a9 100644 --- a/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/BatchEntrySpec.js +++ b/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/BatchEntrySpec.js @@ -5,11 +5,25 @@ qx.Class.define("org.argeo.slc.ria.execution.BatchEntrySpec", { extend : org.argeo.slc.ria.execution.Spec, properties : { + /** + * Reference module + */ module :{}, + /** + * Reference flow + */ flow : {}, + /** + * Original Spec (values shall stay untouched). + */ originalSpec : {} }, + /** + * Instance of BatchEntrySpec + * @param module {org.argeo.slc.ria.execution.Module} Reference module + * @param flow {org.argeo.slc.ria.execution.Flow} Reference flow + */ construct : function(module, flow){ this.base(arguments); this.setModule(module); @@ -20,7 +34,10 @@ qx.Class.define("org.argeo.slc.ria.execution.BatchEntrySpec", { }, members : { - + /** + * Create a label to display in the batch list. + * @return {String} The label + */ getLabel : function(){ var label = this.getModule().getName(); label += "/" + this.getModule().getVersion(); diff --git a/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/Flow.js b/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/Flow.js index 124e14e8a..10473aa5c 100644 --- a/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/Flow.js +++ b/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/Flow.js @@ -25,6 +25,9 @@ qx.Class.define("org.argeo.slc.ria.execution.Flow", { executionSpec : { check : "org.argeo.slc.ria.execution.Spec" }, + /** + * The values to init the ExecutionSpec + */ values : { check : "Node" }, @@ -37,8 +40,17 @@ qx.Class.define("org.argeo.slc.ria.execution.Flow", { }, statics : { + /** + * Xpath to the name + */ XPATH_NAME : "@name", + /** + * XPath to the ExecutionSpec name + */ XPATH_EXEC_SPEC_NAME : "@executionSpec", + /** + * XPath to the values + */ XPATH_VALUES : "slc:values" }, @@ -59,6 +71,13 @@ qx.Class.define("org.argeo.slc.ria.execution.Flow", { var values = org.argeo.ria.util.Element.selectNodes(xmlNode, this.self(arguments).XPATH_VALUES); this.setValues(values[0]); }, + /** + * Get a given value inside the values map + * @param key {String} The key of the value + * @param specType {String} Expected type (currently "primitive" and "ref" are supported) + * @param specSubType {String} Expected subtype (depends on the type) + * @return {String} Value if it is set. + */ getValue: function(key, specType, specSubType){ var xpath; if(specType == "primitive"){ diff --git a/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/Module.js b/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/Module.js index c95b9915b..5e5343184 100644 --- a/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/Module.js +++ b/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/Module.js @@ -56,7 +56,7 @@ qx.Class.define("org.argeo.slc.ria.execution.Module", { members : { /** * Add an execution flow to this module - * @param executionFlow {org.argeo.slc.ria.execution.Flow} + * @param executionFlow {org.argeo.slc.ria.execution.Flow} An instance of execution.Flow */ addExecutionFlow : function(executionFlow){ var spec = this.getExecutionSpecByName(executionFlow.getExecutionSpecName()); @@ -70,16 +70,25 @@ qx.Class.define("org.argeo.slc.ria.execution.Module", { /** * Add an execution Spec to this module - * @param executionSpec {org.argeo.slc.ria.execution.Spec} + * @param executionSpec {org.argeo.slc.ria.execution.Spec} An instance of ExecutionSpec */ addExecutionSpec : function(executionSpec){ this.getExecutionSpecs()[executionSpec.getName()] = executionSpec; }, - + /** + * Find an execution spec by its name + * @param name {String} Name of the spec + * @return {org.argeo.slc.ria.execution.Spec} The spec + */ getExecutionSpecByName : function(name){ return this.getExecutionSpecs()[name]; }, + /** + * Find an execution flow by its name + * @param name {String} name of the flow + * @return {org.argeo.slc.ria.execution.Flow} The flow + */ getExecutionFlowByName : function(name){ return this.getExecutionFlows()[name]; }, diff --git a/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/Spec.js b/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/Spec.js index 680cc9993..2a7a3c039 100644 --- a/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/Spec.js +++ b/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/Spec.js @@ -55,6 +55,10 @@ qx.Class.define("org.argeo.slc.ria.execution.Spec", { } this.setValues(parsedValues); }, + /** + * XML Representation of this object. + * @return {String} An XML String + */ toXml : function(){ var valuesXml = ''; var values = this.getValues(); diff --git a/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/SpecEditor.js b/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/SpecEditor.js index d4b621781..59d8e8661 100644 --- a/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/SpecEditor.js +++ b/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/SpecEditor.js @@ -8,6 +8,9 @@ qx.Class.define("org.argeo.slc.ria.execution.SpecEditor", extend : qx.ui.window.Window, properties : { + /** + * The Spec to edit + */ batchEntrySpec : { check : "org.argeo.slc.ria.execution.BatchEntrySpec" } @@ -18,14 +21,15 @@ qx.Class.define("org.argeo.slc.ria.execution.SpecEditor", * Triggered when the user clicks the "save" button. */ "save" : "qx.event.type.Event", + /** + * Triggered when any data is modified + */ "modified" : "qx.event.type.Event" }, /** - * - * @param caption {String} Title of the window - * @param icon {String} Icon of the window - * @param text {String} Default content of the window. + * Opens an editor with the given values. + * @param batchEntrySpec {org.argeo.slc.ria.execution.BatchEntrySpec} The initial spec to edit */ construct : function(batchEntrySpec){ var editorLabel = "Edit Specs for "+batchEntrySpec.getLabel(); @@ -51,6 +55,9 @@ qx.Class.define("org.argeo.slc.ria.execution.SpecEditor", }, members : { + /** + * Builds the form from the BatchEntrySpec + */ createFormFromSpec : function(){ var values = this.getBatchEntrySpec().getValues(); for(var key in values){ @@ -66,7 +73,9 @@ qx.Class.define("org.argeo.slc.ria.execution.SpecEditor", } } }, - + /** + * Gather data from the form + */ saveFormToSpec : function(){ var values = this.getBatchEntrySpec().getValues(); for(var key in values){ @@ -117,6 +126,8 @@ qx.Class.define("org.argeo.slc.ria.execution.SpecEditor", * @param fieldLabel {String} Label of the field * @param defaultValue {String} The default value * @param choiceValues {Map} An map of values + * @param disabled {Boolean} The field is not writable + * @param subType {String} The type expected (string, integer, etc). */ _addFormInputText : function(formObject, fieldName, fieldLabel, defaultValue, disabled, subType, choiceValues){ var labelElement; diff --git a/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/Value.js b/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/Value.js index 6ce99a06c..29556d886 100644 --- a/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/Value.js +++ b/org.argeo.slc.webapp/src/main/webapp/argeo-ria-lib/slc/class/org/argeo/slc/ria/execution/Value.js @@ -13,22 +13,40 @@ qx.Class.define("org.argeo.slc.ria.execution.Value", { check : "String", init : "" }, + /** + * The type of this value, for the moment "primitive" and "ref" are supported + */ specType : { check : "String", init : "" }, + /** + * Subtype, depending on the "type". + */ specSubType : { check : "String" }, + /** + * Whether it is a parameter or not + */ parameter : { check : "Boolean" }, + /** + * Whether it is frozen on the server, i.e. disabled in the form + */ frozen : { check : "Boolean" }, + /** + * Should not be editable nor seeable, thus hidden + */ hidden : { check : "Boolean" }, + /** + * The real value + */ value : { nullable : true }, @@ -77,6 +95,10 @@ qx.Class.define("org.argeo.slc.ria.execution.Value", { } }, + /** + * Apply the value from the node + * @param xmlNode {Node} Castor representation of this object + */ _applyXmlValue : function(xmlNode){ var xpath; if(this.getSpecType() == "primitive"){ @@ -87,6 +109,10 @@ qx.Class.define("org.argeo.slc.ria.execution.Value", { this.setValue(org.argeo.ria.util.Element.getSingleNodeText(xmlNode, xpath)); }, + /** + * Create an XML Representation of this value + * @return {String} The XML String + */ toXml : function(){ var valueTag = ''+this.getValue()+''; var specAttribute = ''; diff --git a/org.argeo.slc.webapp/src/main/webapp/argeo-ria-src/class/org/argeo/ria/components/DynamicTreeFolder.js b/org.argeo.slc.webapp/src/main/webapp/argeo-ria-src/class/org/argeo/ria/components/DynamicTreeFolder.js index 76509f3ef..6841b700d 100644 --- a/org.argeo.slc.webapp/src/main/webapp/argeo-ria-src/class/org/argeo/ria/components/DynamicTreeFolder.js +++ b/org.argeo.slc.webapp/src/main/webapp/argeo-ria-src/class/org/argeo/ria/components/DynamicTreeFolder.js @@ -6,25 +6,45 @@ qx.Class.define("org.argeo.ria.components.DynamicTreeFolder", { extend : qx.ui.tree.TreeFolder, properties : { + /** + * The current state of the folder, usually "empty" => "loading" => "loaded" + */ "state" : { check : "String", init : "empty", apply : "_applyState" }, + /** + * String to display as a child node during loading + */ "loadingString" : { check : "String", init : "Loading..." }, + /** + * Function that will load the children of this folder + */ "loader" : { check : "Function", init : function(treeFolder){treeFolder.setLoaded();} }, + /** + * Optionnal data describing the "drag" behaviour of the created children. + * First level is "file" or "folder", and for each of them, supported keys are "type" and "action". + */ "dragData": { check : "Map", init : {} } }, + /** + * Creates a new instance of DynamicTreeFolder + * @param label {String} Label of the folder + * @param loader {Function} Function that will load the children + * @param loadingString {String} String to display as a child node during loading + * @param dragData {Map} Optionnal data describing the "drag" behaviour of the created children. + */ construct : function(label, loader, loadingString, dragData){ this.base(arguments, label); if(loader) this.setLoader(loader); @@ -39,7 +59,10 @@ qx.Class.define("org.argeo.ria.components.DynamicTreeFolder", { }, members : { - + /** + * Add an item to the folder + * @param varargs {Mixed} One or many children to add + */ add : function(varargs){ this.base(arguments, varargs); for (var i=0, l=arguments.length; i