CloudWalk Ruby Runtime - Customizing an app

1. Prerequisites
2. Settings and Cwfile.json
3. Source code and DaFunk Framework API
4. Hello world

This guide will walk you through the process of customizing a Ruby application with the CloudWalk CLI. Be aware of the prerequisites and follow all the steps carefully.

Prerequisites

1. This guide assumes that you have completed the previous step: Creating a new app

Settings and Cwfile.json

The CloudWalk Manager provides an interface for customizing an app's settings on the web, and the Cwfile.json completes it with an easy way to edit those settings from the terminal. By running bundle exec rake cloudwalk:deploy every information in the file will update the application's attributes at the CloudWalk Manager, for Ruby and POSXML applications.

Understanding Cwfile.json and Cwfile.json.lock

1. Cwfile.json Manage Application and Modules attributes (name, description, host, versions and etc).
2. Cwfile.json.lock (DO NOT MODIFY THIS FILE, IT'S AUTOMATICALLY GENERATED) Contains the ids for all versions managed by Cwfile.json. Must be generated using the command bundle exec rake cloudwalk:update in every change performed at Cwfile.json.

Cwfile.json POSXML

Cwfile.json for POSXML applications supports to update version, authorizer URL, description and pos display label.

$ cat Cwfile.json # POSXML 
{
  "apps":[
    {
      "name":"posxmltest.xml",
      "modules":{},
      "version":"1.0.0",
      "authorizer_url":"https://myhost.com",
      "description":"posxmltest",
      "pos_display_label":"X"
    }
  ]
}

Cwfile.json Ruby

Cwfile.json for Ruby applications supports to update authorizer_url, description and pos display label.

$ cat Cwfile.json # Ruby 
{
  "name":"rb_test",
  "runtime": "ruby",
  "modules":{
  },
  "version":"1.0.0",
  "authorizer_url":"https://myhost.com",
  "description":"rb_test",
  "pos_display_label":"X"
}

Cwfile.json is different between Ruby and POSXML applications, because a repository of a POSXML application supports any number of POSXML applications and modules.

Source code and DaFunk Framework API

Files and Directories

1. lib/ Contains .rb/.xml files that will be compiled.
2. test/ Contains all test ruby files.
3. Gemfile/Gemfile.lock Manage CloudWalk CLI version and any other Ruby gem
4. Cwfile.json/Cwfile.json.lock Manage CloudWalk Application attributes.
5. Rakefile Ruby task files.

Application and DaFunk API

In order to let you build amazing Ruby applications, we have made an API client available within Ruby, that gives you all the methods you will need to start developing, making it easy to interact with the POS terminal's screen, printer, keyboard, network and to process different types of payments without the overhead of starting from scratch or using a low level language. This tool is called DaFunk and it's open source. Please check the entire DaFunk API documentation.

A new application comes with the following source code in the lib/main.rb file:

require 'simplehttp'

class Main < Device
  def self.call
    puts "Hello CloudWalk!"
    getc
    true
  end

  def self.foo
    :foo
  end

  def self.version
    "0.0.1"
  end
end

It describes some of the main steps of building an application. Let's look at it in detail:

require 'simplehttp'

It's how gems are required. It's Ruby so there must be gems!

The simplehttp gem was required in the Gemfile at the root of the project, and it is also open source. If you are an experienced Ruby developer, this information could be enough for you to build your custom gems for your application!

class Main < Device

It's where the Main class is defined. This is a requirement, all your applications must have a Main class.

Note that it doesn't necessarily have to inherit from the Device class. If you don't inherit, you might write Device specific methods including the name of the class, for example instead of writing puts, you would write Device.puts.

def self.call

Function that is executed each time the application runs. This function is a requirement and must be defined. Note that this function is executed inside a loop, so plan ahead.

puts "Card..."

Displays the string Card... on the terminal screen.

getc

Holds the execution by asking for a key to be pressed.

true

At the end of the Main.call method states whether the loop must continue or not.

Hello world

As a simple example, we can change this application to welcome whoever runs it, ask for a name and then say greetings to the given name.

If you are a Ruby developer, this is the code you might expect:

puts "Hello World! What's your name?"
name = gets
name = name.chomp # Removing the new line
puts "Hello #{name}!!!"

By putting that code inside the Main.call method, before the true at the end, a name will be requested, and after that the name will be displayed in the next line.

Try it yourself! Make the changes, run rake and then cloudwalk emulate. The main.rb file should end up like this:

require 'simplehttp'

class Main < Device
  def self.call
    puts "Hello World! What's your name?"
    name = gets
    name = name.chomp # Removing the new line
    puts "Hello #{name}!!!"
    true
  end

  def self.foo
    :foo
  end

  def self.version
    "0.0.1"
  end
end

• ← Creating a new app