Class: Rfm::Layout

Inherits:
Object show all
Includes:
Config, LayoutModule
Defined in:
lib/rfm/layout.rb,
lib/rfm/base.rb

Overview

The Layout object represents a single FileMaker Pro layout. You use it to interact with records in FileMaker. All access to FileMaker data is done through a layout, and this layout determines which table you actually hit (since every layout is explicitly associated with a particular table – see FileMakers Layout->Layout Setup dialog box). You never specify table information directly in RFM.

Also, the layout determines which fields will be returned. If a layout contains only three fields from a large table, only those three fields are returned. If a layout includes related fields from another table, they are returned as well. And if the layout includes portals, all data in the portals is returned (see Record::portal for details).

As such, you can significantly improve performance by limiting what you put on the layout.

Using Layouts

The Layout object is where you get most of your work done. It includes methods for all FileMaker actions:

  • Layout::all

  • Layout::any

  • Layout::find

  • Layout::edit

  • Layout::create

  • Layout::delete

Running Scripts

In FileMaker, execution of a script must accompany another action. For example, to run a script called _Remove Duplicates_ with a found set that includes everybody named Bill, do this:

myLayout.find({"First Name" => "Bill"}, :post_script => "Remove Duplicates")

Controlling When the Script Runs

When you perform an action in FileMaker, it always executes in this order:

  1. Perform any find

  2. Sort the records

  3. Return the results

You can control when in the process the script runs. Each of these options is available:

  • post_script tells FileMaker to run the script after finding and sorting

  • pre_find_script tells FileMaker to run the script before finding

  • pre_sort_script tells FileMaker to run the script before sorting, but after finding

Passing Parameters to a Script

If you want to pass a parameter to the script, use the options above, but supply an array value instead of a single string. For example:

myLayout.find({"First Name" => "Bill"}, :post_script => ["Remove Duplicates", 10])

This sample runs the script called “Remove Duplicates” and passes it the value 10 as its script parameter.

Common Options

Most of the methods on the Layout object accept an optional hash of options to manipulate the action. For example, when you perform a find, you will typiclaly get back all matching records. If you want to limit the number of records returned, you can do this:

myLayout.find({"First Name" => "Bill"}, :max_records => 100)

The :max_records option tells FileMaker to limit the number of records returned.

This is the complete list of available options:

  • max_records tells FileMaker how many records to return

  • skip_records tells FileMaker how many records in the found set to skip, before returning results; this is typically combined with max_records to “page” through records

  • sort_field tells FileMaker to sort the records by the specified field

  • sort_order can be descend or ascend and determines the order of the sort when sort_field is specified

  • post_script tells FileMaker to perform a script after carrying out the action; you can pass the script name, or a two-element array, with the script name first, then the script parameter

  • pre_find_script is like post_script except the script runs before any find is performed

  • pre_sort_script is like pre_find_script except the script runs after any find and before any sort

  • response_layout tells FileMaker to switch layouts before producing the response; this is useful when you need a field on a layout to perform a find, edit, or create, but you want to improve performance by not including the field in the result

  • logical_operator can be and or or and tells FileMaker how to process multiple fields in a find request

  • modification_id lets you pass in the modification id from a Record object with the request; when you do, the action will fail if the record was modified in FileMaker after it was retrieved by RFM but before the action was run

Attributes

The Layout object has a few useful attributes:

  • name is the name of the layout

  • field_controls is a hash of FieldControl objects, with the field names as keys. FieldControl’s tell you about the field on the layout: how is it formatted and what value list is assigned

Note: It is possible to put the same field on a layout more than once. When this is the case, the value in field_controls for that field is an array with one element representing each instance of the field.

  • value_lists is a hash of arrays. The keys are value list names, and the values in the hash are arrays containing the actual value list items. value_lists will include every value list that is attached to any field on the layout

Direct Known Subclasses

SubLayout

Defined Under Namespace

Modules: LayoutModule Classes: SubLayout

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from LayoutModule

#all, #any, #create, #delete, #edit, #expand_repeats, #find, #get_records, #join_repeats, #name, #params, #query, #state, #view

Methods included from Config

#config, #config_clear, #get_config, #sanitize_config

Constructor Details

#initialize(*args) ⇒ Layout

Initialize a layout object. You never really need to do this. Instead, just do this:

myServer = Rfm::Server.new(...)
myDatabase = myServer["Customers"]
myLayout = myDatabase["Details"]

This sample code gets a layout object representing the Details layout in the Customers database on the FileMaker server.

In case it isn’t obvious, this is more easily expressed this way:

myServer = Rfm::Server.new(...)
myLayout = myServer["Customers"]["Details"]

Raises:



137
138
139
140
 
# File 'lib/rfm/layout.rb', line 137

def initialize(*args)
  @subs ||= []
  main_init(*args)
end

Instance Attribute Details

#field_mapping ⇒ Object (readonly)

Returns the value of attribute field_mapping.



157
158
159
 
# File 'lib/rfm/layout.rb', line 157

def field_mapping
  @field_mapping
end

#field_names ⇒ Object 



349
350
351
352
 
# File 'lib/rfm/layout.rb', line 349

def field_names
	load unless @field_names
	@field_names
end

#portal_meta ⇒ Object 



371
372
373
 
# File 'lib/rfm/layout.rb', line 371

def portal_meta
	@portal_meta ||= view.portal_meta
end

#subs ⇒ Object

SubLayout



57
58
59
 
# File 'lib/rfm/base.rb', line 57

def subs
  @subs
end

#table ⇒ Object 



383
384
385
 
# File 'lib/rfm/layout.rb', line 383

def table
	@table ||= view.table
end

Instance Method Details

#count(find_criteria, options = {}) ⇒ Object 



363
364
365
 
# File 'lib/rfm/layout.rb', line 363

def count(find_criteria, options={})
	find(find_criteria, options.merge({:max_records => 0})).foundset_count
end

#date_format ⇒ Object 



329
330
331
 
# File 'lib/rfm/layout.rb', line 329

def date_format
	@date_format ||= view_meta.date_format
end

#field_controls ⇒ Object 



344
345
346
347
 
# File 'lib/rfm/layout.rb', line 344

def field_controls
  load unless @loaded
  @field_controls
end

#field_meta ⇒ Object 



338
339
340
 
# File 'lib/rfm/layout.rb', line 338

def field_meta
	@field_meta ||= view_meta.field_meta
end

#field_names_no_load ⇒ Object 



354
355
356
 
# File 'lib/rfm/layout.rb', line 354

def field_names_no_load
	@field_names
end

#ignore_bad_data(val = nil) ⇒ Object

This method may be obsolete, since the option can now be set with #config.



163
164
165
166
 
# File 'lib/rfm/layout.rb', line 163

def ignore_bad_data(val = nil)
	(config :ignore_bad_data => val) unless val.nil?
	state[:ignore_bad_data]
end

#load_field_mapping(mapping = {}) ⇒ Object 



439
440
441
442
443
444
445
 
# File 'lib/rfm/layout.rb', line 439

def load_field_mapping(mapping={})
	mapping = (mapping || {}).to_cih
	def mapping.invert
		super.to_cih
	end
	mapping
end

#main_init ⇒ Object 



59
 
# File 'lib/rfm/base.rb', line 59

alias_method :main_init, :initialize

#modelize ⇒ Object

Creates new class with layout name, subclassed from Rfm::Base, and links the new model to a SubLayout instance.



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/rfm/base.rb', line 74

def modelize
 	model_name = name.to_s.gsub(/\W/, '_').classify.gsub(/_/,'')
 	(return model_name.constantize) rescue nil
 	sub = sublayout
 	sub.instance_eval do
  	model_class = eval("::" + model_name + "= Class.new(Rfm::Base)")
  	model_class.class_exec(self) do |layout_obj|
  		@layout = layout_obj
  	end
  	@model = model_class
  	
		# Added by wbr to give config heirarchy: layout -> model -> sublayout
		model.config :parent=>'@layout.parent_layout'
  	config :parent=>'model'
  end
  sub.model.to_s.constantize
 rescue StandardError, SyntaxError
 	nil
end

#models ⇒ Object 



94
95
96
 
# File 'lib/rfm/base.rb', line 94

def models
	subs.collect{|s| s.model}
end

#portal_meta_no_load ⇒ Object 



375
376
377
 
# File 'lib/rfm/layout.rb', line 375

def portal_meta_no_load
	@portal_meta
end

#portal_names ⇒ Object 



379
380
381
 
# File 'lib/rfm/layout.rb', line 379

def portal_names
	portal_meta.keys
end

#sublayout ⇒ Object 



65
66
67
68
69
70
71
 
# File 'lib/rfm/base.rb', line 65

def sublayout
	if self.is_a?(Rfm::Layout)
		sub = SubLayout.new(self); subs << sub; sub
	else
		self
	end
end

#table_no_load ⇒ Object 



387
388
389
 
# File 'lib/rfm/layout.rb', line 387

def table_no_load
	@table
end

#time_format ⇒ Object 



332
333
334
 
# File 'lib/rfm/layout.rb', line 332

def time_format
	@time_format ||= view_meta.time_format
end

#timestamp_format ⇒ Object 



335
336
337
 
# File 'lib/rfm/layout.rb', line 335

def timestamp_format
	@timestamp_format ||= view_meta.timestamp_format
end

#total_count ⇒ Object 



367
368
369
 
# File 'lib/rfm/layout.rb', line 367

def total_count
	view.total_count
end

#value_lists ⇒ Object 



358
359
360
361
 
# File 'lib/rfm/layout.rb', line 358

def value_lists
  load unless @loaded
  @value_lists
end

#view_meta ⇒ Object 



326
327
328
 
# File 'lib/rfm/layout.rb', line 326

def view_meta
	@view_meta ||= view
end