RubyTML v2.0

DESCRIPTION:

RubyTML (or just RTML) is a Ruby framework for communicating with Ingenico’s Incendo-based payment devices.

To really understand what RTML is about, you first have to understand what TML is. TML is an XML-like language called the “Terminal Markup Language” (yeah, we’re really creative with our naming conventions around here). Essentially, it allows developers to write terminal applications using a syntax that is essentially XML. This is a step forward for terminal developers, who are used to writing their applications in embedded C.

The Incendo architecture that runs all of this provides a gateway between an application server, which houses the TML, and the terminal. The TML is translated to byte code and then sent to the terminal via SSL. The terminal then executes this byte code, and only reconnects when it’s ready to download a new TML application. This is another step forward from embedded C, because there’s no longer any need to manually compile and then download applications to the terminal.

However, at the end of the day it’s still TML, and someone has to write that TML code. That’s where I come in. I was brought into Ingenico to write this TML, and I found the task nothing less than daunting. I came from a Java background, so of course the first thing I did was start looking at ways to write Java and have it generate TML. Unfortunately, that was like drilling a hole with a sledgehammer, and it didn’t work out too well. I quickly realized that I was going to spend more time writing the supporting Java code than I would on the TML itself, and given fairly ambitious deadlines, that just wasn’t going to be an option.

So I turned to Ruby. I’d been experimenting with Ruby on Rails over the past month or two, and was amazed at how brain-dead-simple it made standard Web development. I began to think – what is a TML application except for a bunch of glorified Web services? What if Rails could do to TML and XML what it has already done to HTML?

The biggest difference between HTML and TML is that the former is purely (or, in a Web 2.0 world, almost purely) View oriented. That is, HTML is designed for marking up and displaying content, not for transforming it. TML is a bit of a misnomer in that respect, because it is very much about the transforming of data. It takes care of receiving and processing the swipe of magnetic cards, amounts, and so on. In fact, the only thing it doesn’t really handle is actually processing a payment, which is a job left for the remote server.

So the short answer to just what is RTML? It’s a giant DSL (Domain Specific Language), basically, designed for generating TML with a vast reduction in keystrokes and lines-of-code. Check out the RTML web site at www.rubytml.com for more information – from tutorials to my RTML blog.

FEATURES:

  • It’s AWESOME!

  • RTML 1.x reduced lines of code in comparison to raw TML by an average factor of 60-70%, (in some cases as much as 90%), and RTML 2.0 intends to improve this gain in coding efficiency even further by abstracting all repeatable tasks into Widgets, which can now easily be published as Ruby Gems.

  • Widgets allow developers to write highly reusable blocks of RTML code which can then be called from an RTML application as many times as needed.

  • Adapts the Rails MVC approach to TML, neatly separating TML logic from server-side Rails code, moving display-oriented TML code into Views, and creating an Rtml::Transaction model which captures data sent back from a TML application.

PROBLEMS:

  • RubyTML is not a total TML replacement :( You still have to follow the rules, and the overall design process isn’t significantly different. That’s why a copy of the Incendo TML documentation is added to your Rails project when you script/generate rtml.

SYNOPSIS:

Rtml.action :index, :controller => :my_app do
  # cached document expires in 2 hours
  expires_at { 2.hours.from_now }
  integer :amount
  layout 'index'                             # applies the layout in app/views/layouts/index.rtml.erb to every screen

  screen :init, :next => :idle do
    tml.amount = 0                           # sets the terminal client-side variable 'amount' to 0
  end

  screen :idle, :next => :idle do
    display                                  # renders the view in app/views/my_app/index/idle.rtml.erb
  end
end

You should also check the rdoc documentation for Rtml::Widget and the various built-in Widgets for more information
and usage examples. Also, don't forget to go to www.rubytml.com for many more examples and walkthroughs!

REQUIREMENTS:

* hpricot     - 0.8.2
* rails       - 2.3.5
* sc-core-ext - 1.1.1

Test dependencies can be a bit of a question mark. RTML tests were actually written in rspec and make use of webrat for testing the TML output. There’s nothing preventing you from using the standard Rails Test::Unit framework, and generated code will generate Test::Unit tests for you. But you need to install the following rspec-specific gems if you plan to run the in-application tests via “rake rtml:test” – and enabling this will also generate rspec tests instead of Test::Unit ones. While there are a number of Test::Unit extensions for RTML, the unofficially official test framework for RTML is, obviously, rspec.

* rspec       - 1.3.0
* rspec-rails - 1.3.2
* webrat      - 0.7.0

In order to activate these gems after installation, you’ll also want to:

ruby script/generate rspec

INSTALL:

  • sudo gem install rtml

Then, Within Your Rails Application…

* config.gem 'rtml'      #=> marks RTML as an application dependency
* script/generate rtml   #=> generates the RTML migrations and supporting files
* rake rtml:test         #=> runs the entire RTML test suite within your app, to make sure all is peachy

LICENSE:

(The MIT License)

Copyright © 2010 Colin MacKenzie IV

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.