Talking in Pictures

Category: Ruby on Rails

ScreenSteps Desktop 2.7 Now Available! Download ScreenSteps 2.7

Creating a New Person in BatchBook Using the Ruby Batchbook API Wrapper

We have recently been migrating from Highrise to Batchbook for our CRM software. Though Batchbook isn’t nearly as pretty as Highrise, it has some killer functionality in regard to integration with other services we use as well as a pretty slick way for adding custom data fields. It also has an API that makes it easy to integrate with our existing apps.

The API has a Ruby wrapper so it should be a snap to implement. Except that there was a documentation failure. It wasn’t that the documentation was bad. It just wasn’t there. So here are a couple of examples to help anyone who might be using the Ruby wrapper. Hopefully this will save you a few hours of scratching your head.

The Ruby wrapper uses ActiveResource, which is pretty slick. The good thing about this endeavor was that I learned a lot more about ActiveResource which I hadn’t really paid attention to until now.

Setup

To start using the library all you need to do is [download the batchbook.rb file](http://github.com/batchblue/batchbook) and stick it somewhere in your app. I add it to the `lib/` directory.


Fix Settings

The current version of the batchbook.rb file on github has localhost as the domain. You won’t have much luck accessing the API at the localhost:3000 domain. Hopefully they will update this soon, but if they haven’t just change the batchbook.rb file on lines 41-44 to look like this:

 self.host_format = '%s://%s/%s'
 self.domain_format = '%s.batchbook.com'
 self.path = 'service'
 self.protocol = 'https'

Start Using

To start messing around with this I just run script/console from the terminal to get into my Rails app. Then enter:

require 'batchbook'
BatchBook.account = 'your_account'
BatchBook.token = 'your_api_key'

Creating a New Person With an Email

Creating a person is easy enough.

person = BatchBook::Person.new person.first_name = ‘john’ person.last_name = ‘doe’

But what if you want to add an email address? This WON’T work:

person.email = 'john@mail.com'

That is because Batchbook has this concept of locations. So a person doesn’t have an email address. They have a location labeled “work” which has email, phone, city, etc.

So to add that email address, do this:

location = BatchBook::Location.new
location.label = 'work' ## You need this line or it won't save
location.email = 'john@mail.com'

Now, before you call location.save you need to do one very important thing. The location is a nested attribute of the person, so you need to add a path prefix option. Do this:

If you haven’t already saved your person, do so. This will assign an ID to the person object, which you are going to need.

person.save

ActiveResource then posts the information to http://youraccount.batchbook.com/services/people.xml

Now add the prefix option to the location.

location.prefix_options[:person_id] = person.id

This is part of ActiveResource and will add a prefix onto the url. If you don’t add the prefix, ActiveResource posts to /services/locations.xml. That isn’t what you want. The API needs to get a POST to /services/people/#{the_id_of_the_person}/locations.xml. By adding the prefix_option person_id we tell ActiveResource to add the people/#{the_id_of_the_person} to the front of the locations url.

Now just save.

location.save

That’s it. In hindsight it makes sense. But it sure had me confused last night.

Webinar: Why Your Documentation is Useless and How to Fix It
Download the free webinar to learn why your documentation/knowledge base is ineffective and what simple steps you can take to improve it.
Bookmark and Share

Cancel Forms And Avoid The If Then Statements

One of the big pains with Rails form helpers is that they don’t have a cancel button. No, problem – that is easy enough to add in. Just use a second submit tag like so:

            <%= f.submit "Create" %>
            <%= submit_tag "Cancel" %>

Now, if the user clicks the “Cancel” button a “commit” param with a value of “Cancel” will be submitted.

This is nothing earth-shattering. I have found this technique on various blogs. But then they all suggest checking for this parameter in the update or create method of your controller. I don’t like this because it makes you add in extra “if-then” statements. I really hate “if-then” statements. They make the code so much harder to read.

So what to do?

Use a before filter.

before_filter :check_for_cancel, :only => [:create, :update]

Then add in your method to check for the cancel parameter in the commit message.

  private

  def check_for_cancel
    if params[:commit] == "Cancel"
      redirect_to admin_spaces_path
    end
  end

That’s it. So now, if anyone clicks on the “Cancel” button on an edit or new form they will be redirected to the index.

If you really wanted to you could make the Cancel button submit the cancel parameter as part of the model hash. You would do it like this:

            <%= submit_tag "Cancel", :name => "model[cancel]" %>

You would just need to update your check_for_cancel method to check for that param. I prefer the previous method though since it is more generic.

Bookmark and Share

ScreenSteps Live: A Case Study on Ruby on Rails – Part 2 – Figuring Out the Code

In my last post about developing ScreenSteps Live with Ruby on Rails (which was far too long ago) I talked a lot about what led to me getting started with Rails development. In this post I want to talk about what were some of the things about Ruby and Rails that I found really useful and what things were really confusing.

Once again – a little of my background. When I started this I had a music degree from the Berklee College of Music, knew some basic HTML and was at least competent at using CSS thanks to the book “CSS: The Missing Manual“, which I can’t recommend enough.

So I was by no means a programming expert. Concepts such Classes, Modules, ActiveRecord, View Helpers, Partials, Arrays, and Hashes were all totally foreign to me. I had done some database work several years ago where I got to dig into SQL commands a bit. This background at least gave me a good understanding of how relational databases worked.

The Stuff That Confused Me

Here are some of the things that initially confused me about Ruby and Rails:

Block notation

It looks something like this:

@posts.each {|p| p.some_method}

For some reason that totally confused me. Once you figure it out it is wonderful and very powerful. But as I read books and searched the internet I could find all these things that mentioned blocks but didn’t define what they were or how they worked. I think that I will do a post soon about the important things I wish I had known about blocks but I don’t have space for that here. Now that I understand them I can find plenty of information on them. Isn’t that always the case?

Ternary operators

url.blank? ? "Preview not available" : url

That type of stuff totally threw me for a loop. All it is doing is evaluating an expression and returning a value depending on the value returned by the expression. It is short hand for an if-then statement. But those ? and : are very intimidating when your code vocabulary is limited.

Array Operators

posts.collect {|p| p.title } posts.select {|p| p.title == "My Post"}

I didn’t like that stuff at all, mainly because I wasn’t comfortable with arrays yet. That compounded with the block notation had me dong a lot of head scratching.

The Stuff I Liked

(more…)

Bookmark and Share

ScreenSteps Live: A Case Study on Ruby on Rails – Part 1

At Blue Mango Learning Systems we primarily develop two applications:

Distributing a product for Mac, PC and running a hosted web service is a lot of work, especially when there are only two people in your company. Therefore we have had to choose our development tools very carefully. For us, the most important aspect of any development tool is our ability to quickly iterate over a product until we feel that we have it “right”. Really, for us, all other considerations fall way behind. If we can’t iterate efficiently then we are going to move on to another tool.

Ruby on Rails has proven to be a great tool for this type of development. There are a lot of people getting into Ruby on Rails so I thought some of you might be interested in my experience. I think that ScreenSteps Live is an interesting case study in the benefits and drawbacks of Rails, so over the next couple of months I will be posting some of the things that I have learned as I have dived into the Rails world.

First, a little background on myself as a programmer and ScreenSteps Live as a web app.

ScreenSteps Live Struggles to Come To Life

I have no background as a programmer. Well, almost none. We first got the idea for ScreenSteps Live back in late 2006 or early 2007. At that time I had never even attempted to program a web application. I knew some basic html, enough to throw up a web page, and enough php to do some basic includes. But nothing beyond that. I also had programmed some smaller desktop apps with Revolution but only after extensive help from Trevor.

But we needed a web app. Trevor wasn’t going to have time to do it so we decided to outsource. I won’t go into all of the details on this but our first attempt didn’t work out so well. Suffice it to say that after 2 months we had nothing and were out a few thousand dollars. All I can say is be very meticulous in checking out the people you are hiring to develop your stuff. We weren’t and it came back to bite us in the form of lost time and lost money.

(more…)

Bookmark and Share
Screensteps Support Suite

ScreenSteps is the most effective tool for creating and delivering customer tutorials and guides.
Learn about the ScreenSteps Support Suite