rhodes 2.2.6 → 2.3.0.beta.1

data/doc/configuration.txt

@@ -0,0 +1,236 @@
+# Application Configuration
+
+## Build time configuration 
+
+### Application Permissions and Capabilities
+
+To enable specific device capabilities, edit application's build.yml as below:
+
+	:::yaml
+	capabilities:
+	  - camera
+	  - gps
+	android:
+	  capabilities:
+	    - network_state
+
+Rhodes support common plus platform-specific capabilities. They are merged into a single list at build time.
+
+** NOTE: Right now only Android recognizes these configuration options. However, we are planning to enable these options across all platforms. **
+
+List of supported capabilities:
+
+* audio: allow using of audio hardware (record audio, modify audio settings)
+* camera: allow use of hardware camera
+* gps: allow use of geo location service
+* network_state: allow read device network state (connected/disconnected)
+* phone: allow make calls/read phone state
+* pim: allow read/modify personal information and contacts
+* push: allow to use PUSH on device
+* record_audio: allow recording audio ('audio' implies it)
+* vibrate: allow to use hardware vibration mechanism
+* bluetooth: allow to use bluetooth hardware
+
+
+## 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:
+
+Startup page for your application
+
+	start_path = '/app'
+
+Path to the options page (in this case handled by javascript)
+
+	options_path = '/app/Settings'
+
+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 
+
+	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 
+
+Enable copy log messages to standard output, useful for debugging
+
+	LogToOutput = 1
+
+Log categories: '*' means all categories, otherwise list them : Cat1, Cat2 
+
+	LogCategories = *
+
+What log categories to exclude
+
+	ExcludeLogCategories = 
+
+Max log file size in KB, set 0 to unlimited size; when limit is reached, log wraps to beginning of file
+
+	MaxLogFileSize=50
+
+Turn on local http server traces, off by default
+
+	net_trace = 0
+
+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
+
+	logserver = 'http://rhologs.heroku.com' 
+
+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'
+
+Geo location inactivity timeout (in seconds)
+	
+	geo_location_inactivity_timeout = 30
+
+Set this option to 1 in order to open Rhodes app in full screen mode. Default 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
+
+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
+
+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
+
+	bb_disable_closebyback = 0
+
+Load images in background, this improve reaction speed on user actions, 0 by default
+
+	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
+
+Turn on Persistent Storage usage mode for Blackberry
+
+	use_persistent_storage = 1
+	
+
+### 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.
+
+### 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.
+When a Rhodes app starts, it compares the current db version with app_db_version cleans the db if they do not match.
+
+### Ruby API
+
+Each of the configuration options shown above are available through the RhoConfig Ruby API. To access configuration properties from application code use Rho::RhoConfig class:
+
+	:::ruby
+	Rho::RhoConfig.full_screen
+	Rho::RhoConfig.app_property='some value'
+	if Rho::RhoConfig.exists?('some_property')
+	  #do something
+	end
+
+For example:
+
+To get start_path:
+	:::ruby
+	Rho::RhoConfig.start_path 
+	#=> will return current value of start_path
+	
+To set start_path	
+	:::ruby
+	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.
+
+# TBD add link to update of rhoconfig.txt
+
+### SyncEngine Configuration
+In the previous section, there is a "syncserver" option available.  This option can be changed through the Rho::RhoConfig API as you would expect. However, since changing the syncserver option requires updating the SyncEngine at runtime, another Ruby call is available:
+
+	:::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)
+* Perform a logout to make sure the session for the old syncserver is removed
+* Write the new syncserver property to rhoconfig.txt
+
+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 
+
+	:::ruby
+	SyncEngine.set_pollinterval(0)
+
+OR set in rhoconfig.txt:
+	
+	sync_poll_interval=0
+
+### Logging
+To show the application log on the device with log and log-related menu items, like clear, send and log options:
+
+	:::ruby
+	Rho::RhoConfig.show_log
+
+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

@@ -0,0 +1,282 @@
+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:
+
+### Common Parameters
+* `: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.
+* `:authentication` - (optional) Send Basic Auth header with request.  This takes the form:
+		
+		:::ruby
+		:authentication => {
+		  :type => :basic, 
+		  :username => "john", 
+		  :password => "secret"
+		} 
+		
+* `: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`.
+
+	:::ruby
+	Rho::AsyncHttp.get(
+      :url => "http://www.example.com",
+      :headers => {"Cookie" => cookie},
+      :callback => (url_for :action => :httpget_callback)
+    )
+
+Example using Basic Auth:
+
+	:::ruby
+	Rho::AsyncHttp.get(
+	  :url => "http://www.example.com",
+	  :headers => {"Cookie" => cookie},
+	  :callback => (url_for :action => :httpget_callback),
+	  :authentication => {
+	    :type => :basic, 
+		:username => "john", 
+		:password => "secret"
+      }
+	)
+
+Example of synchronous call:
+
+	:::ruby
+	result = Rho::AsyncHttp.get(
+	  :url => "http://www.apache.org/licenses/LICENSE-2.0"
+	)
+    @get_result = res["body"]
+
+**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)`
+Perform HTTP POST request to the specified `:url`.  As with `get`, you can specify optional arguments:
+
+	:::ruby
+	# :post				HTTP POST body to send with request.
+	# :http_command 	(optional) Use different HTTP method
+	#					(i.e. "put").
+	Rho::AsyncHttp.post(
+	  :url => "https://www.example.com",
+	  :headers => {"Cookie" => cookie},
+	  :body => "username=john&password=secret",
+	  :callback => url_for(:action => :httppost_callback),
+	  :callback_param => "post=complete" 
+	)
+	
+### `download_file(:url, :headers, :filename, :callback, :callback_params)`
+Download a file to the specified filename.
+
+	:::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",
+	  :filename => file_name,
+	  :headers => {},
+	  :callback => url_for(:action => :httpdownload_callback),
+	)
+	
+### `upload_file(:url, :headers, :filename, :body, :callback, :callback_params)`
+Upload the specified file using HTTP POST:
+
+	:::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.		
+    Rho::AsyncHttp.upload_file(
+      :url => "http://example.com/receive_file",
+      :filename => file_name,
+      :body => "" #=> leave blank, AsyncHttp will fill in multipart body
+      :headers => {"Content-Type"=>"text/plain"}, #=> used as body text content type
+      :callback => url_for(:action => :httpupload_callback),
+      :callback_param => "" )
+
+You can also send multiple files in a single `upload_file` request:
+
+	:::ruby
+	# :multipart				 Array of hashes containing
+	#							 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 
+	#							 to "blob".
+	#
+	# :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",
+          :name => "image",
+          :content_type => "application/octet-stream"
+        },
+		# You can specify file content inline.
+        {
+          :body => "upload test",
+          :name => "upload_body_test",
+          :content_type => "plain/text"
+        }
+      ]
+    )
+
+### `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.  
+
+### Callback Parameters
+The following parameters are available in an `AsyncHttp` callback:
+
+* `@params["body"]` - The body of the HTTP response.
+
+**NOTE: In the case of a JSON response (Content-Type="application/json"), the `@params["body"] will be parsed automatically and contain a ruby data structure.  Otherwise, `@params["body"]` contains the raw response body.**
+
+**NOTE: In the case of an XML response (Content-Type="application/xml"), Rhodes can automatically parse the `@params["body"]` as well if you enable the ["rexml extension"](/rhodes/extensions#rhodes-extensions) in your application.**
+
+
+* `@params["headers"]` - A hash containing the response headers.
+* `@params["cookies"]` - A the server cookies parsed and usable for subsequent requests.
+* `@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. 
+
+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",
+	    :callback => url_for(:action => :show_callback),
+	  )
+
+	  @response["headers"]["Wait-Page"] = "true"
+	  render :action => :waiting
+	end
+
+This example renders a waiting screen while awaiting a response from the `AsyncHttp` request. The `:waiting` page is transient and will not be added to the navigation history, which means clicking back won't open the page.
+
+The `AsyncHttp` callback can render the response by calling `render_transition`. This function is defined in `ApplicationHelper` so make sure you `include` it in your controller.  The `render_transition` function works much like `render` except that it will animate a transition from the previous page.
+
+Below, a product model is created using the response from the web service and then calling `render_transition`, which leverages the show view template:
+
+	:::ruby
+	include ApplicationHelper
+
+	def show_callback
+	  if @params["status"] == "ok"
+	    @product = Product.new(@params["body"]["product"])
+	    @product.object = @product.id
+	    render_transition :action => :show
+	  else
+	    # In this example, an error just navigates back to the index w/o transition.
+	    WebView.navigate url_for :action => :index
+	  end
+	end
+
+### 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. 
+
+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.
+
+	:::ruby
+	include ApplicationHelper
+	def async_show
+	  Rho::AsyncHttp.get(
+	    :url =>  "http://rhostore.heroku.com/products/#{@params["product_id"]}.json",
+	    :callback => url_for(:action => :show_callback),
+	    :callback_param => caller_request_hash_to_query
+	  )
+
+	  @response["headers"]["Wait-Page"] = "true"
+	  render :action => :waiting
+	end
+
+In your callback function, the first thing you need to do is invoke `caller_request_query_to_hash` (also defined in `ApplicationHelper`) that deserializes the `@request` query parameter value passed in via `callback_param` shown in the example above. The function sets a `@caller_request` in the current context. You can then use it to determine if the user interface had transition enabled by inspecting the `"Transition-Enabled"` request header. For transitions, call `render_transition`, otherwise call `WebView.navigate`.
+
+	:::ruby
+	def show_callback
+	  caller_request_query_to_hash
+
+	  if @params["status"] == "ok"
+	    @product = Product.new(@params["body"]["product"])
+	    @product.object = @product.id
+	    if @caller_request["headers"]["Transition-Enabled"] == "true"
+	      render_transition :action => :show
+	    else
+	      WebView.navigate(
+		 	url_for(:action => :show, :id => @product.object)
+		  )
+	    end
+	  else
+	    WebView.navigate( url_for(:action => :index) )
+	  end
+	end
+
+## 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",
+	    :callback => url_for(:action => :httpget_callback),
+	  )
+   
+	  render :action => :wait
+	end
+
+	def get_res
+	  @@get_result    
+	end
+
+	def get_error
+	  @@error_params
+	end
+
+	def httpget_callback
+	  if @params["status"] != "ok"
+	    @@error_params = @params
+	    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
+
+	def show_result
+	  render :action => :webservicetest, :back => "/app/RexmlTest"
+	end

data/doc/contributing.txt

@@ -0,0 +1,64 @@
+Contributing
+===
+Want to add features to Rhodes?  Found a bug that you want report or fix?
+
+## Report Rhodes Issues
+Please report bugs/features/enhancements to the [google group](http://groups.google.com/group/rhomobile).
+
+## Run Rhodes Specs
+First run the rhodes specs to make sure your environment is up-to-date for development (currently the specs only run on OSX):
+
+1. [Fork](http://help.github.com/forking/) the [Rhodes repository](http://github.com/rhomobile/rhodes).
+2. Clone your new repo: 
+
+		$ git clone git://github.com/<yourhandle>/rhodes.git
+		$ cd rhodes
+		$ bin/rhodes-setup
+		$ rake run:allspecs #=> runs rhodes framework_spec and phone_spec targets
+
+
+If everything passes (pending specs are OK), then your environment is ready for development.  If you have trouble installing a particular gem or the specs just won't run properly, please feel free to ping the [google group](mailto:rhomobile@googlegroups.com rhomobile) or [hop on IRC](http://webchat.freenode.net/?channels=rhomobile) to chat with other Rhodes developers.
+
+## Contributing your Patch
+Now that you're environment is ready, make your changes!
+
+1. Create a topic branch:
+		$ git checkout -b cool_new_feature
+2. Write tests([example](http://github.com/rhomobile/rhodes/blob/a905e9c9781bfe6e5003e8c8a11cd5418b08df73/spec/framework_spec/app/spec/rhom_object_spec.rb#L239))
+3. Make changes...
+4. Add relevant documentation(RDoc, update the README if relevant)
+5. Push to your branch:
+		$ git push origin cool_new_feature
+6. Send a note to the [google group](http://groups.google.com/group/rhomobile)
+
+That's it!  We recommend following [these ruby style guidelines](http://github.com/chneukirchen/styleguide/blob/master/RUBY-STYLE) when coding.
+
+If you are interested us using your patch to Rhodes you will need to submit a  [contribution agreement](http://rhomobile.com/community/contributing/) to us.
+
+## Automated Tests
+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.
+
+### 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:
+
+    :::term
+    $ cd rhodes/spec/phone_spec
+    $ rake run:platform:spec
+
+Where platform is "android" to run it for Android, "iphone" for iPhone, "bb" for BlackBerry. As a shortcut, you can also execute any of the following supported tasks:
+
+    :::term
+    $ rake run:iphone:spec           # Runs spec tests for the current directory
+    $ rake run:iphone:phone_spec     # Runs spec tests for rhodes/spec/phone_spec
+    $ rake run:iphone:framework_spec # Runs spec tests for rhodes/spec/framework_spec
+
+    $ rake run:android:spec          # Runs spec tests for the current directory
+    $ rake run:android:phone_spec    # Runs spec tests for rhodes/spec/phone_spec
+
+    $ rake run:bb:spec               # Runs spec tests for the current directory
+    $ rake run:bb:phone_spec         # Runs spec tests for rhodes/spec/phone_spec
+
+Rhomobile performs continuous testing of the framework_spec on iPhone and the phone_spec on iPhone and BlackBerry via a customized branch of the CIJoe project. Support for the Android phone_spec is currently functional but under development.