~tim/wuparty

a7e87fa724b85c4f47866307383ff5beebd6fc75 — Tim Morgan 11 years ago 2209969
Update to documentation.
2 files changed, 85 insertions(+), 22 deletions(-)

M README.rdoc
M lib/wufoo_party.rb
M README.rdoc => README.rdoc +21 -9
@@ 1,14 1,22 @@
= WufooParty

Lightweight wrapper for Wufoo API over HTTP using HTTParty.
WufooParty is a fairly lightweight wrapper for Wufoo's REST API[http://wufoo.com/docs/api/v3]
using HTTParty[http://httparty.rubyforge.org].

== About
== API Support

This is a very simple API wrapper that utilizes HTTParty -- a wonderful gem for consuming REST APIs.
Wufoo's REST API supports viewing and submitting of entries, filtering entries,
viewing reports, and viewing users.

This lib supports Wufoo's api version 3.0.
This library supports all methods of Wufoo's API version 3.0.

If you need to use version 2 of Wufoo's api, please use the 0.1.x release of WufooParty.
If you need to use version 2 of Wufoo's API, please use the older 0.1.x release of WufooParty.

== Source & Download

* {Homepage & Demo}[http://wufooparty.71m.us]
* {Sourcecode}[http://github.com/seven1m/wufoo_party]
* {RDoc Documentation}[http://seven1m.github.com/wufoo_party]

== Installation



@@ 44,11 52,15 @@ If you need to use version 2 of Wufoo's api, please use the 0.1.x release of Wuf
    
== Feedback

I’d love to hear from you if you have suggestions for improvement, bug fixes, or whatever. Email me at tim@timmorgan.org or fork the project and send a pull request.
I’d love to hear from you if you have suggestions for improvement, bug fixes, or whatever.
Email me at mailto:tim@timmorgan.org or fork the project[http://github.com/seven1m/wufoo_party] and send a pull request.

http://timmorgan.org

== Tests

To run the tests, you must create a form called "Test Form"
and pass in its id via the ENV variable WUFOO_FORM_ID.
Give the form a standard name and address field.
To run the tests, you must create a form called "Test Form" and pass in its id via the
ENV variable WUFOO_FORM_ID. Give the form a standard name and address field.
Make the name field required. Then run:

    WUFOO_ACCOUNT=accountname \

M lib/wufoo_party.rb => lib/wufoo_party.rb +64 -13
@@ 6,6 6,7 @@ require 'mime/types'

# multipart POST support from David Balater's fork of HTTParty:
# http://github.com/dbalatero/httparty
# :stopdoc:
module HTTParty
  module ClassMethods
    def post(path, options={})


@@ 65,6 66,7 @@ module HTTParty
      end
  end
end
# :startdoc:

class WufooParty
  include HTTParty


@@ 72,16 74,19 @@ class WufooParty

  VERSION = '0.9.0'

  # :stopdoc:
  # Represents a general error connecting to the Wufoo service
  class ConnectionError < RuntimeError; end

  # Represents a specific error returned from Wufoo.
  class HTTPError < RuntimeError
    def initialize(code, message)
    def initialize(code, message) # :nodoc:
      @code = code
      super(message)
    end

    # Error code
    attr_reader :code
  end
  # :startdoc:

  ENDPOINT    = 'https://%s.wufoo.com/api/v3'
  API_VERSION = '3.0'


@@ 181,20 186,35 @@ class WufooParty
    end

    attr_accessor :details

    # Return details
    def [](id)
      @details ||= @party.form(@id)
      @details[id]
    end
  end

  # Wraps an individual Wufoo Form.
  # == Instantiation
  # There are two ways to instantiate a Form object:
  # 1. Via the parent WufooParty object that represents the account.
  # 2. Via the WufooParty::Form class directly.
  #   wufoo = WufooParty.new(ACCOUNT, API_KEY)
  #   form = wufoo.form(FORM_ID)
  #   # or...
  #   form = WufooParty::Form.new(FORM_ID, :account => ACCOUNT, :api_key => API_KEY)
  # The first technique makes a call to the Wufoo API to get the form details,
  # while the second technique lazily loads the form details, once something is accessed via [].
  # == \Form Details
  # Access form details like it is a Hash, e.g.:
  #   form['Name']
  #   form['RedirectMessage']
  class Form < Entity
    # Returns field details for the form.
    def fields
      @party.get("forms/#{@id}/fields")['Fields']
    end

    # Access form details.
    def [](id)
      @details ||= @party.form(@id)
      @details[id]
    end

    # Returns fields and subfields, as a flattened array, e.g.
    #   [{'ID' => 'Field1', 'Title' => 'Name - First', 'Type' => 'shortname', 'Required' => true }, # (subfield)
    #    {'ID' => 'Field2', 'Title' => 'Name - Last',  'Type' => 'shortname', 'Required' => true }, # (subfield)


@@ 215,7 235,8 @@ class WufooParty
      flattened
    end

    # Return entries already submitted to the form
    # Return entries already submitted to the form.
    #
    # If you need to filter entries, pass an array as the first argument:
    #   entries([[field_id, operator, value], ...])
    # e.g.:


@@ 240,10 261,12 @@ class WufooParty
    # Submit form data to the form.
    # Pass data as a hash, with field ids as the hash keys, e.g.
    #   submit('Field1' => 'Tim', 'Field2' => 'Morgan')
    # Return value includes the following keys:
    # Return value is a Hash that includes the following keys:
    # * Status
    # * ErrorText
    # * FieldErrors
    # You must submit values for required fields (including all sub fields),
    # and dates must be formatted as <tt>YYYYMMDD</tt>.
    def submit(data)
      options = {}
      data.each do |key, value|


@@ 260,15 283,36 @@ class WufooParty
    end

    # Returns comment details for the form.
    # See Wufoo API documentation for possible options, e.g.
    # you can specify 'entryId' => 123 to filter comments only for the specified entry.
    # See Wufoo API documentation for possible options,
    # e.g. to filter comments for a specific form entry:
    #   form.comments('entryId' => 123)
    def comments(options={})
      options = {:query => options} if options.any?
      @party.get("forms/#{@id}/comments", options)['Comments']
    end
  end

  # Wraps an individual Wufoo Report.
  # == Instantiation
  # There are two ways to instantiate a Report object:
  # 1. Via the parent WufooParty object that represents the account.
  # 2. Via the WufooParty::Report class directly.
  #   wufoo = WufooParty.new(ACCOUNT, API_KEY)
  #   report = wufoo.report(REPORT_ID)
  #   # or...
  #   report = WufooParty::Report.new(REPORT_ID, :account => ACCOUNT, :api_key => API_KEY)
  # The first technique makes a call to the Wufoo API to get the report details,
  # while the second technique lazily loads the report details, once something is accessed via [].
  # == \Report Details
  # Access report details like it is a Hash, e.g.:
  #   report['Name']
  class Report < Entity
    # Access report details.
    def [](id)
      @details ||= @party.report(@id)
      @details[id]
    end

    # Returns field details for the report
    def fields
      @party.get("reports/#{@id}/fields")['Fields']


@@ 280,7 324,14 @@ class WufooParty
    end
  end

  # Wraps an individual Wufoo User.
  class User < Entity

    # Access user details.
    def [](id)
      @details ||= @party.report(@id)
      @details[id]
    end

  end
end