Learning Ruby for Force.com Developers – Part 3

This is part #3 of my adventures of learning Ruby for Force.com developers. If you missed parts #1 and #2 you might want to take a look at those just to get up to speed. Again, these are my goals for this series:

• Learn Ruby
• Develop an app locally using Ruby on Rails and the default SQLite database (this is where we are at right now)
• Modify the app to use Database.com and the Force.com Toolkit for Ruby instead of the SQLite database
• Deploy the app to Heroku
• Modify the app to use Database.com and the REST API

In this post we'll get started building a web app using Ruby on Rails and SQLite. In a nutshell we'll be building a shopping cart app with a little twist. I do a lot of work for Medisend International, which is a non-profit that ships medical supplies to developing countries (among other things). They have an (old) international aid self-service portal that allows aid recipients (typically hospital administrators or local NGOs) to create a shipment and select medical supplies to be shipped to their country. We'll be building a replacement with Ruby on Rails.

Before you get started you might want to go through Get Started with Rails which has a lot of great stuff. I'm only using a subset of the functionality outlined in this guide so you'll definitely want to go through this entire article. I'll zip up all of the code for this part so you can download it and pick it apart.

The first thing we'll want to do is install our software needed for Rails. I had some issues during some of the installations but unfortunately I can't help out much so hopefully things go well for you. First, open Terminal and run the following lines:

sudo gem update --system
sudo gem install rails
sudo bundle install
sudo gem update rake
sudo gem update sqlite3-ruby

Now that all of your software is (hopefully) installed let's start building the app using SQLite to store data. Open Terminal and change to the directory where you want to store your files (~/Documents/Programming/Ruby in my case) and run the following command to create the application:

rails new mediaid-sqlite

This will create a Rails application called MediaidSqlite in a directory called mediaid-sqlite. Now switch to this new directory:

cd mediaid-sqlite

Rails created an entire directory structure for us with all of the files we need to begin building out the app. Feel free to take a look. We'll mainly be working in the app directory. Since we'll be using SQLite, run the following command to create an empty database:

rake db:create

This will create both a development and test SQLite databases inside the db/ folder. You now have a fully functional Rails application. To see it in action, fire up the web server on your local development machine by running:

rails server

If all goes well, when you point your browser to http://localhost:3000 you should see the following:

To stop the web server, simply hit Ctrl+C in the same Terminal window. I typically have at least two Terminal tabs open; one for the server and one for running commands. When running in development mode, Rails does not generally require you to bounce the server when changes are made; changes and files will be automatically picked up by the server.

For the required "Hello World" for the home page, you need to create at minimum a controller and a view. Fortunately, you can do that in a single command. Run the following command in Terminal:

rails generate controller home index

Now we need to delete the default page from your application so Rails will not load it by default. We need to do this as Rails will deliver any static file in the public directory in preference to any dynamic contact we generate from the controllers:

rm public/index.html

Now, you have to tell Rails where the new home page is located. Open the file config/routes.rb in Textmate or your favorite editor. This is your application’s routing file which holds entries in a special DSL that tells Rails how to route incoming requests to your controllers and actions. This file contains many commented out sample routes, and one of them actually shows you how to connect the root of your site to a specific controller and action. Find the line beginning with :root to towards the end of the file, uncomment it so that is looks like the following:

root :to => "home#index"

One of the cool thing about Rails is the scaffolding. Rails scaffolding is a quick and easy way to generate some of the major pieces of an application such as models, views, and controllers for a new resource. It provides the basic functionality and UI to CRUD records. We can create the scaffolding for Shipment and InventoryItem with just a few easy commands. The command below creates the scaffolding for the Shipment resource and specifies the fields for the model:

rails generate scaffold Shipment name:string country:string shipmentType:string status:string shipDate:date items:integer selected:integer reserved:integer

One of the outputs of the rails generate scaffold command is a database migration script. Migrations are Ruby classes that are designed to make it simple to create and modify database tables. Rails uses rake commands to run migrations, and it’s possible to undo a migration after it’s been applied to your database. Migration filenames include a timestamp to ensure that they’re processed in the order that they were created. Now use the following rake command to run the migration:

rake db:migrate

Now we need the InventoryItems to add to our Shipments. Run the following rails generated scaffold command to create the InventoryItems scaffolding:

rails generate scaffold InventoryItem name:string itemNumber:string category:string status:string shipment:integer

Now run the rake command to perform the database migration for InventoryItems:

rake db:migrate

So now we have our database setup and the basic functionality generated for us by Rails. Some people don't like the scaffolding and prefer to code from scratch but I'm going to simply modify the code generated by the scaffolding. The application consists of essentially 6 view and one controller. We'll look at the views first and then dig into the controller.

Home Page

The home page displays a summary of the available shipments and allows the user to select a shipment to process. There are also links at the bottom to access the auto-generated UI to CRUD records for both shipments and inventory items.

<h3>Welcome to MediSend's MediAid!</h3>

<p>MediAid is an international aid, self-service portal for
  inventory selection, processing and information centralization.</p>

<p>The following shipments are available for your aid case:</p>

<table width="75%" cellpadding="2" cellspacing="2">
<tr>
  <th align="left">Shipment</th>
  <th align="left">Type</th>
  <th align="left">Status</th>
</tr>
<% @shipments.each do |shipment| %>
<tr>
  <td><%= link_to shipment.name, shipment %></td>
  <td><%= shipment.shipmentType %></td>
  <td><%= shipment.status %></td>
</tr>
<% end %>
</table>


<br/>The following options are also available:

<ul>
  <li><%= link_to "Maintain Shipments", shipments_path %></li>
  <li><%= link_to "Maintain Inventory Items", inventory_items_path %></li>
</ul>

Shipment Display

This page is where most of the work is done for a shipment. It provides the relevant info on the shipment and allows the users to manage the shipment's contents.

<p id="notice"><%= notice %></p>

<script type="text/javascript">
function confirmDelete() {
  var answer = confirm("Are you sure you want to remove all items from this shipment?")
  if (answer) window.location = "/shipments/<%= @shipment.id %>/remove";
}

function confirmReserve() {
  var answer = confirm("Are you sure you want to update all of the items in this shipment as reserved?")
  if (answer) window.location = "/shipments/<%= @shipment.id %>/reserve";
}
</script>

<h3>Shipment <%= @shipment.name %></h3>

Status: <%= @shipment.status %><br/>
Type: <%= @shipment.shipmentType %><br/>
Country: <%= @shipment.country %><br/>
Items: <%= @shipment.items %><br/>
Selected: <%= @shipment.selected %><br/>
Reserved: <%= @shipment.reserved %>

Available options for this shipment:
<ol>
  <li><%= link_to 'View items in this shipment', items_shipment_path(@shipment) %></li>
  <li><%= link_to 'Add items by product category to this shipment', additems_shipment_path(@shipment) %></li>
  <li><a href="#" onclick="return confirmReserve();">Mark all items as "reserved" for this shipment</a></li>
  <li><a href="#" onclick="return confirmDelete();">Remove all items from this shipment</a></li>
  <li><%= link_to 'View this shipment\'s manifest', manifest_shipment_path(@shipment) %></li>
</ol>

<%= link_to 'Edit', edit_shipment_path(@shipment) %> |
<%= link_to 'Back', shipments_path %>

Add Inventory Items

The add items pages displays the number of available inventory items by category and if there is at least one available, provides the user with a link to add all of the available items. Clicking the link runs the addAll route to add the items to the shipment and then redirect the user back to the shipment display page.

<h3>Add Inventory by Category</h3>

<table width="100%" cellpadding="2" cellspacing="2">
<tr>
  <th align="left">Category</th>
  <th align="left">Available</th>
  <th align="left">Add All</th>
</tr>
<tr>
  <td>Surgical Gloves</td>
  <td><%= @gloves %></td>
  <td><% if @gloves > 0 %><a href="/shipments/<%= @shipment.id %>/addAll?category=Gloves">Add All</a><% else %>Add All<% end %></td>
</tr>
<tr>
  <td>Nebulizer Accessory Kits</td>
  <td><%= @nebulizer %></td>
  <td><% if @nebulizer > 0 %><a href="/shipments/<%= @shipment.id %>/addAll?category=Nebulizer">Add All</a><% else %>Add All<% end %></td>
</tr>
<tr>
  <td>Hyperinflation Systems</td>
  <td><%= @hyperinflation %></td>
  <td><% if @hyperinflation > 0 %><a href="/shipments/<%= @shipment.id %>/addAll?category=Hyperinflation">Add All</a><% else %>Add All<% end %></td>
</tr>
<tr>
  <td>Breathing Circuits</td>
  <td><%= @circuit %></td>
  <td><% if @circuit > 0 %><a href="/shipments/<%= @shipment.id %>/addAll?category=Circuits">Add All</a><% else %>Add All<% end %></td>
</tr>
<tr>
  <td>Armboards</td>
  <td><%= @armboard %></td>
  <td><% if @armboard > 0 %><a href="/shipments/<%= @shipment.id %>/addAll?category=Armboards">Add All</a><% else %>Add All<% end %></td>
</tr>
</table>

<br/><%= link_to 'Back', shipment_path(@shipment) %>

View Shipment Inventory Items

The page simply displays the inventory items currently assigned to this shipment.

<h3>Items for Shipment <%= @shipment.name %></h3>

<table width="100%" cellpadding="2" cellspacing="2">
<tr>
  <th align="left">Item</th>
  <th align="left">Name</th>
  <th align="left">Category</th>
  <th align="left">Status</th>
</tr>
<% @items.each do |item| %>
<tr>
  <td><%= item.itemNumber %></td>
  <td><%= item.name %></td>
  <td><%= item.category %></td>
  <td><%= item.status %></td>
</tr>
<% end %>
</table>

<br/><%= link_to 'Back', shipment_path(@shipment) %>

Mark Items as Reserved

Items that have been added to the shipment need to be marked as reserved so that they can be processed for shipping. Clicking "OK" runs the reserve route to mark the items in the shipment as reserved and then redirect the user back to the shipment display page.

Remove Items from Shipment

Users may want to remove all of the items from their shipment and begin the process anew. Clicking "OK" runs the remove route which removes all of the items from the shipment, making them available again, and then redirects the user back to the shipment display page.

Routes

To process the flow of our application we need to modify app/routes.rb to include our new pages. Here's a snippet from the beginning of the file:

resources :inventory_items

resources :shipments do
  member do
    get 'additems' # /shipments/1/additems
    get 'addAll'   # /shipments/1/addAll
    get 'items'    # /shipments/1/items
    get 'remove'   # /shipments/1/remove
    get 'reserve'  # /shipments/1/reserve
    get 'manifest' # /shipments/1/manifest
  end
end  

get "home/index"

ShipmentController

Last but not least is the ShipmentController. Controllers provide the “glue” between models and views. In Rails, controllers are responsible for processing the incoming requests from the web browser, interrogating the models for data, and passing that data on to the views for presentation. Take a look at the following code which should explain quite a bit. Since the controller contains code both generated by Rails and added by me, I've annotated it for your viewing ease.

class ShipmentsController < ApplicationController
  # GET /shipments
  # GET /shipments.xml
  def index
    @shipments = Shipment.all

    respond_to do |format|
      format.html # index.html.erb
      format.xml  { render :xml => @shipments }
    end
  end

  # GET /shipments/1
  # GET /shipments/1.xml
  def show
    @shipment = Shipment.find(params[:id])

    respond_to do |format|
      format.html # show.html.erb
      format.xml  { render :xml => @shipment }
    end
  end

  # GET /shipments/new
  # GET /shipments/new.xml
  def new
    @shipment = Shipment.new

    respond_to do |format|
      format.html # new.html.erb
      format.xml  { render :xml => @shipment }
    end
  end

  # GET /shipments/1/edit
  def edit
    @shipment = Shipment.find(params[:id])
  end

  # CUSTOM
  # GET /shipments/1/additems
  def additems
    @shipment = Shipment.find(params[:id])

    # get a a count of the available inventory by category
    @gloves = InventoryItem.where(:category => 'Gloves', :status => 'Available').count
    @nebulizer = InventoryItem.where(:category => 'Nebulizer', :status => 'Available').count
    @hyperinflation = InventoryItem.where(:category => 'Hyperinflation', :status => 'Available').count
    @circuit = InventoryItem.where(:category => 'Circuits', :status => 'Available').count
    @armboard = InventoryItem.where(:category => 'Armboards', :status => 'Available').count
  end

  # CUSTOM
  # GET /shipments/1/addAll
  def addAll
    @shipment = Shipment.find(params[:id])

    # add all of the avaiilable items for the category to the shipment as 'selected'
    InventoryItem.where(:category => params[:category], :status => 'Available').each do |item|
      # assign the item to the shipment
      item.shipment = @shipment.id
      # set the status as 'selected'
      item.status = 'Selected'
      item.save
    end
    # update the shipment with total number of items on it
    @shipment.items = InventoryItem.where(:shipment => @shipment.id).count
    # update the shipment with the total number of 'selected' items
    @shipment.selected = InventoryItem.where(:shipment => @shipment.id, :status => 'Selected').count
    @shipment.save
    respond_to do |format|
      format.html { redirect_to(@shipment, :notice => 'Items have been successfully added.') }
      format.xml  { head :ok }
    end
  end

  # CUSTOM
  # GET /shipments/1/items
  def items
    @shipment = Shipment.find(params[:id])

    # fetch all of the items on the shipment regardless of status
    @items = InventoryItem.where(:shipment => @shipment.id).order(:name)
  end

  # CUSTOM
  # GET /shipments/1/manifest
  def manifest
    @shipment = Shipment.find(params[:id])

    # fetch all of the items on the shipment regardless of status
    @items = InventoryItem.where(:shipment => @shipment.id).order(:name)
  end

  # CUSTOM
  # GET /shipments/1/remove
  def remove
    @shipment = Shipment.find(params[:id])

    # remove all items on the shipment
    InventoryItem.where(:shipment => @shipment.id).each do |item|
      # remove it from the shipment
      item.shipment = nil
      # mark the item as available
      item.status = 'Available'
      item.save
    end

    # update the shipment with the correct counts
    @shipment.items = 0
    @shipment.reserved = 0
    @shipment.selected = 0
    @shipment.save
    respond_to do |format|
      format.html { redirect_to(@shipment, :notice => 'All items removed from the shipment.') }
      format.xml  { head :ok }
    end
  end

  # CUSTOM
  # GET /shipments/1/reserve
  def reserve
    @shipment = Shipment.find(params[:id])

    # mark all items on the shipment as reserved
    InventoryItem.where(:shipment => @shipment.id).each do |item|
      item.status = 'Reserved'
      item.save
    end

    # get a count of the number of reserved items on the shipment
    @shipment.reserved = InventoryItem.where(:shipment => @shipment.id).count
    @shipment.save
    respond_to do |format|
      format.html { redirect_to(@shipment, :notice => 'All items were successfully marked as reserved.') }
      format.xml  { head :ok }
    end
  end

  # POST /shipments
  # POST /shipments.xml
  def create
    @shipment = Shipment.new(params[:shipment])

    respond_to do |format|
      if @shipment.save
        format.html { redirect_to(@shipment, :notice => 'Shipment was successfully created.') }
        format.xml  { render :xml => @shipment, :status => :created, :location => @shipment }
      else
        format.html { render :action => "new" }
        format.xml  { render :xml => @shipment.errors, :status => :unprocessable_entity }
      end
    end
  end

  # PUT /shipments/1
  # PUT /shipments/1.xml
  def update
    @shipment = Shipment.find(params[:id])

    respond_to do |format|
      if @shipment.update_attributes(params[:shipment])
        format.html { redirect_to(@shipment, :notice => 'Shipment was successfully updated.') }
        format.xml  { head :ok }
      else
        format.html { render :action => "edit" }
        format.xml  { render :xml => @shipment.errors, :status => :unprocessable_entity }
      end
    end
  end

  # DELETE /shipments/1
  # DELETE /shipments/1.xml
  def destroy
    @shipment = Shipment.find(params[:id])
    @shipment.destroy

    respond_to do |format|
      format.html { redirect_to(shipments_url) }
      format.xml  { head :ok }
    end
  end
end

Summary

That's our application in a nutshell. You can download a zip of the entire project from here. In the next part of the series we'll dive into the Force.com Toolkit for Ruby and really start to integrate with the platform.

Related Posts:

• Learning Ruby for Force.com Developers – Part 1
• Learning Ruby for Force.com Developers – Part 2