LocoRuby is a project mainly written in JAVASCRIPT and RUBY, it's free.
Simple way to execute ruby code on a local windows browser
LocoRuby is a simple way to evaluate local ruby code and include <script type="text/ruby">...</script> blocks on a web
page.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Bytes Free</title>
<script type='text/javascript' src='javascripts/loco_ruby.js'></script>
</head>
<body>
<input type="button" value="Bytes Free?"
onclick="LocoRuby.eval('/([0-9]*) bytes free/.match(`dir /-C`)[1]', function(r){ alert(r + ' bytes free.')})"/>
</body>
</html>Lets say your ruby project (rails, sinatra whatever) mainly runs as a browser application, but also needs to run a little
script on a windows box.
For example to control a legacy application that has no API, or to do some file management in the local environment.
Yes you can write a ruby script to do this, and even package it up as an windows executable. Of course you are going to have to learn details of getting your app to run in windows, and perhaps learn a whole new GUI frame work. Then you have to deploy the executable, and redeploy it if modifications are made. And you have to setup a whole second configuration management system.
Instead wouldn't it be nice if you could just run your script in the browser? Now your code is written as a normal page, with some ruby snippets to handle the code that has to execute on the local machine. Your code is now part of your larger application, and is deployed via the browser.
<script type="text/ruby"> blocks to your pages, and then execute LocoRuby.eval(....) from javascriptLocoRuby.init({...}) to override default parameters.<script type="text/ruby">...</script> blocks to hold your local ruby code.LocoRuby.eval(...ruby expression..., function(return_value) {...}) to evaluate ruby expressions.JQuery - However if loco_ruby does not detect the JQuery object it will automatically load it so it is not required to be included. If you do use JQuery just include it before you do the LocoRuby to avoid redundant loads.
The LocoRuby.exe is simply a webrick server that acts as bootstrap loader. The browser makes cross browser requests to 127.0.0.1:8000 to send the LocoRuby.exe the ruby code, which is loaded as anonymous modules.
To keep the LocoRuby.exe as simple as possible it provides nothing but the basic capabilities. Additional features are provided by the loco_ruby.js file which collects the application ruby scripts from the web page, and wraps it up so you can call eval in the context of the downloaded code. The loco_ruby.js file also contains all the javascript and ruby code needed to manage the popup window interactions.
This is a simple example that brings up a window showing the current number of bytes used on the disk, updated every minute.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Bytes Free</title>
<script type='text/javascript' src='javascripts/loco_ruby.js'></script>
<script type='text/javascript'>
LocoRuby.init({
dimensions: {top: 20, left: 20, width: 150, height: 120},
stay_on_top: true,
onload: function() {update_display(); setInterval(update_display, 60*1000)},
popup_blocked: function() {}
})
function update_display() {
LocoRuby.eval("bytes_free", function (r) {
document.getElementById("bytes_free") = r/1024
})
}
</script>
<script type='text/ruby'>
def bytes_free
/([0-9]*) bytes free/.match(`dir /-C`)[1]
end
</script>
</head>
<body>
<div class="LocoRuby_loading">
Loading Application... If this message does not go away, then check to see that
you are running the LocoRuby.exe and that your browser is not blocking popups.
</div>
<div class="LocoRuby_loaded">
<span id="bytes_free"></span>K bytes free
</div>
</body>
</html>Call LocoRuby.init to override any of the defaults. LocoRuby.init takes a hash with the following optional keys:
LocoRuby.init({})
// run the code in the current window, no security checking. Same as LocoRuby.init(), or not calling it at all.
LocoRuby.init({title: "My PC App"})
// override the page title with "My PC App".
LocoRuby.init({onload: function(){alert('everything working!')}})
// pop up an alert once everything is downloaded.
LocoRuby.init({popup_timeout: 5000, popup_blocked: function () {alert('turn off popup blockers')}})
// after 5 seconds if we can't get a popup going, bring up an alert.
LocoRuby.init({dimensions: {top: 50, left: 50, width: 400, height: 400}})
// run in a new 400 X 400 popup positioned at 50, 50. top, left, width, and height must all be supplied.
LocoRuby.init({stay_on_top: true, dimensions: {top: 50, left: 50, width: 400, height: 400}})
// run in a new popup that stays above all other windows. stay_on_top is ignored unless dimensions are provided.
LocoRuby.init({connection_failure: function() {document.title = "CONNECTION FAILURE"}})
// change document title instead of bringing up alert. verfication_failure works the same
LocoRuby.init({host: "127.0.0.1:8001"})
// use port 8001 instead of 8000. Note you must run LocoRuby with the matching port. I.e.
// LocoRuby --port 8001
LocoRuby.init({encrypt: function(s, fn) {
jQuery.ajax({
url: "/loco_ruby_encrypt_helper/"+s,
context: document.body,
error: function(jqXHR, textStatus, errorThrown) {
alert("failed to get encrypted response from server")
},
success: fn
})}})
// use a server side REST method to digest strings. More below on this...
Download LocoRuby.exe and run it. You can simply click through the options pages and you will have a vanilla install that starts LocoRuby when the PC starts up, and listens on port 8000, with no security code.
You may also setup the following options:
The options are sent through as command line options in the shortcuts set up via the installer. See below for details on the options.
To evaluate an expression in the local ruby environment call
LocoRuby.eval("some ruby expression",optional_call_back, optional_time_out).
The first parameter is a string that will be evaluated in the context of a module made up of any code you have included
in <script type="text/ruby"> blocks.
The optional_call_back is a javascript function that receives the result of your evaluation as string. If the
evaluation times out undefined will be passed to the function.
The optional_time_out (in milliseconds) defaults to 10,000 (10 seconds) if not provided. Can also be overriden
globally in LocoRuby.init().
One of the features of LocoRuby is that you can create simple windows dialogs that run in the browser, but act like stand alone windows applications.
The trigger for this capability is providing dimensions to the init function. This lets LocoRuby know that a new dialog window is desired.
To accomplish this LocoRuby reloads the current page into a newly created browser popup, which is then sized and optionally forced to stay on top.
Once this is done, we want to get rid of the original browser window, so we either do a back (history(-1)) or if there
is no history then just close the original browser window (more on why below.)
Because LocoRuby is not currently set up to deal nicely with multiple windows running the same "application" it also makes sure that any existing popups (of the same application name) are closed before calling onload.
While all this seems complicated it gives a nice user experience. You can create an application links page that links to your LocoRuby popup pages. When the link is followed the LocoRuby page will be loaded in the same browser window, but then a popup will come up, and the parent window will go back to the original page, thus the popup acts like target="_BLANK", where you can control the size of the new window.
You can also create a windows short-cut where the target is the LocoRuby page. In this case when a user opens the short-cut a new browser window with no history is created, in which the LocoRuby code will begin to run. Once the popup is created the original window (with no history) can be deleted.
During debug you may find dealing with a javascript debugger is incompatible with the popup. Just change the dimension key to something like dimension_off, and it will be ignored, and you won't get a popup.
HTML with the LocoRuby_loaded class will remain hidden until the ruby code is up and running. The LocoRuby_loading class will then be hidden. Use these classes to display appropriate content before and after loading has completed.
By default LocoRuby.exe listens on port 8000, and the LocoRuby javascript object communicates with 127.0.0.1. To
listen on a different port run LocoRuby with the --port (-p) option. I.e. LocoRuby -p8001. The LocoRuby js object
must be initialized for the same host:port using the host: key.
I.e. ...host: "127.0.0.1:8001"....
If you want to add additional security you can set up a key on both your server and the local machine. You must provide a digest function on your server that matches the digest in LocalRuby.
--key your_key option. I.e. LocoRuby --key myspecialkey. If
you are launching LocoRuby from a shortcut (.lnk) your can specify the options in the shortcut target, but here is a tip:
Typically your shortcut link will look like this "C:/SomeDirectory/LocoRuby.exe". You want to specify the options
outside the double quotes, i.e "C:/SomeDirectory/LocoRuby.exe" --key myspecialkeyDigest::SHA1.hexdigest("--#{your_key}--#{some_string}--")
I.e. Digest::SHA1.hexdigest("--myspecialkey--#{s}--") where s is the string to digest typically provided via a get
request parameter.In many cases you will be using LocoRuby to simply provide the local "drivers" for a specific webpage. In this case
you can provide the url of the webpage via the -o (--open) option. I.e. LocoRuby -o"www.mysite.com/some_local_app_page".
When LocoRuby starts the webpage you specify will be opened, so you now effectively have a PC app, whose code resides on your server.
When LocoRuby.exe is running it displays a ruby symbol in the windows system tray. You can update the
tip text displayed by the icon by writting to the LocoRuby::Console.tray_icon_tip_text. I.e.
LocoRuby::Console.tray_icon_tip_text = "I just wrote this"
Should you need a more complex UI, the FxRuby gem is included. Just require fox16 in your local ruby script.
The LocoRuby executable is bundled with ruby debug, so all you have to do is invoke the debugger method. When the debugger starts a terminal window will be opened on the windows box. You use all the normal debugger features once you are in the console.
You can start the debugger from a javascript console (i.e. firebug) by calling LocoRuby.debug().
Inside your local ruby code you write to the logger via the LocoRuby::Log object. I.e. LocoRuby::Log.info "hello!".
By default the log level is set to info.
Log files are written to the directory containing the LocoRuby executable. Typically you will want to start a
console and run tail -f debug.log to view the log file contents.
You can also start LocoRuby.exe with the -d (--debugger) option which will set the logging level to DEBUG, write the logs to STDOUT (the console) and leave the console window open.
When debugging it is usually good to turn off the popup window feature so you can easily get at your browser debugger. The simple way to do this is just change the dimensions key to dimensions_off which will be ignored, and your application will run in the current browser window.
If you want to build your own LocoRuby.exe, you will need to install Ruby on a windows box, and install all the gems. LocoRuby comes in a single .rb file. You will also need to install Innosetup to create the one click installer.
Once you are happy you can build a new installer exe by running Rake.
Make it work with multiple instances of the same application. To do this is just a matter of skipping the download if the page has not changed.
Create a javascript object that contains constants, methods, and instance variables of the local ruby code. Then we
can just say LocoRuby.my_local_method() instead of using eval. Likewise return the result as a jsonp object instead
of a string.
Instead of using the browser popup, create a webkit based browser window in native UI app. This would give us better control over the way the popup looks.
Make Mac and Unix versions of the LocoRuby exe, and package up the right set up gems that would be needed for local machine access.
Copyright (c) 2011 CatPrintLabs.com
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Lars Christensen for the Ocra Gem used to create the executable.
Robert Wahler for the auto-gui gem which is included and makes controlling window's gui apps easy.
Thanks for the FxRuby gem.
Thanks to InnoSetup!