lardawge-rfm 1.0.0

data/README.rdoc

@@ -0,0 +1,233 @@
+= Rfm
+
+== Installation
+
+Run the following if you haven't already:
+
+	gem sources -a http://gems.github.com
+	
+Followed by:
+
+  gem install lardawge-rfm
+
+Once the gem is installed, you can use rfm in your ruby scripts by requiring it:
+
+  require 'rubygems'
+  require 'rfm'
+
+== Connecting
+
+You connect with the Rfm::Server object. This little buddy will be your window into FileMaker data.
+
+  require 'rfm/rfm'
+
+  my_server = Rfm::Server.new(
+    :host => 'myservername',
+    :username => 'user',
+    :password => 'pw'
+  )
+
+if your web publishing engine runs on a port other than 80, you can provide the port number as well:
+
+  my_server = Rfm::Server.new(
+    :host => 'myservername',
+    :username => 'user',
+    :password => 'pw',
+    :port => 8080  
+  )
+
+== Databases and Layouts
+
+All access to data in FileMaker's XML interface is done through layouts, and layouts live in databases. The Rfm::Server object has a collection of databases called 'db'. So to get ahold of a database called "My Database", you can do this:
+
+  my_db = my_server.db["My Database"]
+
+As a convenience, you can do this too:
+
+  my_db = my_server["My Database"]
+
+Finally, if you want to introspect the server and find out what databases are available, you can do this:
+
+  all_dbs = my_server.db.all
+
+In any case, you get back Rfm::Database objects. A database object in turn has a property called "layout":
+
+  my_layout = my_db.layout["My Layout"]
+
+Again, for convenience:
+
+  my_layout = my_db["My Layout"]
+
+And to get them all:
+
+  all_layouts = my_db.layout.all
+
+Bringing it all together, you can do this to go straight from a server to a specific layout:
+
+  my_layout = my_server["My Database"]["My Layout"]
+
+NOTE: for the ruby experts, Rfm::Server#db is an Rfm::Factory::DatabaseFactory object, which is just a fancied up Hash. So anything you can do with a hash, you can also do with my_server.db. The same goes for my_db.layouts, which is an Rfm::Factory::LayoutFactory.
+
+
+== Working with Layouts
+
+Once you have a layout object, you can start doing some real work. To get every record from the layout:
+
+  my_layout.all   # be careful with this
+
+To get a random record:
+
+  my_layout.any
+
+To find every record with "Arizona" in the "State" field:
+
+  my_layout.find({"State" => "Arizona"})
+
+To add a new record with my personal info:
+
+  my_layout.create({
+    :first_name => "Geoff",
+    :last_name => "Coffey",
+    :email => "gwcoffey@gmail.com"}
+  )
+
+Notice that in this case I used symbols instead of strings for the hash keys. The API will accept either form, so if your field names don't have whitespace or punctuation, you might prefer the symbol notation.
+
+To edit the record whos recid (filemaker internal record id) is 200:
+
+  my_layout.edit(200, {:first_name => 'Mamie'})
+
+Note: See the "Record Objects" section below for more on editing records.
+
+To delete the record whose recid is 200:
+
+  my_layout.delete(200)
+
+All of these methods return an Rfm::Result::ResultSet object (see below), and every one of them takes an optional parameter (the very last one) with additional options. For example, to find just a page full of records, you can do this:
+
+  my_layout.find({:state => "AZ"}, {:max_records => 10, :skip_records => 100})
+
+For a complete list of the available options, see the "expand_options" method in the Rfm::Server object in the file named rfm_command.rb.
+
+Finally, if filemaker returns an error when executing any of these methods, an error will be raised in your ruby script. There is one exception to this, though. If a find results in no records being found (FileMaker error # 401) I just ignore it and return you a ResultSet with zero records in it. If you prefer an error in this case, add :raise_on_401 => true to the options you pass the Rfm::Server when you create it.
+
+
+== ResultSet and Record Objects
+
+Any method on the Layout object that returns data will return a ResultSet object. Rfm::Result::ResultSet is a subclass of Array, so first and foremost, you can use it like any other array:
+
+  my_result = my_layout.any
+  my_result.size  # returns '1'
+  my_result[0]    # returns the first record (an Rfm::Result::Record object)
+
+The ResultSet object also tells you information about the fields and portals in the result. ResultSet#fields and ResultSet#portals are both standard ruby hashes, with strings for keys. The fields hash has Rfm::Result::Field objects for values. The portals hash has another hash for its values. This nested hash is the fields on the portal. This would print out all the field names:
+
+  my_result.fields.each { |name, field| puts name }
+
+This would print out the tables each portal on the layout is associated with. Below each table name, and indented, it will print the names of all the fields on each portal.
+
+  my_result.portals.each { |table, fields|
+    puts "table: #{table}"
+    fields.each { |name, field| puts "\t#{name}"}
+  }
+
+But most importantly, the ResultSet contains record objects. Rfm::Result::Record is a subclass of Hash, so it can be used in many standard ways. This code would print the value in the 'first_name' field in the first record of the ResultSet:
+
+  my_record = my_result[0]
+  puts my_record["first_name"]
+
+As a convenience, if your field names are valid ruby method names (ie, they don't have spaces or odd punctuation in them), you can do this instead:
+
+  puts my_record.first_name
+
+Since ResultSets are arrays and Records are hashes, you can take advantage of Ruby's wonderful expressiveness. For example, to get a comma-separated list of the full names of all the people in California, you could do this:
+
+  my_layout.find({:state => 'CA'}).collect {|rec| "#{rec.first_name} #{rec.last_name}"}.join(", ")
+
+Record objects can also be edited:
+
+  my_record.first_name = 'Isabel'
+
+Once you have made a series of edits, you can save them back to the database like this:
+
+  my_record.save
+
+The save operation causes the record to be reloaded from the database, so any changes that have been made outside your script will also be picked up after the save.
+
+If you want to detect concurrent modification, you can do this instead:
+
+  my_record.save_if_not_modified
+
+This version will refuse to update the database and raise an error if the record was modified after it was loaded but before it was saved.
+
+Record objects also have portals. While the portals in a ResultSet tell you about the tables and fields the portals show, the portals in a Record have the actual data. For example, if an Order record has Line Item records, you could do this:
+
+  my_order = order_layout.any[0]  # the [0] is important!
+  my_lines = my_order.portals["Line Items"]
+
+At the end of the previous block of code, my_lines is an array of Record objects. In this case, they are the records in the "Line Items" portal for the particular order record. You can then operate on them as you would any other record. 
+
+NOTE: Fields on a portal have the table name and the "::" stripped off of their names if they belong to the table the portal is tied to. In other words, if our "Line Items" portal includes a quantity field and a price field, you would do this:
+
+  my_lines[0]["Quantity"]
+  my_lines[0]["Price"]
+
+You would NOT do this:
+
+  my_lines[0]["Line Items::Quantity"]
+  my_lines[0]["Line Items::Quantity"]
+
+My feeling is that the table name is redundant and cumbersome if it is the same as the portal's table. This is also up for debate.
+
+Again, you can string things together with Ruby. This will calculate the total dollar amount of the order:
+ 
+  total = 0.0
+  my_order.portals["Line Items"].each {|line| total += line.quantity * line.price}
+
+I intend to add a 'delete' method to the Record class as well, but I haven't done this yet. Finally, should you be able to create new records using the Record class? I'm not sure...lots of points to consider on this.
+
+
+== Data Types
+
+FileMaker's field types are coerced to Ruby types thusly:
+
+  Text Field -> String object
+  Number Field -> BigDecimal object  # see below
+  Date Field -> Date object
+  Time Field -> DateTime object # see below
+  TimeStamp Field -> DateTime object
+  Container Field -> URI object
+
+FileMaker's number field is insanely robust. The only data type in ruby that can handle the same magnitude and precision of a FileMaker number is Ruby's BigDecimal. (This is an extension class, so you have to require 'bigdecimal' to use it yourself). Unfortuantely, BigDecimal is not a "normal" ruby numeric class, so it might be really annoying that your tiny filemaker numbers have to go this route. This is a great topic for debate.
+
+Also, Ruby doesn't have a Time type that stores just a normal time (with no date attached). The Time class in ruby is a lot like DateTime, or a Timestamp in FileMaker. When I get a Time field from FileMaker, I turn it into a DateTime object, and set its date to the oldest date Ruby supports. You can still compare these in all the normal ways, so this should be fine, but it will look weird if you, ie, to_s one and see an odd date attached to your time.
+
+Finally, container fields will come back as URI objects. You can:
+
+  - use Net::HTTP to download the contents of the container field using this URI
+  - to_s the URI and use it as the src attribute of an HTML image tag
+  - etc...
+
+Specifically, the URI refers to the _contents_ of the container field. When accessed, the file, picture, or movie in the field will be downloaded.
+
+== Troubleshooting
+
+There are two cheesy methods to help track down problems. When you create a server object, you can provide two additional optional parameters:
+
+:log_actions
+When this is 'true' your script will write every URL it sends to the web publishing engine to standard out. For the rails users, this means the action url will wind up in your WEBrick or Mongrel log. If you can't make sense of what you're getting, you might try copying the URL into your browser to see what is actually coming back from FileMaker.
+
+:log_responses
+When this is 'true' your script will dump the actual response it got from FileMaker to standard out (again, in rails, check your logs).
+
+So, for an annoying, but detailed load of output, make a connection like this:
+
+  my_server = Rfm::Server.new(
+    :host => 'myservername',
+    :username => 'user',
+    :password => 'pw',
+    :log_actions => true,
+    :log_responses => true
+  )
+
+These options will change in the future. They're only there now as a quick-easy way for me to track down problems. I'm open to suggestions for what kind of login options will make sense in the final release.

data/lib/rfm.rb

@@ -0,0 +1,232 @@
+# RFM provides easy access to FileMaker Pro data. With it, Ruby scripts can
+# perform finds, read records and fields, update data, and perform scripts using
+# a simple ruby-like syntax.
+#
+# Author::    Geoff Coffey  (mailto:gwcoffey@gmail.com)
+# Copyright:: Copyright (c) 2007 Six Fried Rice, LLC and Mufaddal Khumri
+# License::   See MIT-LICENSE for details
+#
+# RFM uses the FileMaker XML API, so it requires:
+# - FileMaker Server 9.0 or later
+# - or FileMaker Server Advanced 7.0 or later
+#
+# This documentation serves as a reference to the classes in the API. For more complete
+# usage documentation, see the RFM home page at http://sixfriedrice.com/wp/products/rfm/
+#
+# = Quick Start
+#
+# Rfm is a Gem. As such, any ruby file that uses it, needs to have these two lines on top:
+#
+#   require "rubygems"
+#   require "rfm"
+#
+# (If you don't have Rfm installed, use the +gem install rfm+ command to get it.)
+#
+# === Get a Server
+#
+# Everything in Rfm starts with the Server object. You create a Server object like this:
+#
+#   myServer = Rfm::Server.new(
+#     :host => "yourhost",
+#     :account_name => "someone",
+#     :pasword => "secret"
+#   )
+#
+# The Server object supports many other options, which you'll find explained in its
+# documentation.
+#
+# Note: The account name and password are optional. You can instead provide them on 
+# a per-database basis (using Database::account_name and Database::password). But 
+# it is convenient to do it here because you often have one set of credentials
+# across all databases. Also, you must provide an account_name and password if you
+# want to ask the server for a list of available databases.
+#
+# === Get a Database
+#
+# Once you have a Server object, you can use it to get a Database. For example, if your
+# database is called "Customers", you get it like this:
+#
+#   myDatabase = myServer["Customers"]
+#
+# If you need to supply account and password info specifically for this database
+# (rather than doing it at the Server level), do this:
+#
+#   myDatabase.account_name = "someone"
+#   myDatabase.password = "secret"
+#
+# *IMPORTANT NOTE:* The account name you use to access FileMaker must have the
+# +fmxml+ extended privilege. In other words, edit its privilege set and turn on
+# "Access via XML Web Publishing (fmxml)" in the Extended Privileges section
+# at the bottom-left of the Edit Privilege Set window. If you don't do this, 
+# Rfm will report that it can't log in.
+#
+# === Get a Layout
+#
+# Every action you send to FileMaker always goes through a layout. This is how Rfm knows
+# which table you want to work with, and which fields on that table you care about. This 
+# should feel pretty familiar now:
+#
+#   myLayout = myDatabase["Details"]
+#
+# You might use layouts you already have, or make new layout just for Rfm. Just remember that
+# if you delete a layout, or remove a field from a layout that your Rfm code uses, the 
+# code will stop working.
+#
+# === Putting it Together
+#
+# Usually you don't care much about the intermediate Database object (it's a gateway object,
+# if you will). So it is often easiest to combine all the above steps like this:
+#
+#   myLayout = myServer["Customers"]["Details"]
+#
+# === Performing Actions
+#
+# The Layout object can do a lot of things (see its documentation for a full list). But
+# in general, it involves records. For instance, you can find records:
+#
+#   result = myLayout.find({"First Name" => "Bill"})
+#
+# That code finds everybody whose first name in Bill. All the Layout methods return an
+# ResultSet object. It contains the records, as well as metadata about the fields and 
+# portals on the layout. Usually you'll only concern yourself with the records (and you
+# can read about the others in the ResultSet documentation). 
+#
+# ResultSet is a subclass of Array, Ruby's built in array type. So you can treate it just
+# like any other array:
+#
+#   first_record = result[0]
+#   a_few_records = result[3,7]
+#   record_count = result.size
+#
+# But usually you'll want to loop through them all. Because this is an array, you can use
+# code that is familiar to any Ruby whiz:
+#
+#   result.each { |record|
+#     # do something with record here
+#   }
+# 
+# === Working with Records
+#
+# The records in a ResultSet are actually Record objects. They hold the actual data from
+# FileMaker. Record subclasses Hash, another built in Ruby type, so you can use them like
+# this:
+#
+#   full_name = record["First Name"] + ' ' + record["Last Name"]
+#   info.merge(record)
+#   record.each_value { |value| puts value }
+#   if record.value?("Bill") then puts "Bill is in there somewhere"
+# 
+# The field name serves as the hash key, so these examples get fields called First Name and
+# Last Name. (Note: Unlike a typical Ruby hash, Record objects are not case sensitive. You
+# can say +record["first name"]+ or +record["FIRST NAME"]+ and it will still work.)
+#
+# A record object has the power to save changes to itself back to the database. For example:
+#
+#   records.each { |record| 
+#     record["First Name"] = record["First Name"].upcase
+#     record.save
+#   }
+#
+# That concise code converts the First Name field to all uppercase in every record in the
+# ResultSet. Note that each time you call Record::save, if the record has been modified, 
+# Rfm has to send an action to FileMaker. A loop like the one above will be quite slow
+# across many records. There is not fast way to update lots of records at once right now,
+# although you might be able to accomplish it with a FileMaker script by passing a 
+# parameter).
+#
+# === Editing and Deleting Records
+#
+# Any time you edit or delete a record, you *must* provide the record's internal record
+# if. This is not the value in any field. Rather, it is the ID FileMaker assigns to the
+# record internally. So an edit or delete is almost always a two-step process:
+#
+#   record = myLayout.find({"Customer ID" => "1234"})[0]
+#   myLayout.edit(record.record_id, {"First Name" => "Steve"})
+#
+# The code above first finds a Customer record. It then uses the Record::record_id method
+# to discover that record's internal id. That id is passed to the Layout::edit method.
+# The edit method also accepts a hash of record changes. In this case, we're changing
+# the value in the First Name field to "Steve".
+#
+# Also, note the [0] on the end of the first line. A find _always_ returns a ResultSet.
+# If there's only one record, it is still in an array. This array just happens to have only
+# one element. The [0] pulls out that single record.
+#
+# To delete a record, you would do this instead:
+#
+#   record = myLayout.find({"Customer ID" => "1234"})[0]
+#   myLayout.delete(record.record_id)
+#
+# Finally, the Layout::find method can also find a record using its internal id:
+#
+#   record = myLayout.find(some_id)
+#
+# If the parameter you pass to Layout::find is not a hash, it is converted to a string
+# and assumed to be a record id.
+#
+# === Performing Scripts
+#
+# Rfm can run a script in conjunction with any other action. For example, you might want
+# to find a set of records, then run a script on them all. Or you may want to run a script
+# when you delete a record. Here's how:
+#
+#   myLayout.find({"First Name" => "Bill"}, {:post_script => "Process Sales"})
+#
+# This code finds every record with "Bill" in the First Name field, then  runs the script
+# called "Process Sales." You can control when the script actually runs, as explained in
+# the documentation for Common Options for the Layout class.
+#
+# You can also pass a parameter to the script when it runs. Here's the deal:
+#
+#   myLayout.find(
+#     {"First Name" => "Bill"},
+#     {:post_script => ["Process Sales", "all"]}
+#   )
+#
+# This time, the text value "all" is passed to the script as a script parameter.
+#
+# =Notes on Rfm with Ruby on Rails
+#
+# Rfm is a great fit for Rails. But it isn't ActiveRecord, so you need to do things
+# a little differently.
+#
+# === Configuration
+#
+# To avoid having to reconfigure your Server object in every Rails action, you 
+# might add a configuration hash to the environment.rb. It can include all the
+# options you need to connecto to your server:
+#
+#   RFM_CONFIG = {
+#     :host => "yourhost",
+#     :account_name => "someone",
+#     :password => "secret",
+#     :db => "Customers"
+#   }
+#
+# Then you can get a server concisely:
+#
+#   myServer = Server.net(RFM_CONFIG)
+#   myServer[RFM_CONFIG[:db]]["My Layout"]...
+#
+# You might even want to add code to your application.rb to centralize access
+# to your various layouts.
+#
+# === Disable ActiveRecord
+#
+# If you're not using any SQL database in your Rails app, you'll quickly discover
+# that Rails insists on a SQL database configuration anyway. This is easy to fix.
+# Just turn off ActiveRecord. In the environment.rb, find the line that starts with
+# +config.frameworks+. This is where you can disable the parts of Rails you're not 
+# using. Uncomment the line and make it look like this:
+#
+#     config.frameworks -= [ :active_record ]
+# 
+# Now Rails will no longer insist on a SQL database.
+ 
+$: << File.expand_path(File.dirname(__FILE__))
+
+require 'rfm_command'
+require 'rfm_util'
+require 'rfm_result'
+require 'rfm_factory'
+require 'rfm_error'