rhodes 3.4.2 → 3.5.1.12

data/doc/configuration.txt

@@ -1,6 +1,6 @@
 # Application Configuration
 
-## Build time configuration 
+## Build time configuration
 
 ### Application Permissions and Capabilities
 
@@ -30,16 +30,17 @@ List of supported capabilities:
 * record_audio: allow recording audio ('audio' implies it)
 * vibrate: allow to use hardware vibration mechanism
 * bluetooth: allow to use bluetooth hardware
+* sdcard: allow writing to SD card on Android devices
 
 ### RhoGallery Security Token
 
-To restrict access to the application it could be built with a security token. Specify security token in the build.yml and build application. Application built with security token can be started in normal mode only if you provide this token as a parameter.  
+To restrict access to the application it could be built with a security token. Specify security token in the build.yml and build application. Application built with security token can be started in normal mode only if you provide this token as a parameter.
 If you do not specify correct security token in start params, application will close on start by default. If you want do something instead of exit (for example show special message or run application in limited mode etc.) you can define another start_path for your application in "rhoconfig.txt":
 
 	invalid_security_token_start_path = '/app/InvalidSecurityTokenStartPage'
 
 Specify security token in build.yml:
-	
+
 	security_token: 123
 
 Run application with special parameter:
@@ -57,7 +58,7 @@ To enable JavaScript and/or CSS code obfuscation at `public` folder of Rhodes ap
 
 If JavaScript or CSS code obfuscation is not required, then just omit `js` or `css` line accordingly.
 
-NOTE: The `jqmobile`, `jqtouch`, and `jquery` folders <b>must</b> be excluded when obfuscation is enabled, because the obfuscated versions of these libraries are there already.
+**NOTE: The `jqmobile`, `jqtouch`, and `jquery` folders <b>must</b> be excluded when obfuscation is enabled, because the obfuscated versions of these libraries are there already.
 
 ## Run time configuration
 Each Rhodes application contains a configuration file called "rhoconfig.txt".  A typical rhoconfig.txt will look like the following when an app is generated:
@@ -66,6 +67,8 @@ Startup page for your application
 
 	start_path = '/app'
 
+NOTE: If you set your start path to a location not ending in .erb, then the ruby code in application.rb will not execute (ex. if you are trying to change the default menu, etc)	
+
 Path to the options page (in this case handled by javascript)
 
 	options_path = '/app/Settings'
@@ -74,31 +77,31 @@ Location of bundle url (i.e. from rhohub.com); used by desktop win32 simulator
 
 	rhobundle_zip_url = ''
 
-Optional password to access bundle (usually not required); used by desktop win32 simulator 
+Optional password to access bundle (usually not required); used by desktop win32 simulator
 
 	rhobundle_zip_pwd = nil
 
 Log level: 0-trace, 1-info(app level), 3-warnings, 4-errors. It is recommended for production set it to 3 to minimize log and increase speed lost due to log output
 
-	MinSeverity  = 1 
+	MinSeverity  = 1
 
 Enable copy log messages to standard output, useful for debugging
 
 	LogToOutput = 1
 
-Log categories: '*' means all categories, otherwise list them : Cat1, Cat2 
+Log categories: '*' means all categories, otherwise list them : Cat1, Cat2
 
 	LogCategories = *
 
 What log categories to exclude
 
-	ExcludeLogCategories = 
+	ExcludeLogCategories =
 
 Max log file size in Bytes, set 0 to unlimited size; when limit is reached, log wraps to beginning of file
 
 	MaxLogFileSize=50000
 
-Custom log file path
+Custom log file path. On Android devices "sdcard" capability must be enabled to allow writing to SD card.
 
 	LogFilePath = '/mnt/sdcard/myapp.log'
 
@@ -114,17 +117,17 @@ Skip http package body from log(for security reasons), off by default
 
 	log_skip_post = 1
 
-Define exclude parameters log filter(for security reasons) - parameter names separated by comma, empty by default. 
+Define exclude parameters log filter(for security reasons) - parameter names separated by comma, empty by default.
 
 	log_exclude_filter = 'login, password'
 
 Timeout of network requests in seconds (30 by default)
-	
+
 	net_timeout = 60
 
-Log server address where log will be posted by using RhoConf.send_log or from the log view. Log server source code is open and available at http://github.com/rhomobile/rhologs, so you can deploy your own logserver
+Log server address where log will be posted by using RhoConf.send_log or from the log view. Log server source code is open and available at <http://github.com/rhomobile/rhologs>, so you can deploy your own logserver
 
-	logserver = 'http://rhologs.heroku.com' 
+	logserver = 'http://rhologs.heroku.com'
 
 Log file prefix - contain human-readable text
 
@@ -135,26 +138,31 @@ Sync server url, typically this will look like 'http://<hostname>:<port>/applica
 	syncserver = 'http://localhost:9292/application'
 
 Set this option to 1 in order to open Rhodes app in full screen mode. Default is 1 for Android up to Rhodes 2.2.5. On all other platforms and on Android from Rhodes > 2.2.5 default is 0
-	
+
 	full_screen = 1
 
-Set this option to 1 in order to enable WebView zoom (Android only). Defauld is 0
+Set this option to 1 in order to enable WebView zoom (Android only). Default is 0
 
 	enable_screen_zoom = 1
 
+Set application window width and hieght (Win32 only). Default is 400 x 600.
+
+	screen_width = 800
+	screen_height = 600
+
 Port of the local (embedded) HTTP server. This parameter is mainly for debug purposes. If not specified, application will use dynamically selected one.
 **NOTE WARNING!!! Remove this parameter before put application to production. **
-	
+
 	local_server_port = 8080
 
 Show status bar on windows mobile. Default is 1 (show)
-	
+
 	wm_show_statusbar = 1
 
 **NOTE: This parameter works only with Internet Explorer Browser. When you use Motorola WebKit browser, statusbar is not available **
 
 Disable screen rotation. By default set to 0 (enabled). This option available on ANDROID and iPhone ONLY
-	
+
 	disable_screen_rotation = 1
 
 Disable closing app when pressing back on home screen on blackberry
@@ -166,17 +174,17 @@ Load images in background, this improve reaction speed on user actions, 0 by def
 	bb_loadimages_async = 0
 
 Set to 0 to reset the bulksync_state and trigger a bulk sync the next time rhodes synchronizes
-	
+
 	bulksync_state = 1
 
 Hides forward button and animates back button transition
-	
+
 	jqtouch_mode=1
 
 Splash screen image display options. See more details [here](ui#loading-screen).
 
 	splash_screen='zoom'
-	
+
 Turn on Full Browser mode for Blackberry 4.6.0 and higher
 
 	use_bb_full_browser = 1
@@ -189,12 +197,20 @@ To use only models from bulk database. If true, application will not create mode
 
 	use_bulk_model = true
 
-Disable WebView to check SSL sertificate (Android). Used to allow proced with self signed sertificates. Use at your own risk. This configuration option works well for any Android version except 2.3.3/2.3.4 (due to Android WebView behavior).
+Disable WebView to check SSL certificate (Android). Used to allow proceed with self signed certificates. Use at your own risk. This configuration option works well for any Android version except 2.3.3/2.3.4 (due to Android WebView behavior).
 
 	no_ssl_verify_peer = 1
 
+Allows finish sync if sync is active at the time when application is put to background. This parameter will take effect only on iOS devices.
+
+	finish_sync_in_background = 1
+
+Enable web plugins (Flash etc.) on Android devices.
+
+	enable_web_plugins = 1
+
 ### Last Visited Page
-To save/restore last visited page use WebView.current_location in on_ui_created/on_ui_destroyed of [AppAplication class](application#appapplication-class).
+To save/restore last visited page use WebView.current_location in on_ui_created/on_ui_destroyed of [AppApplication 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.
@@ -215,12 +231,12 @@ For example:
 
 To get start_path:
 	:::ruby
-	Rho::RhoConfig.start_path 
+	Rho::RhoConfig.start_path
 	#=> will return current value of start_path
-	
-To set start_path	
+
+To set start_path
 	:::ruby
-	Rho::RhoConfig.start_path = '/app/MyObject' 
+	Rho::RhoConfig.start_path = '/app/MyObject'
 	#=> start_path will be saved to rhoconfig.txt as '/app/MyObject'
 
 You may store any arbitrary options in the rhoconfig.txt file using the Ruby API. Keep in mind that they will may be lost the next time the user installs a new version of the application.
@@ -233,7 +249,7 @@ In the previous section, there is a "syncserver" option available.  This option
 	:::ruby
 	SyncEngine.set_syncserver(
 		'http://examplesyncserver.com/apps/MyApp/sources/')
-		
+
 Calling the function above will do the following:
 
 * Update the in-memory syncserver for the SyncEngine (all subsequent synchronization will use the new syncserver)
@@ -244,18 +260,18 @@ To enable auto sync you can call (enabled by default with 5 minutes interval )
 
 	:::ruby
 	SyncEngine.set_pollinterval(timeout_in_seconds)
-	
+
 OR set in rhoconfig.txt:
 
 	sync_poll_interval=timeout_in_seconds
 
-To disable auto sync you can call 
+To disable auto sync you can call
 
 	:::ruby
 	SyncEngine.set_pollinterval(0)
 
 OR set in rhoconfig.txt:
-	
+
 	sync_poll_interval=0
 
 ### Logging
@@ -268,12 +284,12 @@ To send the log to the log server url, defined in rhoconfig.txt:
 
 	:::ruby
 	Rho::RhoConfig.send_log = "http://example.com/client_log?client_id=123&device_pin=345&log_name=mylog"
-	
+
 Url format: \<logserver\>/client_log?client_id=\<client_id\>&device_pin=\<device_pin\>&log_name=\<logname\>
 
 ### Persistent Storage (Blackberry only)
 To enable use of the RIM persistent storage API in rhodes, just add following line to your rhoconfig.txt:
 
 	use_persistent_storage = 1
-	
+
 It will enable RIM's persistent storage API (instead of files) to store the DB version, the DB journal and the database itself. The main goal of persistent storage is that all objects stored by an application will be automatically removed when the application is uninstalled.

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

@@ -3,7 +3,7 @@ Connecting Directly to Web Services with Rhodes
 Rhodes provides another utility for connecting to backend services besides the [`SyncEngine`](/rhodes/synchronization) called `AsyncHttp`.  Your application can use the `AsyncHttp` library to interact with web services, pull remote images, etc.
 
 ## AsyncHttp API
-Below is the list of available `AsyncHttp` methods you can use to asyncrhonously make calls to http(s) services:
+Below is the list of available `AsyncHttp` methods you can use to asynchronously make calls to http(s) services:
 
 ### Common Parameters
 * `:url` - URL of the request.
@@ -15,13 +15,13 @@ Below is the list of available `AsyncHttp` methods you can use to asyncrhonously
         #values will be decoded automatically in callback
 
 * `:authentication` - (optional) Send Basic Auth header with request.  This takes the form:
-		
+
 		:authentication => {
-		  :type => :basic, 
-		  :username => "john", 
+		  :type => :basic,
+		  :username => "john",
 		  :password => "secret"
-		} 
-		
+		}
+
 * `:ssl_verify_peer` - (optional) Verify SSL certificates, `true` by default.
 
 ### `get(:url, :headers, :callback, :callback_param)`
@@ -42,8 +42,8 @@ Example using Basic Auth:
 	  :headers => {"Cookie" => cookie},
 	  :callback => (url_for :action => :httpget_callback),
 	  :authentication => {
-	    :type => :basic, 
-		:username => "john", 
+	    :type => :basic,
+		:username => "john",
 		:password => "secret"
       }
 	)
@@ -71,15 +71,15 @@ Perform HTTP POST request to the specified <code>:url</code>.  As with get, you
 	  :headers => {"Cookie" => cookie},
 	  :body => "username=john&password=secret",
 	  :callback => url_for(:action => :httppost_callback),
-	  :callback_param => "post=complete" 
+	  :callback_param => "post=complete"
 	)
-	
+
 ### `download_file(:url, :headers, :filename, :callback, :callback_param)`
 Download a file to the specified filename.<a id="asynchttp-download_file-ex" />
 
 	:::ruby
 	file_name = File.join(Rho::RhoApplication::get_base_app_path, "test.jpg")
-	
+
 	# :filename		Full path to download file target.
 	Rho::AsyncHttp.download_file(
 	  :url => "http://www.google.com/images/logos/ps_logo2.png",
@@ -87,15 +87,15 @@ Download a file to the specified filename.<a id="asynchttp-download_file-ex" />
 	  :headers => {},
 	  :callback => url_for(:action => :httpdownload_callback),
 	)
-	
+
 ### `upload_file(:url, :headers, :filename, :body, :callback, :callback_param)`
 Upload the specified file using HTTP POST:<a id="asynchttp-upload_file-ex" />
 
-	:::ruby	
+	:::ruby
   	file_name = File.join(Rho::RhoApplication::get_base_app_path, "myfile.txt")
 
 	# :filename		Full path to download file target.
-	# :post			HTTP POST body to send with request.		
+	# :post			HTTP POST body to send with request.
     Rho::AsyncHttp.upload_file(
       :url => "http://example.com/receive_file",
       :filename => file_name,
@@ -108,21 +108,21 @@ You can also send multiple files in a single `upload_file` request:
 
 	:::ruby
 	# :multipart				 Array of hashes containing
-	#							 file information. 
+	#							 file information.
 	#
 	# :multipart[:filename]		 Name of file to be uploaded.
 	#
 	# :multipart[:filename_base] (optional) Base directory containing
 	#							 the :filename.
-	# :multipart[:name]			 (optional) File type, defaults 
+	# :multipart[:name]			 (optional) File type, defaults
 	#							 to "blob".
 	#
-	# :multipart[:content_type]	 (optional) Content-Type header, 
+	# :multipart[:content_type]	 (optional) Content-Type header,
 	#							 defaults to "application/octet-stream".
    	Rho::AsyncHttp.upload_file(
       :url => "some_url",
       :multipart => [
-        { 
+        {
           :filename => file_name,
 		  # if missed base name from file path used
           :filename_base => "files_to_upload",
@@ -138,14 +138,14 @@ You can also send multiple files in a single `upload_file` request:
       ]
     )
 
-### `cancel(cancel_callback = "*")` 
+### `cancel(cancel_callback = "*")`
 Cancel the current `AsyncHttp` call.  Defaults to "*", which cancels all requests.
 
 	:::ruby
 	AsyncHttp.cancel
 
 ## AsyncHttp Callback
-As you noticed with each of the code samples above, we specified a `:callback` action.  This will execute with the `AsyncHttp` request is completed.  
+As you noticed with each of the code samples above, we specified a `:callback` action.  This will execute with the `AsyncHttp` request is completed.
 
 ### Callback Parameters
 The following parameters are available in an `AsyncHttp` callback:
@@ -162,15 +162,15 @@ The following parameters are available in an `AsyncHttp` callback:
 * `@params["http_error"]` - HTTP error code if response code was not 200.
 
 ## AsyncHttp and Animated Transitions
- 
-Adding an animated transition to an `AsyncHttp` request requires some small setup and is useful for displaying a smoother user experience. 
+
+Adding an animated transition to an `AsyncHttp` request requires some small setup and is useful for displaying a smoother user experience.
 
 To enable an animated transition, the controller action must set a `"Wait-Page"` response header after making the `AsyncHttp` call. The response header tells the user interface that an `AsyncHttp` request has been spawned and that the rendered view should be treated as a transient page, it will not be added to the navigation history.
 
 	:::ruby
 	def async_show
 	  Rho::AsyncHttp.get(
-	    :url => "http://rhostore.heroku.com/products/#{@params["product_id"]}.json",
+	    :url => "http://rhostore.herokuapp.com/products/#{@params["product_id"]}.json",
 	    :callback => url_for(:action => :show_callback),
 	  )
 
@@ -209,7 +209,7 @@ Also, you can disable caching on exact page transition with `data-dom-cache` att
 
 ### Note About Animated Transitions
 
-If you deploy to platforms that don"t handle animated transitions (like Windows Mobile and BlackBerry), the controller will need to handle both cases. In your `AsyncHttp` request, you"ll need to set the `callback_param` with the `@request` variable. 
+If you deploy to platforms that don"t handle animated transitions (like Windows Mobile and BlackBerry), the controller will need to handle both cases. In your `AsyncHttp` request, you"ll need to set the `callback_param` with the `@request` variable.
 
 There's a helper function called `caller_request_hash_to_query` defined in `ApplicationHelper` that you can invoke. The returned value is a string that looks like "_request=<json_request>", where `<json_request>` is the URL-encoded JSON representation of the `@request` value. This parameter is used to give the callback function some context of whether the user interface made the request with or without transition enabled.
 
@@ -217,7 +217,7 @@ There's a helper function called `caller_request_hash_to_query` defined in `Appl
 	include ApplicationHelper
 	def async_show
 	  Rho::AsyncHttp.get(
-	    :url =>  "http://rhostore.heroku.com/products/#{@params["product_id"]}.json",
+	    :url =>  "http://rhostore.herokuapp.com/products/#{@params["product_id"]}.json",
 	    :callback => url_for(:action => :show_callback),
 	    :callback_param => caller_request_hash_to_query
 	  )
@@ -249,19 +249,19 @@ In your callback function, the first thing you need to do is invoke `caller_requ
 
 ## AsyncHttp Example
 Here is a controller in the [Rexml sample from the System API Samples](http://github.com/rhomobile/system-api-samples).  It makes a `AsyncHttp.get` call to a test web service.  Then it parses the web service response with rexml and displays the result.
-	
+
 	:::ruby
 	def webservicetest
 	  Rho::AsyncHttp.get(
-	    :url => "http://rhostore.heroku.com/products.xml",
+	    :url => "http://rhostore.herokuapp.com/products.xml",
 	    :callback => url_for(:action => :httpget_callback),
 	  )
-   
+
 	  render :action => :wait
 	end
 
 	def get_res
-	  @@get_result    
+	  @@get_result
 	end
 
 	def get_error
@@ -271,20 +271,20 @@ Here is a controller in the [Rexml sample from the System API Samples](http://gi
 	def httpget_callback
 	  if @params["status"] != "ok"
 	    @@error_params = @params
-	    WebView.navigate( url_for(:action => :show_error) )        
+	    WebView.navigate( url_for(:action => :show_error) )
 	  else
 	    @@get_result = @params["body"]
 
 	    begin
 	      require "rexml/document"
-     
+
 	      doc = REXML::Document.new(@@get_result)
 	      puts "doc : #{doc}"
 	    rescue Exception => e
 	      puts "Error: #{e}"
 	      @@get_result = "Error: #{e}"
 	    end
-         
+
 	    WebView.navigate( url_for(:action => :show_result) )
 	  end
 	end

data/doc/contributing.txt

@@ -39,7 +39,7 @@ If you are interested us using your patch to Rhodes you will need to submit a  [
 Rhodes includes automated tests that can (and should) be run periodically against the codebase if you're modifying the Rhodes framework itself.
 
 ### Install Rhodes
-The automated tests are a part of the Rhodes project on GitHub. To obtain the Rhodes source code and access the automated tests, follow the instructions in the [Setup Rhodes Source Code](http://rhodocs.rhohub.com/rhodes/build#setup-rhodes-source-code) section. You will find two automated test sets under rhodes/spec/. One is called phone_spec, the other is framework_spec.
+The automated tests are a part of the Rhodes project on GitHub. To obtain the Rhodes source code and access the automated tests, follow the instructions in the [Setup Rhodes Source Code](build#setting-up-rhodes-source-code) section. You will find two automated test sets under rhodes/spec/. One is called phone_spec, the other is framework_spec.
 
 ### Running Tests
 Assuming you have already downloaded the necessary SDKs (instructions can be found [here](http://rhodocs.rhohub.com/rhodes/build)), all you need to do is execute the appropriate rake task. To execute the phone_spec, for example, you can do the following in Terminal: