= Shippinglogic

The goal of this library is to provide simple and straight forward interfaces to the various shipping web services: FedEx, UPS, USPS, etc. (Only FedEx is supported at this time)

== Helpful links

* <b>Documentation:</b> http://rdoc.info/projects/binarylogic/shippinglogic
* <b>Repository:</b> http://github.com/binarylogic/shippinglogic/tree/master
* <b>Bugs / feature suggestions:</b> http://binarylogic.lighthouseapp.com/projects/16601-searchlogic
* <b>Google group:</b> http://groups.google.com/group/shippinglogic

<b>Before contacting me directly, please read:</b>

If you find a bug or a problem please post it on lighthouse. If you need help with something, please use google groups. I check both regularly and get emails when anything happens, so that is the best place to get help. This also benefits other people in the future with the same questions / problems. Thank you.

== Install & use

Install the gem from rubyforge:

  sudo gem install shippinglogic

Or from github:

  sudo gem install binarylogic-shippinglogic

Now just include it in your project and you are ready to go.

You can also install this as a plugin:

  script/plugin install git://github.com/binarylogic/shippinglogic.git

See below for usage examples.

== Usage

What's unique about this library is it's usage / syntax. Let me show you...

=== Calls to the web services are lazy

A simple example where we want to track a FedEx package:

  fedex = Shippinglogic::FedEx.new(key, password, account, meter) # all credentials FedEx requires
  tracking = fedex.track(:tracking_number => "077973360403984")

Now here is why this is cool. Nothing has happened yet. No call has been made to the FedEx servers, etc. We do this because we don't need it yet. You don't need it until you start using the object. Lets continue with our example:

  tracking.first  # call is made to FedEx and returns the first tracking result in the array
  tracking.size   # cache is used to determine the size of the array

This is similar to how ActiveRecord's association proxies work. When you call user.orders no database activity occurs until you actually use the object.

=== Flexibility

You will notice above we assign the result of the 'track' method to a variable called 'tracking'. That object has more to it:

  # Initializing
  tracking = fedex.track(:tracking_number => "XXXXXXXXXXXXX")
  tracking.tracking_number
  # => "XXXXXXXXXXXXX"
  
  # Attribute accessors
  tracking.tracking_number = "YYYYYYYYYYYYYYY"
  tracking.tracking_number
  # => "YYYYYYYYYYYYYYY"
  
  # Mass attribute setting
  tracking.attributes = {:tracking_number => "ZZZZZZZZZZZZZZZZ"}
  tracking.tracking_number
  # => "ZZZZZZZZZZZZZZZZ"
  
  # Mass attribute reading
  tracking.attributes
  # => {:tracking_number => "ZZZZZZZZZZZZZZZZ"}

== Available services and their features

This library is still very new, as a result only FedEx is support at this time. More will come.

=== FedEx

1. <b>Tracking</b> - See Shippinglogic::Fedex::Track
1. <b>Getting service rates</b> - See Shippinglogic::Fedex::Rates

=== Add your own services

Simply fork the project and make your changes. If you want to add support for a new service it should be fairly straight forward. Checkout the code in Shippinglogic::Fedex::Track, it very simple and easy to follow. It's a great place to start because its the simplest of services.

== Interface integration

What's nice about having an object is that you can pass it around. Let's say you wanted to add simple FedEx tracking functionality to your app:

  class TrackingController < ApplicationController
    def new
      @tracking = fedex.track(params[:tracking])
    end
    
    def create
      @tracking = fedex.track(params[:tracking])
      render :action => :new if !@tracking.successful?
    end
    
    private
      def fedex
        @fedex ||= Shippinglogic::FedEx.new(key, password, account, meter)
      end
  end

That's pretty simple. Now check out your form:
  
  # new.html.haml
  - form_for @tracking do |f|
    = f.error_messages
    = f.text_field :tracking_number
    = f.submit "Track"

Then your results:

  # create.html.haml
  - @tracking.each do |event|
    .event
      .name= event.name
      .occured_at= event.occured_at.to_s(:long)
      .location== #{event.city}, #{event.state} #{event.postal_code}, #{event.country}
      .residential= event.residential ? "Yes" : "No"

== Copyright

Copyright (c) 2009 {Ben Johnson of Binary Logic}[http://www.binarylogic.com], released under the MIT license