UI Flow Shorthand Application - A Proposal

The OCRuby Users' Group Needs a Group Project

Here in Orange County, CA, Ruby Users' Group, we're in the process of selecting a "group project".

A Suggested Project

Here's an idea. Implement a simple graphical tool for Ryan Singer's recent posting on a shorthand notation for UI flow. Forrest and I both like it. If you haven't already, read Ryan's post. Here's an example from his article:



In the following discussion, I'll refer to Ryan's subject matter as "UI shorthand".

Now, it is to be admitted that Ryan himself protests building a tool for UI shorthand, but Forrest suggests that perhaps Ryan's shorthand could be another Cucumber script. Just because a Cucumber script doesn't attempt to "document everything" doesn't mean that the metaphor isn't a valuable vehicle for test-driven-development. We suggest that UI shorthand could be an additional valuable input for TDD.

Implementation Alternatives

So, presuming for sake of discussion that this is a project worth pursuing, what do we have w/ UI shorthand? Its artifacts are hand-drawn diagrams. Hmm, don't want to parse those.

If we want to capture the information in the hand-drawn diagrams in a parsible way, I can see two strategies:

1. Create a DSL (Domain Specific Language) that will generate the diagrams.
2. Build a WYSIWYG tool to interactively draw the diagrams.

Either of these alternatives could be implemented within a web application or as a Ruby-based client application; although some solutions would be more difficult and/or less-satisfying to the user than others.

Alternative 1 - Create a DSL and generate the diagrams

This can be implemented either on the server or the client. Since graphics are involved, if this is done on the client, then the user will need to download the rendering engine we select. If this is on the server, then the server can generate the graphic in a form that the user's browser will already know how to download and display.

This would be an opportunity to get involved with a graphics tool like SVN.

An example of a site doing something equivalent can be found here. http://yuml.me/

Here is an example of their generated output:



A second step would be to implement a filter that would convert the DSL to Cucumber or RSpec syntax.

Alternative 2 - Build a WYSIWYG tool to interactively draw the diagrams.

Ruby has all the libraries needed to implement a full WSYIWYG on the client. In this case, perhaps the tool would also generate the DSL so that it, in turn, could be converted to Cucumber or RSpec as described in alternative 1 above.

Doing a WYSIWYG is much harder on the server. About all I can think of is having the server rapidly generate a mouse-drag in Ajax while updating a image of the drag. At best, this is likely to be sluggish.

Or we could do it in a proprietary browser "desktop" like Microsoft's Silverlight or Flash.

Summary and Call to Action

Anyways, that's the extent that I've thought about it. This sound interesting? OCRubyists, please weigh in w/ comments here.

Thanks for your participation.

RForce/Salesforce Setup for Dummies

Justification

It took me too many hours to set up Salesforce and then use RForce to verify that Ruby could communicate w/ the Salesforce application. Hopefully the distillation that follows here will help pave the way for others. I explain very little "why"; but being able to see something "that works" may be helpful to your understanding.

Preconditions

• You have no Salesforce account.
• You have not installed RForce
• You have Ruby 1.8.7 installed and am reasonably Ruby-fluent.
  

Here's what we're going to accomplish:

• Create a developer Salesforce account and verify there is data entered into it.
  
• Grab the RForce gem.
• Write an unit test to retrieve data from the Salesforce account that was set up.

Detailed Steps

Create a Salesforce Developers Account

You will need an email account:

1. Browse http://www.salesforce.com/platform/developers.jsp
2. In the middle of the screen:
   

   

   click the large button to the right, "get started".
3. Fill in the requested information and submit.
4. After a minute or two, check the email account you submitted for an email titled: "Salesforce login confirmation" from info@sforce.com. Open the email up and click the link supplied to confirm your developer registration and to log in.
5. The login page will require you to change your password. Do so and submit.
6. The developer landing page will appear (top-left corner shown here):
   
7. At this point, you have just created your own "sandbox" CRM application. Add a record (that we will later retrieve from Ruby) by clicking the Home tab. Your home form will appear:
   
8. In the upper-left corner to the right of the Start Here tab, click the tab.
9. Click the Accounts link.
10. Set the dropdown labeled View to "All Accounts" and click Go.
11. You should see a list of accounts. We're going to pick one to retrieve: sForce. Hence, record the following information for it:
    
    
    
    
    
    
    
    
    
    
    

    Column Name	Value
    Account Name	sForce
    Phone	(415) 901-7000

12. Finally, you're gonna need to set up a security token. At the very top of the same page, click the link Setup. You should see your Personal Setup page.
13. In this part of the page:
    
    click the (magic) link Reset your security token.
14. A page, Reset Security Token, will appear. Click the button Reset Security Token.
15. A page will appear indicating that the security token has been sent to your email address.
16. Wait for the email to arrive at your mailbox. It will be titled Salesforce security token confirmation. The token will appear after "Security Token:". Copy it and save it in a safe place.

We're done with setting up our Salesforce cloud application and our security token.

Install RForce

Use Ruby gem to install RForce. The command is:

gem install rforce

(Don't forget the sudo if you are on the Macintosh.)

Create Test in Test::Unit

Copy the following unit test code into your favorite text editor:



require 'test/unit'
require 'rubygems'
gem 'rforce'
require 'rforce'

include RForce

class RforceRetrievalTest < Test::Unit::TestCase

  def setup
    @binding = RForce::Binding.new 'https://login.salesforce.com/services/Soap/u/16.0'
    userID = 'yourID' # replace w/ your actual Salesforce developer user ID.
    password = 'password' # replace w/ your Salesforce developer account password.
    securityToken = 'token' # replace w/ your security token
    @binding.login userID, (password + securityToken)
  end

  def test_retrieve_an_account
    answer = @binding.search :searchString => "find {sForce} in name fields returning account(id, phone)"
    record = answer[:searchResponse][:result][:searchRecords][:record]
    assert_equal 'Account', record[:type]
    assert_equal '(415) 901-7000', record[:Phone]
  end

end


Put this file where your unit test files belong in a Ruby project, run it, and verify that you can retrieve data from your new Salesforce application.

Enjoy!