Payday is a Ruby gem that will help you create simple invoices. It’s a generic PDF invoicing library and as I will show you in this tutorial, it can be easily used to help you create invoices from Paypal transactions.

First thing to do, add the gem to your Gemfile :

gem "payday"

Next, you can create a rails initializer file with your company infos :

# /config/initializers/payday.rb
Payday::Config.default.invoice_logo = "#{Rails.root}/public/images/logo.png"
Payday::Config.default.company_name = "My Company inc."
Payday::Config.default.company_details = "100 Sunset Blvd\nHollywood\nUnited States\ninfo@mycompany.com"

When a client makes a purchase on Paypal, you can configure your account to receive Instant Payment Notifications (IPN). I save each transaction in a Payment model and dump the paypal IPN request params in a serialized hash called paypal_params. This is the method from my model class I use to generate the invoice :

# app/models/payment.rb
serialize :paypal_params

def generate_pdf_invoice
  invoice = Payday::Invoice.new(
    :invoice_number => paypal_params['invoice'],
    :currency => paypal_params['mc_currency'])
  invoice.paid_at = invoice.due_at = created_at.to_date
  invoice.bill_to = invoice.ship_to = paypal_params.slice(
    'address_name', 'address_street', 'address_city',
    'address_zip', 'address_country').values.join("\n")
  invoice.line_items << Payday::LineItem.new(
    :price => paypal_params['mc_gross'],
    :quantity => 1,
    :description => paypal_params['item_name'])
  invoice.notes = "Thank you for your purchase!"
  invoice.render_pdf
end

Obviously, you will want to adjust this code to fit what you are selling. In my case, there is always only one line item in my transactions.

Finally, I make the invoice downloadable from the user account page. The controller method works like this :

# app/controllers/payments_controller.rb
def pdf_invoice
  payment = Payment.find_by_tx_id! params[:id]
  respond_to do |format|
    format.pdf do
      send_data payment.generate_pdf_invoice,
        :filename => payment.invoice_filename,
        :type => "application/pdf"  , :disposition => "inline"
    end
  end
end

Again, you will probably have to adjust this method for your own needs. Don’t forget to add the pdf mime type to the mime_types.rb initializer :

# /config/initializers/mime_types.rb
Mime::Type.register 'application/pdf', :pdf

There’s a lot more you can do with Payday. It supports I18n and it integrates well with ActiveRecord. I encourage you to take a look at the readme on github.

So if you are using the Facebook Javascript SDK and set the cookies option to true, Safari won’t accept the FBS_XXXX cookie planted by the SDK. I struggled a whole week-end before figuring it out.

The work-around I use is to set a cookie from the server with the signed_request in it if there is one present. This solves most of the problems since I can just use the cookie when I don’t have a fresh signed_request (this happens when I do a request inside the canvas).

Here is the code inside a before_filter in the application_controller. I use Rails with the Facebooker2 gem :

The P3P header is used to make IE6 and IE7 accept the cookie as well.

If you’re building a Facebook canvas application with Rails, take the time to also read my post about keeping your REST architecture with the POST requests.

Starting March 10th, The POST for canvas option will become mandatory for all Facebook canvas apps. This means all requests to your iframe originating from the Facebook frame will be POST requests. If you use restful controllers in your app, this is not a good news. Fortunately, there is a very easy way to convert those POST back to GET with a Rack middleware :

Since all request coming from Facebook will include a signed_request parameter, you can assume that these requests are coming from the top frame. Other requests made directly from your iframe won’t be altered. You can safely now safely use Post for canvas and continue to assume all requests coming from the top frame will be get requests.

With Poll for Facebook, you can add as many questions as you want to your poll, images and invite your friends to answer it. There is a free and a Premium version.

I encourage you to try it and give me your feedback. It is now available in English, French, Spanish and German.

1. Prepare the map in your model

In your Geolocation model, start by adding this snippet of code which will initialize your map.

def map
  @map ||= prepare_map
end

def mapped?
  latitude && longitude
end

def coordinates
  [latitude, longitude]
end

private

def prepare_map
  return unless mapped?
  returning GMap.new("gmap") do |map|
    map.control_init(:large_map => true, :map_type => true)
    map.center_zoom_init(coordinates, 15) # Set the center and zoo level
    map.overlay_init(GMarker.new(coordinates))
  end
end

The important method here is prepare_map. What it does is create a new map centered at the given coordinates. The overlay_init method sets a marker at the coordinates position. This is a basic vanilla map initialization. You might want to read the YM4R api for more options like adding an info window or multiple markers.

2. Call it from your controller

In our controller, we will set the @map variable to make it accessible in our view :

@map = customer.geolocation.map

3. Display the map in your view

You will need this snippet of code in the header section of your document to do the proper javascript imports and initializations :

= GMap.header
= @map.to_html

And in the body of your view, where you want to display the map, simply add :

@map.div(:width => 600, :height => 400)

This last line will generate a div with the id “gmap” (or whatever name you set in the GMap.new function). I find it’s cleaner to just set the width an height through CSS.

4. Adding complexity

This technique will only work if you display only one map on the page. The map needs to be visible on page load to be properly displayed. But what if there is multiple maps you want to display on the same page? And what if you want to show them in overlay popups? You probably don’t want to initialize them all on page load since it will freeze the client browser. This will require some javscript hacking. I will show you how to do that next week!

1. The user enters an address and you need to validate it and geoposition it (latitude & longitude) on a map.
2. You need to display the google map for that given address on a webpage.

Today, I will show you how I did the first step using the YM4R/GM plugin.

1- Setup the plugin and get you Google Maps key

First thing to do is to install the YM4R/GM plugin plugin. There is also a gem but it seems to be a stripped-down version of the plugin. I couldn’t get it working so I would advise to use the plugin :

script/plugin install svn://rubyforge.org/var/svn/ym4r/Plugins/GM/trunk/ym4r_gm

The plugin creates a file in your config folder named gmaps_api_key.xml. You need to enter your Google Maps API keys for the different environments. You can get the keys here.

2- Create the model

Next thing to do is to create your Geolocation activerecord model. You need to at least have those four attributes :

create_table "geolocations", :force => true do |t|
  t.string   "address"
  t.string   "city"
  t.float    "latitude"
  t.float    "longitude"
end

You might also want to add the country and postal code to the mix. But in most case, Google Maps will be able to return you a location with just a street address and a city.

3- Set the geolocation on the before_save

When you create a new gelocation record, you want to geoposition it. Here’s my code in the Geolocation.rb model :

before_save :set_geolocation

def set_geolocation
  if changes['address'] || changes['city'] || !mapped?
    results = Geocoding::get(complete_address)
    if results.status == Geocoding::GEO_SUCCESS
      self.latitude, self.longitude = results[0].latlon
    else
      self.latitude, self.longitude = nil
    end
  end
end

def complete_address
  [address, city].select(&:present?).join(', ')
end

def mapped?
  latitude && longitude
end

What this does is set the latitude and longitude for the given address on the before_save callback. We first check if the address or the city changed and if so we try to get a geocoding. If the API responds with SUCCESS, we set the latitude and longitude with the first result. If the API failed to return a valid address, we set the latitude and longitude to nil. We can check if the address was mapped using the mapped? method.

4- Wrap it up

Geopositionning the address is only the first part of the problem. Next week I’ll show you how to use the latitude and longitude information we stored to display Google maps in your webpages.

Next week : How to display a google map for a geopositioned address

Typically, when working locally, your mongrel or webrick instance running on port 3000 is not accessible unless you enable port forwarding on your router. And even then, your ISP probably doesn’t assign you a fixed IP address which means you have to run a dynamic IP address service like dyndns. This quickly gets complicated and if you work behind a corporate network or develop from different locations (ex.: home, office, Starbucks…), this solution won’t even work.

Meet Tunnlr, an easy to use service that makes your local Rails server accessible from the Internet by just typing a single rake command in your console. When you register to the service, you will be assigned a fixed URL address with a port number and this is the address you will use to configure your Facebook application and access it locally.

One downside to that approach is that since each request has to do a return trip to the Tunnlr servers, you loose the lightning speed loading time you’re used to when developing from your local machine (no network latency). I found a little hack that will bypass the need to do a return trip and it can be done in three easy steps

1- Modify your /etc/hosts file and add the following line :

127.0.0.1	web1.tunnlr.com

This tells your machine to route all requests made to the web1.tunnlr.com address to your local machine. Unfortunately, there is no way to specify port redirections in the hosts file so we need step 2 and 3 to make sure our remote and local ports are the same.

2- Modify your tunnlr.yml or facebooker.yml file to make your local port the same as your remote port. In my case, this is port 10524.

remote_port: 10524
local_port: 10524

3- Start your Rails server with the same port that has been assigned to you by Tunnlr.
[/code]script/server -p 10524[/code]

That’s it! Now when you query web1.tunnlr.com your local requests will stay local and your server will still be remotely accessible from the tubes!

The Rails documentation states that this can be useful for forms that are triggered from multiple places.

In my case I needed it to redisplay the same page after a post that didn’t validate. I could redirect the user back to the right action but some request parameters were missing in the post action that prevented this to work right.

For example, if the last request was /my_action?location=there, I would lose the location parameter if I didn’t send it along in the post. And I didn’t want to send the parameter along since I was calling a different controller which business logic didn’t relate to these parameters.

Well, by using the HTTP referer, Rails redirects back to the URL with the right parameters and sends the user to the exact same location he was. Neat!

// Alternates the background colors of the elements
// elems  - Array of jQuery DOM objects
// colors - Array of hexadecimal colors
function alternateBgColor(elems, colors) {
    elems.each( function(index) {
    var colorIndex = index % colors.length;
    $(this).css('background-color', colors[colorIndex]);
  });
}

It’s only a three lines function but the cool thing about it is that you can alternate through as many colors as you need. I’m only using two for now but this could come useful at some point! I like how everything javascript just got easier with jQuery.