We often work on projects that intersect two technologies near and dear to us: FileMaker and Ruby. This allows us to build robust web applications in Ruby on Rails, integrated with data sources from FileMaker solutions. When Claris introduced the FileMaker Data API we were naturally curious to try it out. At the time there was no off-the-shelf Ruby library for us to simply
gem install, so we decided to roll up our sleeves and build one. Thus, fmrest-ruby was born.
This article will walk you through setting up and using fmrest-ruby in a Ruby on Rails project. Some level of familiarity with Ruby/Rails and FileMaker’s Data API is advised, although much of the content covered here is applicable to any Ruby project, Rails or not.
Installation and Setup
Without further ado, let’s start with setting up fmrest-ruby on our Rails project. Simply add
fmrest to your Gemfile:
Once we have fmrest-ruby installed we’ll want a place to configure it, so we’ll create
Since this is a Rails project, which uses ActiveRecord by default, we take advantage of that and use the ActiveRecord token store. The token store is where fmrest-ruby will keep our Data API session tokens. If we weren’t using ActiveRecord we could choose a different back-end for our token store, like Redis or Moneta.
Next, we’ll need a place where to put our Data API connection settings: host, database, credentials, etc. Assuming we’ll only be connecting to a single FileMaker database, the easiest place for our settings is in
For real-world applications it’s recommended that you use encrypted credentials through Rails’
config/credentials.yml.enc, but for this example, the above should be enough.
There are many other connection options we can set here, but these are the barebone requirements to connect to our database. We leave logging turned on for development, but you may want to turn it off in production as it can be quite chatty.
This YAML file will not be loaded on its own though, so we’ll have to add the following to our initializer from earlier:
By now we are done with the setup, and we can start writing model classes connecting to our FileMaker layouts.
A good practice is to create a base model class that all our subsequent model classes will inherit from, so you can easily add common functionality. Rails does this for you already when you use ActiveRecord by providing an
ApplicationRecord class. We can recreate that, except using fmrest-ruby:
ApplicationFmLayout here, but you’re free to choose any name you like. And of course, this step is entirely optional, you’re free to skip it and inherit your models from
FmRest::Layout directly instead.
Cue Your FileMaker Database
Next, let’s add our first actual layout model class. First, we’ll need a FileMaker database to connect to. For simplicity’s sake, I’ll just create a pre-built Contacts app to use as our database.
Naturally, our first layout model will be called Contact, so let’s create it:
layout macro above specifies the name of the FileMaker layout we’ll be connecting this class to. If omitted, fmrest-ruby will try to use the name of the class as the layout name (
"Contact" in this example), but since in our case they don’t match, we need to specify it.
At this point we can actually start using our
Contact class. Let’s fire up a Rails console (
bin/rails c) to play a bit with it:
The first thing you’ll probably notice is that the logger is very chatty, spouting information about each Data API request as if there’s no tomorrow. That information can often be useful for debugging (especially if something had gone wrong with our Data API connection) but if it’s too much for your liking, you can go back to
config/filemaker.yml and turn the
log option to
false. You can always turn it back on if you need it later. For the sake of brevity I’ll leave logging off for the following examples.
Back to our Rails console, let’s modify a record:
So we’re already able to fetch a layout record, modify it and save it. That’s great, but having to access attributes by calling
contact["First Name"] is not very ergonomic nor Ruby-like. We can do better.
Let’s add some attribute mappings to our class:
attributes method lets us map Ruby-friendly names to actual layout field names. With this in place we can now do:
Much better! And we can actually use the new attribute mappings pretty much anywhere where a field name would be expected, for instance when querying:
.query method lets us define find conditions on field values for our find request, and
.sort specifies which field to sort by, similar to ActiveRecord’s
Topped Off With a Sprinkle of UI
So, let’s now leave our Rails console and build a simple web UI to list and display our layout records. We’ll start with the controller:
Next, a simple index view (
app/views/contacts/index.html.erb) listing links to contact profiles:
Notice how we call
contact_path(contact) instead of
contact_path(contact.record_id). This is because
FmRest::Layout is at its root compatible with ActiveModel (the bones of ActiveRecord), so it shares many tricks with ActiveRecord. One such trick is providing
to_param, a method that Rails’ path helpers (like
contact_path here) will try to call on their given argument, so we don’t have to explicitly point it to the id attribute.
And finally the Contact profile view (
With that in place we can now fire up our Rails server and open
/contacts in our browser, and voilà:
This is of course just a toy application, but from here on adding things like full CRUD operations or simple pagination should be fairly familiar territory (provided that you have experience building Rails apps.) So, I’ll leave that as an exercise for you, dear reader. Here are a few added suggestions:
And make sure to also give fmrest-ruby’s README a read for details on these and other, more advanced features.
I’m hoping to do a follow up blog post where I’ll add portals to our
If you’re interested in the nuts and bolts of how the Claris FileMaker Data API works I recommend you read Beezwax’s blog posts on the topic.