“Setting up your Ruby on Rails environment for Force.com “

Like many of you, I was excited about the announcement regarding heroku at Dreamforce.  I wanted to learn more about Ruby and heroku and what better way to learn a new programming language than to write and deploy an application.  Though I found the getting started article useful, it assumes you have a working environment.  This article shows you how you can easily setup a working environment on a windows machine. 

The Big Picture

Before we get started, it is useful to understand how the toolkit fits into the overall Ruby environment. Ruby is a programming language  and Rails is a web application framework.  The Force.com toolkit for Ruby is a library (called a gem in Ruby parlance) that speaks to the Force.com database via the Web Services API.  Ruby provides several tools like gem for package management and rake a build program similar to make.  


Setting up the Ruby on Rails environment

The first step is to install Ruby.  I downloaded and installed from  this site – http://rubyinstaller.org/downloads/ .  Run the executable and choose the installation option to add Ruby executable to your path.  I installed it in c:softwareRuby192

Next, open a command window and follow the steps below.  We will be installing various libraries needed to setup our environment.

  •  Install rake.  We will need it later.

    c:softwareRuby192 >  gem install rake

  • Install Rails.  We explicitly specify version 2.3.8 since the toolkit was built against that version.

    c:softwareRuby192 >  gem install -v=2.3.8 rails

  •  Install hpricot as below.  I had to specify the platform flag since I got an error without it.  

    c:softwareRuby192 >  gem install hpricot –platform=mswin32

  • Install Facets.

    c:softwareRuby192 >  gem install -v=2.8.4 facets

  • Install the Force.com Ruby toolkit

    c:softwareRuby192 >  gem install asf-soap-adapter

At this point we have the necessary environment to create a Rails project that uses the Force.com toolkit.  Let us test it by creating a new project and making sure that everything is setup properly.

Testing the toolkit 

We start by creating a new rails project

c:softwareRailsExamples > rails test

This creates a new project under the directory test.  We would need to modify two of the files that rails creates for us.

  • configenvironment.rb – Add the reference to the Force.com toolkit.  Your file should look like this environment.rb file.
  • configdatabase.yml – you need to specify your org credentials.  Add a configuration element called salesforce-default-realm.  The final file should look like this database.yml file.  Do not forget to add the security token to the password element. 

We are now ready to test the connectivity.  Open a command window and go to the root of your project directory.  We will start the console to do our test.

c:softwareRailsExamplestest > ruby scriptconsole

You will now be able to call the different methods in the toolkit.  Let us do a simple query by typing the following in the console.

>> Salesforce::SfBase.query_by_sql(“select name from Account”) 

If everything is setup correctly, you should see a list of the accounts in your org.  

Congrats!  You now have a working environment to start building your Rails applications that leverages Force.com.

What next?

  • Download the example referenced in the wiki article.  You can either download the source or use git a distributed source code control tool.  You can find more information on git and githubhere.
  • Examine the source of the Force.com toolkit – especially sf_base.rb an sf_utility.rb to get an idea of the methods available.  The toolkit is available  here on github.
  • Build your own application and deploy on Heroku.  I will be examining this in a later blog.  

I hope this blog saves you some time as you begin your Ruby journey with Force.com and database.com.  I am excited about the possibilities. Finally, I would like to thank my friend Ray Gao for helping me with some of the issues I ran into while building my first Ruby app.

“Setting up your Ruby on Rails environment for Force.com “

"Basic vi editor commands"

General Startup
	To use vi: vi filename
	To exit vi and save changes: ZZ   or  :wq
	To exit vi without saving changes: :q!
	To enter vi command mode: [esc]

        A number preceding any vi command tells vi to repeat
	that command that many times.

Cursor Movement

	h       move left (backspace)

	j       move down

	k       move up

	l       move right (spacebar)

	[return]   move to the beginning of the next line

	$       last column on the current line

	0       move cursor to the first column on the
		current line

	^       move cursor to first nonblank column on the
		current line

	w       move to the beginning of the next word or
		punctuation mark

	W       move past the next space

	b       move to the beginning of the previous word
		or punctuation mark

	B       move to the beginning of the previous word,
		ignores punctuation

        e       end of next word or punctuation mark

        E       end of next word, ignoring punctuation

        H       move cursor to the top of the screen

        M       move cursor to the middle of the screen

        L       move cursor to the bottom of the screen

Screen Movement

       G        move to the last line in the file

       xG       move to line x

       z+       move current line to top of screen

       z        move current line to the middle of screen

       z-       move current line to the bottom of screen

       ^F       move forward one screen

       ^B       move backward one line

       ^D       move forward one half screen

       ^U       move backward one half screen

       ^R       redraw screen
		( does not work with VT100 type terminals )

       ^L       redraw screen
		( does not work with Televideo terminals )


       r        replace character under cursor with next
		character typed

       R        keep replacing character until [esc] is hit

       i        insert before cursor

       a        append after cursor

       A        append at end of line

       O        open line above cursor and enter append mode


	x       delete character under cursor

	dd      delete line under cursor

        dw      delete word under cursor

        db      delete word before cursor

Copying Code

        yy      (yank)'copies' line which may then be put by
		the p(put) command. Precede with a count for
		multiple lines.

Put Command
        brings back previous deletion or yank of lines,
	words, or characters

        P       bring back before cursor

        p       bring back after cursor

 Find Commands

	?       finds a word going backwards

	/       finds a word going forwards

        f       finds a character on the line under the
		cursor going forward

        F       finds a character on the line under the
		cursor going backwards

        t       find a character on the current line going
		forward and stop one character before it

	T       find a character on the current line going
		backward and stop one character before it

	;	repeat last f, F, t, T

Miscellaneous Commands

	.	repeat last command

	u	undoes last command issued

	U	undoes all commands on one line

	xp	deletes first character and inserts after
		second (swap)

	J	join current line with the next line

	^G	display current line number

	%	if at one parenthesis, will jump to its mate

	mx	mark current line with character x

	'x	find line marked with character x

	NOTE: Marks are internal and not written to the file.

Line Editor Mode
	Any commands form the line editor ex can be issued
	upon entering line mode.

	To enter: type ':'

	To exit: press[return] or [esc]

ex Commands
	For a complete list consult the
	UNIX Programmer's Manual

	copies (reads) filename after cursor in file
	currently editing

	:r filename


	:w 	saves the current file without quitting


	:#	move to line #

	:$	move to last line of file

	executes 'cmd' as a shell command.

"Basic vi editor commands"