Installation and Walkthrough
Installing the droiuby client is straightforward, simply upload the apk to device or you can get from google play through this url:
http://play.google.com/store/apps/details?id=com.droiuby.application
Launching the app will show you an almost empty screen with a url text field. Here you an enter the url of a droiuby enabled site that you want to visit.
Note: Droiuby is currently available only for android 4.0 and above devices.
Make sure you have ruby and rubygems installed. jruby is recommended but the gem will work with MRI for most of the tasks.
Install the droiuby gem
gem install droiuby
There are post-install steps. Refer to README.md (https://github.com/jedld/droiuby-doo)
When developing for droiuby it is recommended that you have the android emulator or an android tablet/handset (at least Ice Cream Sandwich) with you.
A capable web server and web application framework (e.g. Ruby on Rails)
The app descriptor xml tells droiuby about your app. This includes the base url and the main layout file that it will use as well as the name and image if you intend to publish your app. The app descriptor should be placed in a publicly accessible location, either in your public folder or you can dynamically generate the file from a template. The descriptor XML should look like this (config.xml):
<app_descriptor>
<name>hello_world</name>
<description>This is a hello world app</description>
<launcher_icon/>
<base_url>http://localhost:3000</base_url>
<main>main</main>
</app_descriptor>
Place your apps name and description inside the "name" and "description" tag. The optional launcher_icon should be an absolute path to a png or jpg image. The base_url should contain the root path to your app. Droiuby will use the base_url to resolve relative references in all parts of your application.
The "main" element describes the location of the initial layout xml file that droiuby will parse. In this case, since the base_url is http://localhost:3000, droiuby will load the file from http://localhost:3000/main.
The layout file is an xml file that describes the UI elements that the user will see on the screen similar to your HTML templates. Below is a sample "hello world" layout file.
<activity>
<preload id="android_log_drawable" type="image" src="http://upload.wikimedia.org/wikipedia/en/a/a5/Android-logo.jpg"/>
<t color="#50FF0D0D" class="exclamation text" >Hello World!!!</t>
<img src="@preload:android_log_drawable" width="100"/>
</activity>
This will render the android logo and print Hello World!!! on the screen. Assuming the Application descriptor XML can be accessed at public/config.xml, you can enter http://localhost:3000/public/config.xml** to load the app. After it finishes loading you should see the android logo with "hello world" text at the bottom.
See the layout template reference manual on what those tags mean. It may also be useful to look at the android documentation also, as all of this just run on top of the android framework.
Simply displaying an image and text is boring, so here we will add buttons and handle events when the user clicks on a button.
For handling events, Droiuby comes packaged with a jruby container for parsing your scripts, it also comes with a minimal set of libraries (e.g. droiuby view wrappers and activesupport).
Below the layout file is modified to contain a button and a reference to a ruby script. The ruby script is defined next.
main.xml
<activity controller="main.rb#main">
<preload id="android_log_drawable" type="image" src="http://upload.wikimedia.org/wikipedia/en/a/a5/Android-logo.jpg"/>
<t color="#50FF0D0D" class="exclamation text" >Hello World!!!</t>
<img src="@preload:android_log_drawable" width="100"/>
<button id='test_button' width="match">test</button>
</activity>
Here we see the use of the controller attribute. The attribute follows the following syntax:
url#class name
e.g.
main.rb#main
Because of the base URL, droiuby will look for main.rb here http://localhost:3000/main.rb. Next the class name passed will be used to instantiate the controller for this activity.
main.rb
class Main < Activity
def on_create
V('#test_button').on(:click) do |v|
toast 'hello world'
end
end
end
The on_create method is the first method called after the View have been created and attached (but not rendered). Note that on_create runs inside android's UI thread and long running operations should be avoided.
For droiuby ruby scripts, the embedded jruby interpreter has a minimal set of libraries available to it (to minimize the preparsing time required during startup).
For events handling, droiuby uses a jquery and ruby inspired mechanism of using blocks that will be called later when the event actually happens. V serves as the universal selector mechanism for droiuby.
The droiuby console can be launched by pointing your browser to your android device or emulator at port 4000. If you are using the emulator you would also need to configure it (See Notes on testing with the android emulator)
The droiuby console allows for full introspection and you can issue any code that you would normally use inside your ruby scripts including using V and adding event handlers.
To view a summary of your layout's structure, you can issue:
V().p_tree
Rails activesupport is bundled with the client which provides the various string and date enhancements that rails developers have come to expect.
You can customize droiuby to include your own set of libraries as well... simply place your libraries as a zip file under assets/lib/vendor, droiuby will automatically extract files under that folder during initial startup to android's temp directory (You can then require those files inside your ruby scripts). You can see activesupport.zip and json.zip as two examples of this mechanism.