rhodes 2.3.2 → 2.4.0.beta.1

data/doc/configuration.txt

@@ -98,11 +98,6 @@ Log file prefix - contain human-readable text
 
 	logname='helloworld'
 
-Keep track of the last visited page
-
-	KeepTrackOfLastVisitedPage = 0 
-	LastVisitedPage = ''
-
 Sync server url, typically this will look like 'http://<hostname>:<port>/application'. For example:
 
 	syncserver = 'http://localhost:9292/application'
@@ -162,11 +157,7 @@ To use only models from bulk database. If true, application will not create mode
 	use_bulk_model = true
 	
 ### Last Visited Page
-Rhodes can keep track of the last visited page, so that next time you start your application, it will open to the same page. To enable this feature, use 
-
-	KeepTrackOfLastVisitedPage=1
-
-Keep in mind, POST requests will be converted to GETs.
+To save/restore last visited page use WebView.current_location in on_ui_created/on_ui_destroyed of [AppAplication class](application#appapplication-class).
 
 ### Application Database Version
 If you want the next version of your application to start from a clean database, set app_db_version in rhoconfig.txt.

data/doc/connect-to-web-services.txt

@@ -9,7 +9,7 @@ Below is the list of available `AsyncHttp` methods you can use to asyncrhonously
 * `:url` - URL of the request.
 * `:headers` - Hash of headers to send with the request.
 * `:callback` - Callback action to execute when the request is done.
-* `:callback_params` - (optional) Parameters to send to the callback.
+* `:callback_param` - (optional) Parameters to send to the callback.
 * `:authentication` - (optional) Send Basic Auth header with request.  This takes the form:
 		
 		:authentication => {
@@ -20,8 +20,8 @@ Below is the list of available `AsyncHttp` methods you can use to asyncrhonously
 		
 * `:ssl_verify_peer` - (optional) Verify SSL certificates, `true` by default.
 
-### `get(:url, :headers, :callback, :callback_params)`
-Perform HTTP GET request to the specified `:url`.  You can also provide an optional hash of `:headers` and `:callback_params`.
+### `get(:url, :headers, :callback, :callback_param)`
+Perform HTTP GET request to the specified `:url`.  You can also provide an optional hash of `:headers` and `:callback_param`.
 
 	:::ruby
 	Rho::AsyncHttp.get(
@@ -55,7 +55,7 @@ Example of synchronous call:
 **NOTE: WARNING! Do NOT use synchronous calls unless you know what you are doing.  This is a blocking call and will cause your UI to freeze.**
 
 
-### `post(:url, :headers, :body, :callback, :callback_params)`
+### `post(:url, :headers, :body, :callback, :callback_param)`
 Perform HTTP POST request to the specified `:url`.  As with `get`, you can specify optional arguments:
 
 	:::ruby
@@ -70,7 +70,7 @@ Perform HTTP POST request to the specified `:url`.  As with `get`, you can speci
 	  :callback_param => "post=complete" 
 	)
 	
-### `download_file(:url, :headers, :filename, :callback, :callback_params)`
+### `download_file(:url, :headers, :filename, :callback, :callback_param)`
 Download a file to the specified filename.
 
 	:::ruby
@@ -84,7 +84,7 @@ Download a file to the specified filename.
 	  :callback => url_for(:action => :httpdownload_callback),
 	)
 	
-### `upload_file(:url, :headers, :filename, :body, :callback, :callback_params)`
+### `upload_file(:url, :headers, :filename, :body, :callback, :callback_param)`
 Upload the specified file using HTTP POST:
 
 	:::ruby	

data/doc/device-caps.txt

@@ -45,6 +45,7 @@ Properties:
 * has_camera - is camera available on the device
 * screen_width - screen width in pixels
 * screen_height - screen height in pixels
+* screen_orientation - screen orientation 'portrait', 'landscape'
 * ppi_x - horizontal PPI (Pixels Per Inch)
 * ppi_y - vertical PPI (Pixels Per Inch)
 * has_network - is device connected to the network
@@ -71,7 +72,7 @@ Enable\disable phone sleep by timeout, return previous state
 	:::ruby
 	System.set_sleeping
 
-Open application associated with url; behavior may be different on different platforms and depend on installed software
+Open application associated with url; behavior may be different on different platforms and depend on installed software. On iPhone, if you post path of local file, then the specific iOS control (UIDocumentInteractionController) where file will previewed and user will be able open this file by selected application wich supported this filetype.
 	:::ruby
 	System.open_url(url)
 
@@ -95,7 +96,7 @@ Unzip file to the same folder where zip file is
 	:::ruby
 	System.unzip_file(local_path_to_zip)
 
-Return command line parameters as a string
+Return command line parameters as a string. Worked only on iPhone now. Resetting when application go to background. If your URLBundle is "myapp" and you open application by url: "myapp:/app/page1", then start params will "/app/page1". 
 	:::ruby
 	System.get_start_params() 
 
@@ -116,6 +117,12 @@ See the [Configuration](configuration#build-time-configuration) section for more
 
 The GPS receiver consumes a significant amount of energy, and should be switched off most of the time in order to preserve the device's battery life. Any call to get location information will power up the GPS receiver. Also note that it usually takes a while to acquire the device's current position; in some cases, it may take several minutes and may not work at all indoors.
 
+Note that in old rhodes versions (up to 2.3.1) this feature uses only GPS location provider;
+however, in new rhodes it also use network based location determination. Network based location
+is not so precise as GPS but in most cases it consume less power and return results faster than GPS.
+Rhodes will update location using network data until GPS has started; then only GPS will be used
+as more precise data.
+
 ### Asynchronous Ajax calls
 
 The Rhodes framework provides a simple HTML tag for accessing Geolocation information. To use it, include the appropriate javascript library on your page:
@@ -151,7 +158,7 @@ Set callback to track location changes.
 
 	:::ruby
 	GeoLocation.set_notification(
-		callback, callback_params="", ping_gpssystem_timeout=0)
+		callback, callback_param="", ping_gpssystem_timeout=0)
 
 * callback - callback url; it will be called only once, to have it called again, you need to call set_notification again.
 * ping_gpssystem_timeout  - optional, if 0 system timeout used, use to redefine timeout in sec for gps system reading
@@ -770,13 +777,13 @@ In your controller, you may call on system alert methods to show popup, vibrate,
 
 You can also customize popup window's title, icon, buttons and specify callback to be called on button click:
 	:::ruby
-	Alert.show_popup {
+	Alert.show_popup( {
 		:message => 'Some message', 
 		:title => 'Custom title', 
 		:icon => '/public/images/icon.png',
 	    :buttons => ["Yes", "No", 
 			{:id => 'cancel', :title => 'Cancel all'}],
-	    :callback => url_for(:action => :on_dissmiss_popup) }
+	    :callback => url_for(:action => :on_dissmiss_popup) } )
 
 Popup window always close after clicking on any button.
 
@@ -837,6 +844,22 @@ For example you can use Alert.show_status in sync notification callback:
 		Rho::RhoMessages.get_message('hide'))
 	end
 
+## Timer
+
+In your controller, you may start timer using Rho::RhoTimer class:
+
+** start_timer ** - start timer and call callback after some interval
+	:::ruby
+	Rho::RhoTimer.start_timer(interval_milliseconds, callback_url, callback_data)
+
+For example:
+    :::ruby
+	Rho::RhoTimer.start_timer(5000, (url_for :action => :timer_callback), "test")
+	
+** stop_timer ** - stop timer by callback
+	:::ruby
+	Rho::RhoTimer.stop_timer(callback_url)
+		
 ## Screen rotation
 When user rotate device, Rhodes update view corresponding to new orientation. To get notification about rotation use callback:
 	:::ruby
@@ -859,6 +882,23 @@ Use rho_open_target=_blank in html link. Note that jqtouch or other javascript l
 ### Sample
 See CustomUri of [system API sample application](http://github.com/rhomobile/rhodes-system-api-samples/tree/master/app/CustomUri/controller.rb) for example.
 
+## Run rhodes application from browser
+On Android it is possible to start rhodes app by http link from browser. It is also possible to register custom URI scheme for the app.
+By default the http://com.vendor.appname URI format is used. If custom URI scheme is set up in build.yml then this scheme is used followed by any string.
+
+http scheme example:
+    :::html
+    <a href="http://com.rhomobile.rhodessystemapisamples">Open System API Samples</a>
+
+Custom scheme example:
+    :::ruby
+    android:
+        BundleURLScheme: rhodes
+
+    :::html
+    <a href="rhodes://any_string_here">Open System API Samples</a>
+
+
 ## MapView
 MapView class provides an embeddable map interface, similar to the one provided by the Maps application. The following code would go into your controller and the map appears on a whole page.
 
@@ -1022,6 +1062,9 @@ Open link in external application (browser for http:// links):
 
 Open appstore on iphone: [http://wiki.akosma.com/IPhone_URL_Schemes#App_Store](http://wiki.akosma.com/IPhone_URL_Schemes#App_Store)
 
+### Blackberry
+On Blackberry 5.0 and later you can use JavaScript [blackberry.launch object](http://docs.blackberry.com/en/developers/deliverables/18446/blackberry_launch_971534_11.jsp#blackberry_launch_newMap_971532_11)
+to create SMS, make Phone call etc.
 
 ## BlackBerry network connection
 Rhodes may use any Blackberry network connection available on the device. What particular network connection will be selected depends on the url suffix used to connect. Here is the algorithm:

data/doc/extensions.txt

@@ -41,7 +41,7 @@ In case of several extensions, insert space after extension name and comma:
 
 	extensions: ["rholang", "net-http"]
 
-Create utf-8 encoded file in app `<app_folder>/app/lang/lang_<lang_id>.rb`. This file will be automatically loaded by rhodes based on current locale.
+Create utf-8 encoded file in app `<app_folder>/app/lang/lang_<lang_id>_<country_id>.rb` or `<app_folder>/app/lang/lang_<lang_id>.rb`. This file will be automatically loaded by rhodes based on current locale.
 
 For Example create lang_en.eb:
 	:::ruby
@@ -528,6 +528,13 @@ Make sure following folder added to your compiler include path:
 * [$(RHO_ROOT)/platform/shared/ruby/iphone](http://github.com/rhomobile/rhodes/tree/master/platform/shared/ruby/iphone/)
 * [$(RHO_ROOT)/platform/shared/common](http://github.com/rhomobile/rhodes/tree/master/platform/shared/common/)
 
+### url_for_nativeview
+Examples of how to use the url_for_nativeview method:
+    
+	url_for_nativeview :name => 'rainbow_view', :param => 'red'
+	==> rainbow_view:red
+
+
 ## Using LineaSDK in Rhodes (with using special Linea native extension)
 Please see documentation :  [LineaSDK as native extension in Rhodes applications](linea) 
 

data/doc/rhom.txt

@@ -371,6 +371,12 @@ The `:order` argument accepts several forms:
 ### `find_all(*args)`
 Alias for find(:all,*args).
 
+### `find_by_sql(sql_query)`
+Returns rhom object(s) based on sql_query. This method works only for schema models:
+
+    :::ruby
+    @accts = Account.find_by_sql("SELECT * FROM Account")
+
 ### `new(attributes = nil)`
 Creates a new rhom object and assigns given attributes, or initializes an empty rhom object.
 
@@ -771,6 +777,16 @@ You can also group `:conditions`:
 	  :select => ['name','industry','description']
 	)
 
+## Find by numeric field
+To use number comparison conditions in find use CAST :
+    :::ruby
+    @accts = Account.find(:all, 
+        :conditions => { {:func=> 'CAST', :name=>'rating as INTEGER', :op=>'<'} => 3 } )
+    #or using sql query:
+    size = 3
+    @accts = Account.find(:all, 
+        :conditions => ["CAST(rating as INTEGER)< ?", "#{size}"], :select => ['rating'] )
+        
 ## Database Encryption
 If your application requires that the local database is encrypted on the filesystem, you can enable it by setting a flag in `build.yml`:
 

data/doc/synchronization.txt

@@ -154,7 +154,7 @@ These parameters are included in all notifications.
 
 For "login-error", "query-error", "logoff-error": Type object is hash contains 'message'  from server: @params["server_errors"]["query-error"]['message']
 
-For "create-error", "update-error", "delete-error": Type object is hash each containing an "object" as a key (that failed to create) and a corresponding "message": @params["server_errors"]["create-error"][object]['message']
+For "create-error", "update-error", "delete-error": Type object is hash each containing an "object" as a key (that failed to create) and a corresponding "message" and "attributes": @params["server_errors"]["create-error"][object]['message'], @params["server_errors"]["create-error"][object]['attributes']
 
 **NOTE: "create-error" has to be handled in sync callback. Otherwise sync will stop on this model. To fix create errors you should call Model.on_sync_create_error or SyncEngine.on_sync_create_error**
 
@@ -171,21 +171,46 @@ This status returns for bulk-sync models that use [`FixedSchema`](/rhom#fixed-sc
 
 **NOTE: In this scenario the sync callback should notify the user with a wait screen and start the bulk sync process.**
 
-### Server create-error processing on client
-"create-error" has to be handled in sync callback. Otherwise sync will stop on this model. To fix create errors you should call Model.on_sync_create_error or SyncEngine.on_sync_create_error:
+### Server error processing on client
+#### create-error
+has to be handled in sync callback. Otherwise sync will stop on this model. To fix create errors you should call Model.on_sync_create_error or SyncEngine.on_sync_create_error:
 
 	:::ruby
 	SyncEngine.on_sync_create_error( src_name, objects, action )
 	Model.on_sync_create_error( objects, action )
 
-* objects - One or more error objects
-* action - May be :delete or :recreate. :delete just remove object from client, :recreate will push this object to server again at next sync.
+    * objects - One or more error objects
+    * action - May be :delete or :recreate. :delete just remove object from client, :recreate will push this object to server again at next sync.
+
+#### update-error
+
+	:::ruby
+	SyncEngine.on_sync_update_error( src_name, objects, action )
+	Model.on_sync_update_error( objects, action )
+    
+    * objects - One or more error objects
+    * action - May be :retry - will push update object operation to server again at next sync.
+
+#### delete-error
+
+	:::ruby
+	SyncEngine.on_sync_delete_error( src_name, objects, action )
+	Model.on_sync_delete_error( objects, action )
+    
+    * objects - One or more error objects
+    * action - May be :retry - will push delete object operation to server again at next sync.
 
 For example:
 	:::ruby
     SyncEngine.on_sync_create_error( @params['source_name'], 
-        @params['server_errors']['create-error'].keys(), :delete)
-    
+        @params['server_errors']['create-error'], :delete)
+
+    SyncEngine.on_sync_update_error( @params['source_name'], 
+        @params['server_errors']['update-error'], :retry)
+        
+    SyncEngine.on_sync_delete_error( @params['source_name'], 
+        @params['server_errors']['delete-error'], :retry)
+   
 ### Notification Example
 Here is a simple example of a sync notification method that uses some of the parameters described above:
 
@@ -205,7 +230,7 @@ Here is a simple example of a sync notification method that uses some of the par
         if @params['server_errors'] && 
            @params['server_errors']['create-error']
             SyncEngine.on_sync_create_error( @params['source_name'], 
-                @params['server_errors']['create-error'].keys(), :delete)
+                @params['server_errors']['create-error'], :delete)
         end
 	  
 	    err_code = @params['error_code'].to_i
@@ -283,8 +308,6 @@ Next, in your controller action that displays the object(s), add the object noti
 	  end
 	end
 
-**NOTE: If you use `url_for` in your .erb files, then when you select a specific object(s) to view, those objects are added to the object notify map automatically.**
-
 #### Object Notification Parameters
 The object notification callback receives three arrays of hashes: "deleted", "updated" and "created".  Each hash contains values for the keys "object" and "source_id" so you can display which records were changed.
 
@@ -419,11 +442,12 @@ Start the `SyncEngine` process and display an optional status popup (defaults to
 	SyncEngine.dosync(false)
 	  #=> no status popups are displayed
 
-### `dosync_source(source_id, show_sync_status = true)`
-Star the `SyncEngine` process for a given source_id and display an optional status popup (defaults to true).
+### `dosync_source(source_id_or_name, show_sync_status = true)`
+Star the `SyncEngine` process for a given source id or source name and display an optional status popup (defaults to true).
 
 	:::ruby
-	SyncEngine.dosync_source(Product.get_source_id, true)
+	SyncEngine.dosync_source(Product.get_source_id.to_i, false) #sync by source id
+    SyncEngine.dosync_source(Product.get_source_name, false) #sync by source name	
 
 ### `lock_sync_mutex`
 Blocking call to wait for `SyncEngine` lock (useful for performing batch operations).
@@ -460,11 +484,29 @@ Clears the sync notification for a given source id.
 
 	:::ruby
     SyncEngine.on_sync_create_error( @params['source_name'], 
-        @params['server_errors']['create-error'].keys(), :delete)
+        @params['server_errors']['create-error'], :delete)
     
 * objects - One or more error objects
 * action - May be :delete or :recreate. :delete just remove object from client, :recreate will push this object to server again at next sync.
 
+### `on_sync_update_error( src_name, objects, action )`
+
+	:::ruby
+    SyncEngine.on_sync_update_error( @params['source_name'], 
+        @params['server_errors']['update-error'], :retry)
+    
+* objects - One or more error objects
+* action - May be :retry - will push update object operation to server again at next sync.
+
+### `on_sync_delete_error( src_name, objects, action )`
+
+	:::ruby
+    SyncEngine.on_sync_delete_error( @params['source_name'], 
+        @params['server_errors']['delete-error'], :retry)
+    
+* objects - One or more error objects
+* action - May be :retry - will push delete object operation to server again at next sync.
+
 ### `set_pollinterval(interval)`
 Update the `SyncEngine` poll interval. Setting this to 0 will disable polling-based sync.  However, you may still use [push-based-sync](/rhosync/push).
 

data/doc/ui.txt

@@ -102,6 +102,11 @@ By default, Rhodes framework uses a modified version of jQTouch version 1, beta
 * Conversely, Ajax requests inspect for a 'Wait-Page' response header. This informs jQTouch that the page it received was returned after an asynchronous HTTP request was spawned by the controller. Wait pages are not added to the jQtouch history. The animation is then deferred until the expected page is returned to the user interface via the Rho.insertAsyncPage() call. This method is typically invoked after an async HTTP callback function has been triggered in the controller.
 * You can override the slide animated transition for forms by setting an animation class on the form like '\<form class="pop"\>...\</form\>'.
 
+### Submit form
+If you need to submit form programmatically, please use the expression **jQT.submitForm('.current form.yourFormClass');**. Here **jQT** is defined as it shown above.  To specify the exact form on the page it is recommended to use **class** instead of **id**.
+
+Be careful, using expressions like **$('#form_id').submit();** with jQTouch it lead to an incorrect result!
+
 ## Loading screen
 
 Rhodes supports the display of a custom "Loading" screen while your application is launching. This screen's source is the file loading.html, located at <application-root>/app/loading.html.
@@ -573,9 +578,19 @@ Means the same as above and setup background color for tabbar.
 	:::ruby
 	Rho::NativeTabbar.create( :tabs => tabs, 
 		:background_color => 0x0000FF)
+
+Means the same as above and place TabBar in bottom of screen (actual only on Android, where TabBar placed in top of screen by default).	
+	:::ruby
+	Rho::NativeTabbar.create( :tabs => tabs, 
+		:background_color => 0x0000FF, :place_tabs_bottom => true)
 	
 **NOTE: If you setup :background_color on Android you should also setup :selected_color for each tab **	 
 
+Create TabBar and set callback for change tab event. In callback see @params['tab_index'] for string value with new tab index.
+	:::ruby
+	Rho::NativeTabbar.create(:tabs => tabs, :on_change_tab_callback => url_for(:action => :tabbar_on_tab_change_callback))
+
+
 Remove current tabbar. Does nothing if there is no active bar	
 	:::ruby
 	Rho::NativeTabbar.remove
@@ -584,6 +599,11 @@ Switch active tab to second (numeration is zero based i.e. 0 means first tab, 1
 	:::ruby
 	Rho::NativeTabbar.switch_tab(1) 
 
+Get current tab index
+	:::ruby
+	Rho::NativeTabbar.get_current_tab 
+
+
 Rho::NativeTabbar.create() create native tab bar UI element and activate its first tab. If you want to see another tab, call Rho::NativeTabbar.switch_tab explicitly just after NativeBar.create:
 
 	:::ruby
@@ -629,6 +649,7 @@ The Date/Time picker API allows the user to choose date or time:
 * DateTimePicker.choose(callback, title, initial_time, fmt)
 * DateTimePicker.choose(callback, title, initial_time, fmt, opaque)
 * DateTimePicker.choose_with_range(callback, title, initial_time, fmt, user_data, mindatetime, maxdatetime)
+* DateTimePicker.set_change_value_callback(callback)   - set callback for listen "on change" event. If you want set this callback, you should do it before each call of "choose" methods.
 
 The "fmt" parameter can have the following values (any other value throws an exception):
 
@@ -640,7 +661,7 @@ The "user_data" parameter is an optional string. It is non-interpreted and will
 
 Once user chooses a date/time and presses OK or Cancel, the callback URL you specified will be called. The callback is a POST message; the body of the message contains 'status', 'result' and, 'user_data' if provided.
 
-* 'status' can be 'ok' or 'cancel'
+* 'status' can be 'ok' or 'cancel' or 'change' (for change value callback only)
 * 'result' is a string representation of the selected date, as the number of seconds since Epoch. Ruby time can be created from it using the Time::at method.
 * There is no 'result' if status is 'cancel'
 * 'user_data' - if it exists, 'user_data' will be the same string that was passed into the choose method.
@@ -668,7 +689,7 @@ Animated transitions are supported on the iPhone and Android. Rhodes uses a cust
 			type="text/javascript"></script>
         <link href="/public/jqtouch/jqtouch.css" 
 			type="text/css" rel="stylesheet"/>
-        <script>$.jQTouch();</script>
+        <script>jQT = $.jQTouch();</script>
     <% end %>
 
 Also make sure to add jqtouch_mode=1 to your application's [rhoconfig.txt](configuration#run-time-configuration). Setting this property enables animation for the back button in the bottom toolbar and hides the forward button.

data/installer/instant-rhodes.nsi

@@ -93,14 +93,14 @@ section "uninstall"
     Push "PATH" 
     Push "R" 
     Push "HKLM" 
-    Push "$INSTDIR\redis-1.2.6-windows"
+    Push "$INSTDIR\redis-2.2.2"
     Call un.EnvVarUpdate
     Pop $R0
 
     Push "REDIS_HOME" 
     Push "R" 
     Push "HKLM" 
-    Push "$INSTDIR\redis-1.2.6-windows"
+    Push "$INSTDIR\redis-2.2.2"
     Call un.EnvVarUpdate
     Pop $R0
 
@@ -157,21 +157,21 @@ Section "Redis" redisSection
  
   SetOutPath $INSTDIR
  
-  File /r "redis-1.2.6-windows"
+  File /r "redis-2.2.2"
  
   ;add to path here
 
   Push "PATH" 
   Push "P" 
   Push "HKLM" 
-  Push "$INSTDIR\redis-1.2.6-windows"
+  Push "$INSTDIR\redis-2.2.2"
   Call EnvVarUpdate
   Pop $R0
 
   Push "REDIS_HOME" 
   Push "P" 
   Push "HKLM" 
-  Push "$INSTDIR\redis-1.2.6-windows"
+  Push "$INSTDIR\redis-2.2.2"
   Call EnvVarUpdate
   Pop $R0
 
@@ -211,7 +211,7 @@ SectionEnd
  
   ;Language strings
   LangString DESC_InstallRuby ${LANG_ENGLISH} "This installs ruby 1.8.7, rubygems 1.3.7, Rhodes and RhoSync gems."
-  LangString DESC_InstallRedis ${LANG_ENGLISH} "This installs redis 1.2.6 (required to run RhoSync)."
+  LangString DESC_InstallRedis ${LANG_ENGLISH} "This installs redis 2.2.2 (required to run RhoSync)."
   LangString DESC_InstallGit ${LANG_ENGLISH} "This installs Git (which includes the Git Bash)."
   LangString DESC_InstallGnuMake ${LANG_ENGLISH} "This installs GNU Make (sometimes required to update gems)."