Class: Rfm::Record

Inherits:
CaseInsensitiveHash show all
Defined in:
lib/rfm/record.rb

Overview

The Record object represents a single FileMaker record. You typically get them from ResultSet objects. For example, you might use a Layout object to find some records:

results = myLayout.find({"First Name" => "Bill"})

The results variable in this example now contains a ResultSet object. ResultSets are really just arrays of Record objects (with a little extra added in). So you can get a record object just like you would access any typical array element:

first_record = results[0]

You can find out how many record were returned:

record_count = results.size

And you can of course iterate:

results.each (|record|
  // you can work with the record here
)

Accessing Field Data

You can access field data in the Record object in two ways. Typically, you simply treat Record like a hash (because it is a hash…I love OOP). Keys are field names:

first = myRecord["First Name"]
last = myRecord["Last Name"]

If your field naming conventions mean that your field names are also valid Ruby symbol named (ie: they contain only letters, numbers, and underscores) then you can treat them like attributes of the record. For example, if your fields are called “first_name” and “last_name” you can do this:

first = myRecord.first_name
last = myRecord.last_name

Note: This shortcut will fail (in a rather mysterious way) if your field name happens to match any real attribute name of a Record object. For instance, you may have a field called “server”. If you try this:

server_name = myRecord.server

you’ll actually set server_name to the Rfm::Server object this Record came from. This won’t fail until you try to treat it as a String somewhere else in your code. It is also possible a future version of Rfm will include new attributes on the Record class which may clash with your field names. This will cause perfectly valid code today to fail later when you upgrade. If you can’t stomach this kind of insanity, stick with the hash-like method of field access, which has none of these limitations. Also note that the myRecord[] method is probably somewhat faster since it doesn’t go through method_missing.

Accessing Repeating Fields

If you have a repeating field, RFM simply returns an array:

val1 = myRecord["Price"][0]
val2 = myRecord["Price"][1]

In the above example, the Price field is a repeating field. The code puts the first repetition in a variable called val1 and the second in a variable called val2.

Accessing Portals

If the ResultSet includes portals (because the layout it comes from has portals on it) you can access them using the Record::portals attribute. It is a hash with table occurrence names for keys, and arrays of Record objects for values. In other words, you can do this:

myRecord.portals["Orders"].each {|record|
  puts record["Order Number"]
}

This code iterates through the rows of the Orders portal.

Field Types and Ruby Types

RFM automatically converts data from FileMaker into a Ruby object with the most reasonable type possible. The type are mapped thusly:

  • Text fields are converted to Ruby String objects

  • Number fields are converted to Ruby BigDecimal objects (the basic Ruby numeric types have much less precision and range than FileMaker number fields)

  • Date fields are converted to Ruby Date objects

  • Time fields are converted to Ruby DateTime objects (you can ignore the date component)

  • Timestamp fields are converted to Ruby DateTime objects

  • Container fields are converted to Ruby URI objects

Attributes

In addition to portals, the Record object has these useful attributes:

  • record_id is FileMaker’s internal identifier for this record (not any ID field you might have in your table); you need a record_id to edit or delete a record

  • mod_id is the modification identifier for the record; whenever a record is modified, its mod_id changes so you can tell if the Record object you’re looking at is up-to-date as compared to another copy of the same record

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(record, result, field_meta, layout, portal = nil) ⇒ Record

Returns a new instance of Record.



105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/rfm/record.rb', line 105

def initialize(record, result, field_meta, layout, portal=nil)
  @record_id = record['record-id']
  @mod_id    = record['mod-id']
  @mods      = {}
  @layout    = layout
  @portals ||= Rfm::CaseInsensitiveHash.new

  relatedsets = !portal && result.instance_variable_get(:@include_portals) ? record.xpath('relatedset') : []
  
  record.xpath('field').each do |field|
    field_name = field['name']
    field_name.gsub!(Regexp.new(portal + '::'), '') if portal
    datum = []
    
    field.xpath('data').each do |x| 
      datum.push(field_meta[field_name].coerce(x.inner_text, result))
    end
  
    if datum.length == 1
      self[field_name] = datum[0]
    elsif datum.length == 0
      self[field_name] = nil
    else
      self[field_name] = datum
    end
  end
  
  unless relatedsets.empty?
    relatedsets.each do |relatedset|
      tablename, records = relatedset['table'], []
  
      relatedset.xpath('record').each do |record|
        records << self.class.new(record, result, result.portal_meta[tablename], layout, tablename)
      end
  
      @portals[tablename] = records
    end
  end
  
  @loaded = true
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(symbol, *attrs, &block) ⇒ Object (private) 



217
218
219
220
221
222
223
224
225
 
# File 'lib/rfm/record.rb', line 217

def method_missing(symbol, *attrs, &block)
  method = symbol.to_s
  return read_attribute(method) if self.key?(method)

  if method =~ /(=)$/ && self.key?($`)
    return @mods[$`] = attrs.first
  end
  super
end

Instance Attribute Details

#mod_id ⇒ Object (readonly)

Returns the value of attribute mod_id.



103
104
105
 
# File 'lib/rfm/record.rb', line 103

def mod_id
  @mod_id
end

#portals ⇒ Object (readonly)

Returns the value of attribute portals.



103
104
105
 
# File 'lib/rfm/record.rb', line 103

def portals
  @portals
end

#record_id ⇒ Object (readonly)

Returns the value of attribute record_id.



103
104
105
 
# File 'lib/rfm/record.rb', line 103

def record_id
  @record_id
end

Class Method Details

.build_records(records, result, field_meta, layout, portal = nil) ⇒ Object 



147
148
149
150
151
 
# File 'lib/rfm/record.rb', line 147

def self.build_records(records, result, field_meta, layout, portal=nil)
  records.each do |record|
    result << self.new(record, result, field_meta, layout, portal)
  end
end

Instance Method Details

#[](value) ⇒ Object 



200
201
202
 
# File 'lib/rfm/record.rb', line 200

def [](value)
  read_attribute(value)
end

#[]=(name, value) ⇒ Object

Gets the value of a field from the record. For example:

first = myRecord["First Name"]
last = myRecord["Last Name"]

This sample puts the first and last name from the record into Ruby variables.

You can also update a field:

myRecord["First Name"] = "Sophia"

When you do, the change is noted, but *the data is not updated in FileMaker*. You must call Record::save or Record::save_if_not_modified to actually save the data.

Raises:



192
193
194
195
196
197
 
# File 'lib/rfm/record.rb', line 192

def []=(name, value)
  return super unless @loaded
  raise Rfm::ParameterError, 
    "You attempted to modify the field :#{name} which does not exist in the current Filemaker layout." unless self.key?(name)
  @mods[name] = value
end

#_original_hash_reader ⇒ Object 



199
 
# File 'lib/rfm/record.rb', line 199

alias :_original_hash_reader :[]

#respond_to?(symbol, include_private = false) ⇒ Boolean

Returns:

  • (Boolean) 


204
205
206
207
 
# File 'lib/rfm/record.rb', line 204

def respond_to?(symbol, include_private = false)
  return true if self.include?(symbol.to_s)
  super
end

#save ⇒ Object

Saves local changes to the Record object back to Filemaker. For example:

myLayout.find({"First Name" => "Bill"}).each(|record|
  record["First Name"] = "Steve"
  record.save
)

This code finds every record with Bill in the First Name field, then changes the first name to Steve.

Note: This method is smart enough to not bother saving if nothing has changed. So there’s no need to optimize on your end. Just save, and if you’ve changed the record it will be saved. If not, no server hit is incurred.



166
167
168
169
 
# File 'lib/rfm/record.rb', line 166

def save
  self.merge(@layout.edit(self.record_id, @mods)[0]) if @mods.size > 0
  @mods.clear
end

#save_if_not_modified ⇒ Object

Like Record::save, except it fails (and raises an error) if the underlying record in FileMaker was modified after the record was fetched but before it was saved. In other words, prevents you from accidentally overwriting changes someone else made to the record.



174
175
176
177
 
# File 'lib/rfm/record.rb', line 174

def save_if_not_modified
  self.merge(@layout.edit(@record_id, @mods, {:modification_id => @mod_id})[0]) if @mods.size > 0
  @mods.clear
end