rsence 2.0.0.10.pre → 2.0.0.11

data/docs/PluginBundles.rdoc

@@ -0,0 +1,96 @@
+
+= Overview
+Plugin bundles are the "building blocks" of RSence applications.
+A bundle is a directory that groups together the software code
+and its related resources.
+
+Plugin bundles are constructed of at least a directory and a ruby
+source file either named "main.rb" or the same name as the
+directory plus + ".rb".
+
+The main ruby file has to contain at least one class extended from one
+of the three types of plugins:
+- {RSence::Plugins::Plugin__ Plugin}, which is the simplest main logic plugin model.
+- {RSence::Plugins::GUIPlugin__ GUIPlugin}, which is an extended model of plugin with built-in user interface support.
+- {RSence::Plugins::Servlet__ Servlet}, which is a "traditional" request/response handler for GET/POST url's.
+
+== Example 1: A very simple plugin bundle structure
+  !!!plain
+  simple_plugin/
+  `-- main.rb
+
+=== Simplest possible contents of the "main.rb" as above
+  class SimplePlugin < Plugin
+  end
+
+A plugin like this just gets registered as a plugin named :simple_plugin when RSence finds it in one of its "plugins" directories. By default, one "plugins" directory is distributed as a part of RSence and contains some core services common to most applications. The other is the "plugins" directory inside your RSence project environment directory.
+
+To make the plugin do something useful, extend its model. To know more about that, just read the documentation about the model classes: {RSence::Plugins::Plugin__ Plugin}, {RSence::Plugins::GUIPlugin__ GUIPlugin}, {RSence::Plugins::Servlet__ Servlet}.
+
+=== Extending the simple plugin to say "Hello" to your web browser's javascript console.
+  class SimplePlugin < Plugin
+    def init_ui( msg )
+      msg.console( "Hello" )
+    end
+  end
+
+== Example 2: {file:ExampleGuiPlugin The "welcome" GUIPlugin bundle}
+This example is rather lengthy, so read it {file:ExampleGuiPlugin here}.
+
+
+= Plugin meta-information files
+
+These files are optional parts of a bundle, but are supported by the system. Most bundles will contain several other files as well, as defined by each bundle's software code.
+
+=== Supported by all bundle types, including {RSence::Plugins::Servlet__ Servlet}:
+- An {file:PluginBundleInfo info.yaml file}
+  - Defines the meta-information about the bundle, like its name, description, version, system requirements, dependencies etc.
+  - Each bundle *should* include an +info.yaml+ file.
+  - Any extra information, like default settings of the plugin itself can be stored here
+
+=== Supported by {RSence::Plugins::Plugin__ Plugin} and {RSence::Plugins::GUIPlugin__ GUIPlugin} bundles:
+- A {file:Values values.yaml file}
+  - Defines the default client-server {RSence::HValue HValue} objects to create for each user session.
+    - Contains what the default data is for each value.
+    - Defines if the data should be reset when the page is reloaded.
+    - Defines if the data should be the return-value of a plugin method.
+  - Binds the values to responder methods.
+    - Defines which plugins to bind
+      - The plugin defaults to the plugin bundle which defined the method
+    - Defines which methods to bind
+      - When the data of the value is changed by the client, the system calls the bound plugin methods to respond to and validate the data.
+
+=== Supported by {RSence::Plugins::GUIPlugin__ GUIPlugin} bundles:
+- A {file:JavascriptBundles client_pkgs.yaml file}
+  - Defines the packages of any extra javascript bundles and their themes, when contained in the bundle.
+    - The contents of the packages are loaded and built automatically by the built-in {ClientPkgPlugin +client_pkg+} plugin.
+- A {file:GUITreeYaml gui/main.yaml file}
+  - Instead of +main.yaml+, can optionally be named like +simple_plugin.yaml+ if the bundle name is +simple_plugin+
+  - Defines structure of the default user interface.
+  - Defines client-side {RSence::HValue value} bindings
+    - The values used must be defined, like using the {file:Values +values.yaml+} file
+  - May define other mappings, like localized strings and other static data.
+  - The system builds a user interface based on this file automatically when a RSence web page is loaded (and reloaded) by the user.
+
+= Values and data transfer
+The description is rather lengthy, so it's in its own document {file:Values HERE}.
+
+= Messages and sessions
+As a side effect of having the same instances of plugins serve the requests of all sessions, the request/response/session messaging is implemented as messaging objects. These objects contain or delegate all the necessary hooks required by the complete request/response cycle.
+
+The naming convention of the {RSence::Message Message} instance is +msg+ and it's given as the first parameter of methods using it directly.
+
+Use {RSence::Message#session_id +msg.session_id+} to identify the session's serial number and {RSence::Message#user_id +msg.user_id+} to identify the user's identity. Both are Numbers.
+
+Use the {RSence::Message#session +msg.session+} +Hash+ to store any persistent data associated with the user's session, preferably using the name of the plugin or its registered name as the primary key entry in the Hash. To do so automatically, just call the {RSence::Plugins::Plugin__#get_ses +get_ses+} method in your Plugin or GUIPlugin.
+
+The session data is persistent; it's stored in the session database by the main {RSence::SessionStorage SessionStorage} instance automatically, if a database connection string is properly configured.
+
+The +msg+  also provides access to the {RSence::Request +msg.request+} and {RSence::Response +msg.response+} objects directly, but don't mess around with them unless you know exactly what you are doing.
+
+Use the {RSence::PluginManager#method_missing +@plugins+} object to call other plugins, like this:
+  @plugins.plugin_name.method_name( param1, param2 )
+
+To append Javascript source code to be executed in the client, use the {RSence::Message#reply +msg.reply+} method. The {RSence::Message#console +msg.console+} method displays debugging messages in the browser's Javascript console.
+
+

data/docs/Values.rdoc

@@ -0,0 +1,163 @@
+= Overview
+The data exchange system exists to support bi-directional data synchronization between the browser and the plugin. The values are stored in the session as +HValue+ instances.
+
+Values support Hashes, Arrays, Strings, Numbers, Booleans and logically correct combinations of those. The data is automatically converted between ruby objects (server) and json objects (client). For dates and times, use Numbers as seconds since or before UTC epoch; (1970-01-01 00:00:00.0 equals 0.0) and convert accordingly for the representation intended.
+
+Each instance may be bound to plugin methods that are used as value change notification responders.
+
+When a method is bound to the value, the method is called as an event notification whenever the client has changed the value and synchronizes it to the server. The responders act as validators by default.
+
+Values may be bound in the client to instances of classes that implement the HValueResponder interface, like any derivate of HControl. See the client documentation for instructions about using them.
+
+To define a value responder method, it needs to respond to exactly two parameters: {RSence::Message +msg+} and {RSence::HValue +value+} (in that specific order). The method's return value must be either +true+ or +false+. When the method returns +false+, the change is discarded and the previously server-set value is sent back to the client.
+
+= Defining values
+The simplest and recommended way of defining the values is to define the value configuration file +values.yaml+ at the root level of your plugin bundle. The definition is then copied to each session automatically. Values created using +values.yaml+ files are accessible by their name in each user's session object.
+
+For instance, if a value has been defined as +:myvalue+, it's accessible in code like this:
+  ses = get_ses(msg) # gets the session object of the local plugin
+  my_value = ses[:myvalue] # reference to the value instance
+
+=== Syntax reference of the contents of a +values.yaml+ file:
+
+The name of the value, +:value_name+ in this case. It's a Hash key in the yaml syntax
+  !!!yaml
+   :value_name:
+
+Definitions of the value; all definitions are optional.
+
+The static value definition, a string "Foo" in this case. The default is +0+
+  !!!yaml
+     :value: Foo
+
+A plugin method to call to define the default value dynamically instead of the static value defined in +:value+
+  !!!yaml
+     :value_call:
+
+The name of the plugin where the responder method is found. It Defaults to the plugin where defined
+  !!!yaml
+       :plugin: plugin_name
+
+The name of the responder method. Mandatory item when defining a value call. In this case a method named +method_name+
+  !!!yaml
+       :method: method_name
+
+Optionally, list of parameters for the +:method+ in the order of defined. In this case, three parameters: 1, 'foo' and 3
+  !!!yaml
+       :args:
+         - 1
+         - foo
+         - 3
+
+If +:uses_msg+ is set to false, the {RSence::Message +msg+} won't be passed as the first parameter to the +:method+. It's +true+ by default.
+  !!!yaml
+       :uses_msg: false
+
+Restores the default, when the session is restored (page reload etc); defaults to +true+
+  !!!yaml
+     :restore_default: false
+
+List of value responder methods to bind.
+  !!!yaml
+     :responders:
+
+The name of the plugin and the method to bind. The plugin defaults to the plugin where defined. The responder methods always use the convention (+msg+, +value+) as their parameters.
+  !!!yaml
+       - :plugin: plugin_name
+         :method: method_name
+
+Another responder, this one using the same plugin where defined:
+  !!!yaml
+       - :method: another_method
+
+==== Example 1:
+A value defined using only the defaults by supplying an empty Hash: { value: 0, default restored, no responders or calls }
+  !!!yaml
+   :value_with_defaults: {}
+
+==== Example 2:
+This value defines a Number (123) and doesn't restore the default, when restoring the session.
+  !!!yaml
+   :one_two_three:
+     :value: 123
+     :restore_default: false
+
+==== Example 3:
+This value gets a random string and specifies a responder, that ensures it's unique, if changed in the client. (Such methods aren't predefined).
+  !!!yaml
+   :random_unique_string:
+     :value_call:
+       :method:   get_unique_random_string
+       :uses_msg: false
+     :responders:
+       - :method: ensure_unique_random_string
+
+
+= Using values in code
+
+=== Creating a HValue object in ruby and creates the client representation automatically.
+Sometimes dynamic value allocation is required. In these cases, use {RSence::HValue HValue} directly in the plugin's ruby code (or any library code that gets a +msg+).
+ a_test_value = HValue.new( msg, 'any_json_mappable_data' )
+
+=== A minimal value responder method is defined like this:
+  def my_value_responder( msg, my_value )
+    return true
+  end
+
+=== To access the content of the value, use the {RSence::HValue#data +value.data+} attribute.
+  def int_between_100_and_200( msg, value )
+    data = value.data.to_i
+    return ( data >= 100 and data <= 200 )
+  end
+
+=== To change the content of the value, use the {RSence::HValue#set +value.set+} method.
+  def int_between_100_and_200( msg, value )
+    data = value.data.to_i
+    value.set( msg, 100 ) if data < 100
+    value.set( msg, 200 ) if data > 200
+    return true
+  end
+
+=== Setting a HValue object in ruby.
+Doing the change in ruby sets the client-side accordingly too and causes all client-bound value responders to receive the same data. automatically. The data is synchronized server-client after all server responders have responded to all triggers by the last client-server synchronization, so only the lastly set data of a value is sent to the client.
+  a_test_value.set( msg, 'this_wont_be_on_the_client' )
+  a_test_value.set( msg, ['neither','will','this','be',[true]] )
+  a_test_value.set( msg, { 'and' => 'this', 'also' => 'stays', 'in' => 'the', 'server' => [1,2,3,4] )
+  a_test_value.set( msg, 'this is the last one, this gets through' )
+
+=== Binding a HValue responder in ruby. Causes the client-server synchronization to respond to all the bound methods.
+  class SomeTestPlugin < Plugin
+    def resp_one( msg, value )
+      puts "got data: #{value.data.inspect}"
+      return true
+    end
+    def resp_two( msg, value )
+      revert_to = "foo foo"
+      value.set( msg, revert_to )
+      puts "got the data too, but changed it to: #{value.data.inspect}"
+      return true
+    end
+    def define_responders( msg )
+      ...
+      # the @name is the name of the plugin bundle
+      a_test_value.bind( @name, :resp_one )
+      a_test_value.bind( @name, :resp_two )
+    end
+  end
+
+=== Referring to the value manually in the client, using the server
+This references the value by id in the client scope and binds it to a new instance of the +HTextArea+ component with its own dedicated app instance.
+  msg.reply( "COMM.Values.values[#{a_test_value.value_id.to_json}].bind( HTextArea.nu( [0,0,100,100], HApplication.nu() ) );" )
+
+=== Storing a reference to a variable in the session scope.
+Allows you to retrieve this session-specific object in any scope with access to the same session's +msg+, even in other requests (and server restarts, when a {RSence::SessionStorage SessionStorage} database connection is enabled).
+  get_ses(msg)[:the_test_name] = a_test_value
+
+=== Freeing a HValue responder, won't be used as a responder anymore
+  a_test_value.release( @name, :resp_two )
+
+=== Freeing all responders of a value
+  a_test_value.release_all
+
+=== Destructing a value, releases all bindings on both client and server and destructs the client representation too
+  a_test_value.die!( msg )

data/js/comm/{comm/autosync → autosync}/autosync.js

@@ -10,8 +10,7 @@
 LOAD(
   function(){
     COMM.urlResponder=COMM.URLResponder.nu();
-    urlResponder=COMM.urlResponder; // backwards compatibility
-    COMM.Transporter.url=HCLIENT_HELLO;
+    COMM.Transporter.url=COMM.Transporter.HelloUrl;
     COMM.Transporter.stop=false;
     COMM.Transporter.sync();
   }

data/js/comm/{comm/comm.js → comm.js}

@@ -35,6 +35,7 @@
   **                         JavaScript code.
   **
 ***/
+var//RSence
 COMM = {
   
 /** Displays an error alert, if the browser doesn't support XMLHttpRequests

data/js/comm/jsloader/jsloader.js

@@ -14,6 +14,7 @@
   ** standard package url.
 ***/
 
+//var//RSence.Foundation
 COMM.JSLoader = HClass.extend({
   
 /** = Description
@@ -97,14 +98,11 @@ COMM.JSLoader = HClass.extend({
   }
 });
 
-/** -- Global reference ++ **/
-JSLoader = COMM.JSLoader;
-
 // Makes the standard jsLoader instance based on the client base url 
 // of the server when the page is loaded.
 LOAD(
   function(){
-    COMM.jsLoader = COMM.JSLoader.nu( HCLIENT_BASE + '/js/' );
+    COMM.jsLoader = COMM.JSLoader.nu( COMM.ClientPrefix + '/js/' );
     // backwards compatibility aliases:
     jsLoader = COMM.jsLoader;
   }

data/js/comm/{comm/queue → queue}/queue.js

@@ -14,6 +14,7 @@
   **
   ** COMM.Queue runs as a single instance, dan't try to reconstruct it.
 ***/
+//var//RSence.COMM
 COMM.Queue = HApplication.extend({
   
 /** The constructor takes no arguments and starts queue flushing automatically.

data/js/comm/{comm/session → session}/session.js

@@ -15,17 +15,18 @@
   ** The server expects this exact algorithm and refuses to serve unless
   ** the SHA1 hash sum of the keys matches.
   **
-  ** Uses a +SHAClass+ instance for generation.
+  ** Uses a +SHA+ instance for generation.
   **
-  ** +COMM.Queue+ runs as a single instance, dan't try to reconstruct it.
+  ** +COMM.Queue+ runs as a single instance, don't try to reconstruct it.
 ***/
+//var//RSence.COMM
 COMM.Session = HClass.extend({
   
 /** The constructor takes no arguments.
   **/
   constructor: function(){
     var _this = this;
-    _this.sha = SHAClass.nu(8);
+    _this.sha = SHA.nu(8);
     _this.sha_key = _this.sha.hexSHA1(((new Date().getTime())*Math.random()*1000).toString());
     _this.ses_key = '0:.o.:'+_this.sha_key;
     _this.req_num = 0;

data/js/comm/{comm/sessionwatcher → sessionwatcher}/sessionwatcher.js

@@ -21,6 +21,7 @@
   **   as the _timeoutSecs constructor parameter.
   **
 ***/
+//var//RSence.COMM
 COMM.SessionWatcher = HApplication.extend({
   constructor: function( _timeoutSecs, _sesTimeoutValueId ){
     

data/js/comm/{comm/transporter → transporter}/transporter.js

@@ -20,6 +20,7 @@
   **
   ** Don't call any of its methods from your code.
 ***/
+//var//RSence.COMM
 COMM.Transporter = HApplication.extend({
   
 /** Sets up the default settings upon construction.

data/js/comm/{comm/urlresponder → urlresponder}/urlresponder.js

@@ -17,6 +17,7 @@
   ** a client-side-only HValue instance until then.
   **
 ***/
+//var//RSence.COMM
 COMM.URLResponder = HApplication.extend({
   constructor: function(){
     this.urlMatchers = [];

data/js/comm/{comm/values → values}/values.js

@@ -11,6 +11,7 @@
   **
   ** Keeps track of all +HValue+ instances present.
 ***/
+//var//RSence.COMM
 COMM.Values = HClass.extend({
   
 /** No constructor, singleton class.

data/js/controls/button/button.js

@@ -13,8 +13,11 @@
   ** It's limited to 24px height by the default theme, because
   ** it's much simpler to render that way.
   ***/
+var//RSence.Controls
 HButton = HControl.extend({
+  
   componentName: 'button',
+  
 /** = Description
   * setStyle function for button.
   *
@@ -23,8 +26,10 @@ HButton = HControl.extend({
     ELEM.setStyle(this.markupElemIds.label,_name,_value);
     return this;
   }
+  
 });
 
+
 /*** = Description
   ** Simple HButton extension, operates on its value so it's useful
   ** for sending button clicks to the server and the like.
@@ -36,6 +41,7 @@ HButton = HControl.extend({
   ** +1+::     Disabled, clicked
   ** +Other+:: Disabled, not clickable, not clicked
   ***/
+var//RSence.Controls
 HClickButton = HButton.extend({
   
   defaultEvents: {
@@ -58,6 +64,9 @@ HClickButton = HButton.extend({
       this.setValue(1);
     }
   }
+  
 });
 
-HClickValueButton = HClickButton;
+var//RSence.Controls
+HClickValueButton = HClickButton;
+

data/js/controls/checkbox/checkbox.js

@@ -10,6 +10,7 @@
   ** Simple checkbox component, toggles the value of
   ** itself between true and false.
   ***/
+var//RSence.Controls
 HCheckbox = HButton.extend({
   componentName: 'checkbox',
   
@@ -44,4 +45,5 @@ HCheckbox = HButton.extend({
   }
 });
 //-- Alias for some users:++
+var//RSence.Controls
 HCheckBox = HCheckbox;

data/js/controls/dialogs/alert_sheet/alert_sheet.js

@@ -10,6 +10,7 @@
   ** HAlertSheet is a simple alert notification control.
   ***/
 
+var//RSence.Controls
 HAlertSheet = HSheet.extend({
 
 /** = Description