MotionModel: Models, Relations, and Validation for RubyMotion
MotionModel is a DSL for cases where Core Data is too heavy to lift but you are still intending to work with your data, its types, and its relations. It also provides for data validation and actually quite a bit more.
File | Module | Description |
---|---|---|
ext.rb | N/A | Core Extensions that provide a few Rails-like niceties. Nothing new here, moving on... |
model.rb | MotionModel::Model | You should read about it in "What Model Can Do". Model is the raison d'etre and the centerpiece of MotionModel. |
validatable.rb | MotionModel::Validatable | Provides a basic validation framework for any arbitrary class. You can also create custom validations to suit your app's unique needs. |
input_helpers | MotionModel::InputHelpers | Helps hook a collection up to a data form, populate the form, and retrieve the data afterwards. Note: MotionModel supports Formotion for input handling as well as these input helpers. |
formotion.rb | MotionModel::Formotion | Provides an interface between MotionModel and Formotion |
transaction.rb | MotionModel::Model::Transactions | Provides transaction support for model modifications |
MotionModel is MIT licensed, which means you can pretty much do whatever you like with it. See the LICENSE file in this project.
- Getting Going
- Bugs, Features, and Issues, Oh My!
- What Model Can Do
- Model Data Types
- Validation Methods
- Model Instances and Unique IDs
- Using MotionModel
- Transactions and Undo/Cancel
- Notifications
- Core Extensions
- Formotion Support
- Problems/Comments
- Submissions/Patches
Bugs, Features, and Issues, Oh My!
The reason this is up front here is that in order to respond to your issues we need you to help us out by reading these guidelines. You can also look at Submissions/Patches near the bottom of this README which restates a bit of this.
That said, all software has bugs, and anyone who thinks otherwise probably is smarter than I am. There are going to be edge cases or cases that our tests don't cover. And that's why open source is great: other people will run into issues we can fix. Other people will have needs we don't have but that are of general utility. And so on.
But… fair is fair. We would make the following requests of you:
- Debug the code as far as you can. Obviously, there are times when you just won't be able to see what's wrong or where there's some squirrely interaction with RubyMotion.
- If you are comfortable with the MotionModel code, please try to write a spec that makes it fail and submit a pull request with that failing spec. The isolated test case helps us narrow down what changed and to know when we have the issue fixed. Two things make this even better:
- Our specs become more comprehensive; and
- If the issue is an interaction between MotionModel and RubyMotion, it's easier to pass along to HipByte and have a spec they can use for a quick hitting test case. Even better, fix the bug and submit that fix and the spec in a pull request.
- If you are not comfortable with the MotionModel code, then go ahead and describe the issue in as much detail as possible, including backtraces from the debugger, if appropriate.
Now, I've belabored the point about bug reporting enough. The point is, if you possibly can, write a spec.
Issues: Please mark your issues as questions or feature requests, depending on which they are. We'll do all we can to review them and answer questions as quickly as possible. For feature requests, you really can implement the feature in many cases and then submit a pull request. If not, we'll leave it open for consideration in future releases.
Summary
Bugs: Please write a failing spec
Issues: Please mark them as question or request
Changes for Existing Users to Be Aware Of
Please see the CHANGELOG for update on changes.
Version 0.4.4 is the first version to be gem-compatible with RubyMotion 2.0
Version 0.3.8 to 0.4.0 is a minor version bump, not a patch version. Upgrading to 0.4.0 will break existing code. To update your code, simply insert the following line:
class ModelWithAdapter
include MotionModel::Model
include MotionModel::ArrayModelAdapter # <== Here!
columns :name
end
This change lays the foundation for using other persistence adapters. If you don't want to update all your models, install the gem:
$ gem install motion_model -v 0.3.8
or if you are using bundler:
gem motion_model, "0.3.8"
Version 0.3.8 was the last that did not separate the model and persistence concerns.
Getting Going
If you are using Bundler, put this in your Gemfile:
gem 'motion_model'
then do:
bundle install
If you are not using Bundler:
gem install motion_model
then put this in your Rakefile after requiring motion/project
:
require 'motion_model'
If you want to use Bundler from master
, put this in your Gemfile:
gem 'motion_model', :git => 'git@github.com:sxross/MotionModel.git'
Note that in the above construct, Ruby 1.8.x hash keys are used. That's because Apple's System Ruby is 1.8.7 and won't recognize keen new 1.9.x hash syntax.
What MotionModel Can Do
You can define your models and their schemas in Ruby. For example:
class Task
include MotionModel::Model
include MotionModel::ArrayModelAdapter
columns :name => :string,
:long_name => :string,
:due_date => :date
end
class MyCoolController
def some_method
@task = Task.create :name => 'walk the dog',
:long_name => 'get plenty of exercise. pick up the poop',
:due_date => '2012-09-15'
end
end
Side note: The original documentation on this used description
for the column that is now long_name
. It turns out Apple reserves description
so MotionModel saves you the trouble of finding that particular bug by not allowing you to use it for a column name.
Models support default values, so if you specify your model like this, you get defaults:
class Task
include MotionModel::Model
include MotionModel::ArrayModelAdapter
columns :name => :string,
:due_date => {:type => :date, :default => '2012-09-15'}
end
A note on defaults, you can specify a proc, block or symbol for your default if you want to get fancy. The most obvious use case for this is that Ruby will optimize the assignment of an array so that a default of []
always points to the same object. Not exactly what is intended. Wrapping this in a proc causes a new array to be created. Here's an example:
class Foo
include MotionModel::Model
include MotionModel::ArrayModelAdapter
columns subject: { type: :array, default: ->{ [] } }
end
This is not constrained to initializing arrays. You can initialize pretty much anything using a proc or block. If you are specifying a block, make sure to use begin/end instead of do/end because it makes Ruby happy.
Here's a different example:
class Timely
include MotionModel::Model
include MotionModel::ArrayModelAdapter
columns ended_run_at: { type: :time, default: ->{ Time.now } }
end
Note that this uses the "stubby proc" syntax. That is pretty much equivalent to:
columns ended_run_at: { type: :time, default: lambda { Time.now } }
for the previous example.
If you want to use a block, use the begin/end syntax:
columns ended_run_at: { type: :time, default:
begin
Time.now
end
}
Finally, you can have the default call some class method as follows:
class Timely
include MotionModel::Model
include MotionModel::ArrayModelAdapter
columns unique_thingie: { type: :integer, default: :randomize }
def self.randomize
rand 1_000_000
end
end
You can also include the Validatable
module to get field validation. For example:
class Task
include MotionModel::Model
include MotionModel::ArrayModelAdapter
include MotionModel::Validatable
columns :name => :string,
:long_name => :string,
:due_date => :date
validates :name, :presence => true
end
class MyCoolController
def some_method
@task = Task.new :name => 'walk the dog',
:long_name => 'get plenty of exercise. pick up the poop',
:due_date => '2012-09-15'
show_scary_warning unless @task.valid?
end
end
Important Note: Type casting occurs at initialization and on assignment. That means
If you have a field type int
, it will be changed from a string to an integer when you
initialize the object of your class type or when you assign to the integer field in your class.
a_task = Task.create(:name => 'joe-bob', :due_date => '2012-09-15') # due_date is cast to NSDate
a_task.due_date = '2012-09-19' # due_date is cast to NSDate
Model Data Types
Currently supported types are:
:string
:text
-
:boolean
,:bool
-
:int
,:integer
-
:float
,:double
:date
:array
You are really not encouraged to stuff big things in your models, which is why a blob type is not implemented. The smaller your data, the less overhead involved in saving/loading.
Special Columns
The two column names, created_at
and updated_at
will be adjusted automatically if they
are declared. They need to be of type :date
. The created_at
column will be set only when
the object is created (i.e., on first save). The updated_at
column will change every time
the object is saved.
Validation Methods
To use validations in your model, declare your model as follows:
class MyValidatableModel
include MotionModel::Model
include MotionModel::ArrayModelAdapter
include MotionModel::Validatable
# All other model-y stuff here
end
Here are some sample validations:
validate :field_name, :presence => true
validate :field_name, :length => 5..8 # specify a range
validate :field_name, :email => true
validate :field_name, :format => /\A\d?\d-\d?\d-\d\d\Z/ # expected string format would be like '12-12-12'
The framework is sufficiently flexible that you can add in custom validators like so:
module MotionModel
module Validatable
def validate_foo(field, value, setting)
# do whatever you need to make sure that the value
# denoted by *value* for the field corresponds to
# whatever is passed in setting.
end
end
end
validate :my_field, :foo => 42
In the above example, your new validate_foo
method will get the arguments
pretty much as you expect. The value of the
last hash is passed intact via the settings
argument.
You are responsible for adding an error message using:
add_message(field, "incorrect value foo #{the_foo} -- should be something else.")
You must return true
from your validator if the value passes validation otherwise false
.
An important note about save
once you include Validatable
, you have two flavors
of save:
Method | Meaning |
---|---|
save(options) |
Just saves the data if it is valid (passes validations) or if you have specified :validate => false for options
|
save! |
Saves the data if it is valid, otherwise raises a MotionModel::Validatable::RecordInvalid exception |
Model Instances and Unique IDs
It is assumed that models can be created from an external source (JSON from a Web
application or NSCoder
from the device) or simply be a stand-alone data store.
To identify rows properly, the model tracks a special field called :id
. If it's
already present, it's left alone. If it's missing, then it is created for you.
Each row id is guaranteed to be unique, so you can use this when communicating
with a server or syncing your rowset to a UITableView.
Using MotionModel
-
Your data in a model is accessed in a very ActiveRecord (or Railsey) way. This should make transitioning from Rails or any ORM that follows the ActiveRecord pattern pretty easy. Some of the finder syntactic sugar is similar to that of Sequel or DataMapper.
-
Finders are implemented using chaining. Here is an examples:
@tasks = Task.where(:assigned_to).eq('bob').and(:location).contains('seattle') @tasks.all.each { |task| do_something_with(task) }
You can use a block with find:
@tasks = Task.find{|task| task.name =~ /dog/i && task.assigned_to == 'Bob'}
Note that finders always return a proxy (
FinderQuery
). You must usefirst
,last
, orall
to get useful results.@tasks = Task.where(:owner).eq('jim') # => A FinderQuery. @tasks.all # => An array of matching results. @tasks.first # => The first result
You can perform ordering using either a field name or block syntax. Here's an example:
@tasks = Task.order(:name).all # Get tasks ordered ascending by :name @tasks = Task.order{|one, two| two.details <=> one.details}.all # Get tasks ordered descending by :details
You can implement some aggregate functions using map/reduce:
@task.all.map{|task| task.number_of_items}.reduce(:+) # implements sum @task.all.map{|task| task.number_of_items}.reduce(:+) / @task.count #implements average
-
-
Serialization is part of MotionModel. So, in your
AppDelegate
you might do something like this:@tasks = Task.deserialize_from_file('tasks.dat')
and of course on the "save" side:
Task.serialize_to_file('tasks.dat')
After the first serialize or deserialize, your model will remember the file name so you can call these methods without the filename argument.
Implementation note: that the this serialization of any arbitrarily complex set of relations is automatically handled by
NSCoder
provided you conform to the coding protocol (which MotionModel does). When you declare your columns,MotionModel
understands how to serialize your data so you need take no specific action.Persistence will serialize only one model at a time and not your entire data store. This is to allow you to decide what data is serialized when.
-
Relations
class Task include MotionModel::Model include MotionModel::ArrayModelAdapter columns :name => :string has_many :assignees end class Assignee include MotionModel::Model include MotionModel::ArrayModelAdapter columns :assignee_name => :string belongs_to :task end # Create a task, then create an assignee as a # related object on that task a_task = Task.create(:name => "Walk the Dog") a_task.assignees.create(:assignee_name => "Howard") # See? It works. a_task.assignees.assignee_name # => "Howard" Task.first.assignees.assignee_name # => "Howard" # Create another assignee but don't save # Add to assignees collection. Both objects # are saved. another_assignee = Assignee.new(:name => "Douglas") a_task.assignees << another_assignee # adds to relation and saves both objects # The count of assignees accurately reflects current state a_task.assignees.count # => 2 # And backreference access through belongs_to works. Assignee.first.task.name # => "Walk the Dog"
-
There are four ways to delete objects from your data store:
-
object.delete #
just deletes the object and ignores all relations -
object.destroy #
deletes the object and honors any cascading declarations -
Class.delete_all #
just deletes all objects of this class and ignores all relations -
Class.destroy_all #
deletes all objects of this class and honors any cascading declarations
The key to how the destroy
variants work in how the relation is declared. You can declare:
class Task
include MotionModel::Model
include MotionModel::ArrayModelAdapter
columns :name => :string
has_many :assignees
end
and assignees
will not be considered when deleting Task
s. However, by modifying the has_many
,
has_many :assignees, :dependent => :destroy
When you destroy
an object, all of the objects related to it, and only those related
to that object, are also destroyed. So, if you call task.destroy
and there are 5
assignees
related to that task, they will also be destroyed. Any other assignees
are left untouched.
You can also specify:
has_many :assignees, :dependent => :delete
The difference here is that the cascade stops as the assignees
are deleted so anything
related to the assignees remains intact.
Note: This syntax is modeled on the Rails :dependent => :destroy
options in ActiveRecord
.
Hook Methods
During a save or delete operation, hook methods are called to allow you a chance to modify the object at that point. These hook methods are:
before_save(sender)
after_save(sender)
before_delete(sender)
after_delete(sender)
MotionModel makes no distinction between destroy and delete when calling hook methods, as it only calls them when the actual object is deleted. In a destroy operation, during the cascading delete, the delete hooks are called (again) at the point of object deletion.
Note that the method signatures may be different from previous implementations. No longer can you
declare a hook method without the sender
argument.
Finally, contrasting hook methods with notifications, the hook methods before_save
and after_save
are called before the save operation begins and after it completes. However, the notification (covered
below) is only issued after the save operation. However... the notification understands whether the
operation was a save or update. Rule of thumb: If you want to catch an operation before it begins,
use the hook. If you just want to know about it when it happens, use the notification.
The delete hooks happen around the delete operation and, again, allow you the option to mess with the
object before you allow the process to go forward (pretty much, the before_delete
hook does this).
IMPORTANT: Returning false in a before hook stops the rest of the operation. So, for example, you could prevent the deletion of the last admin by writing something like this:
def before_delete(sender)
return false if sender.find(:privilege_level).eq('admin').count < 2
end
Transactions and Undo/Cancel
MotionModel is not ActiveRecord. MotionModel is not a database-backed mapper. The bottom line is that when you change a field in a model, even if you don't save it, you are partying on the central object store. In part, this is because Ruby copies objects by reference, so when you do a find, you get a reference to the object in the central object store.
The upshot of this is that MotionModel can be wicked fast because it isn't moving much more than pointers around in memory when you do assignments. However, it can be surprising if you are used to a database-backed mapper.
You could easily build an app and never run across a problem with this, but in the case where you present a dialog with a cancel button, you will need a way to back out. Here's how:
# in your form presentation view...
include MotionModel::Model::Transactions
person.transaction do
result = do_something_that_changes_person
person.rollback unless result
end
def do_something_that_changes_person
# stuff
return it_worked
end
You can have nested transactions and each has its own context so you don't wind up rolling back to the wrong state. However, everything that you wrap in a transaction must be wrapped in the transaction
block. That means you need to have some outer calling method that can wrap a series of delegated changes. Explained differently, you can't start a transaction, have a delegate method handle a cancel button click and roll back the transaction from inside the delegate method. When the block is exited, the transaction context is removed.
Notifications
Notifications are issued on object save, update, and delete. They work like this:
def viewDidAppear(animated)
super
# other stuff here to set up your view
NSNotificationCenter.defaultCenter.addObserver(self, selector:'dataDidChange:',
name:'MotionModelDataDidChangeNotification',
object:nil)
end
def viewWillDisappear(animated)
super
NSNotificationCenter.defaultCenter.removeObserver self
end
# ... more stuff ...
def dataDidChange(notification)
# code to update or refresh your view based on the object passed back
# and the userInfo. userInfo keys are:
# action
# 'add'
# 'update'
# 'delete'
end
In your dataDidChange
notification handler, you can respond to the MotionModelDataDidChangeNotification
notification any way you like,
but in the instance of a tableView, you might want to use the id of the object passed back to locate
the correct row in the table and act upon it instead of doing a wholesale reloadData
.
Note that if you do a delete_all, no notifications are issued because there is no single object on which to report. You pretty much know what you need to do: Refresh your view.
This is implemented as a notification and not a delegate so you can dispatch something
like a remote synch operation but still be confident you will be updating the UI only on the main thread.
MotionModel does not currently send notification messages that differentiate by class, so if your
UI presents Task
s and you get a notification that an Assignee
has changed:
class Task
include MotionModel::Model
include MotionModel::ArrayModelAdapter
has_many :assignees
# etc
end
class Assignee
include MotionModel::Model
include MotionModel::ArrayModelAdapter
belongs_to :task
# etc
end
# ...
task = Task.create :name => 'Walk the dog' # Triggers notification with a task object
task.assignees.create :name => 'Adam' # Triggers notification with an assignee object
# ...
# We set up observers for `MotionModelDataDidChangeNotification` someplace and:
def dataDidChange(notification)
if notification.object is_a?(Task)
# Update our UI
else
# This notification is not for us because
# We don't display anything other than tasks
end
The above example implies you are only presenting, say, a list of tasks in the current view. If, however, you are presenting a list of tasks along with their assignees and the assignees could change as a result of a background sync, then your code could and should recognize the change to assignee objects.
Core Extensions
- String#humanize
- String#titleize
- String#empty?
- String#singularize
- String#pluralize
- NilClass#empty?
- Array#empty?
- Hash#empty?
- Symbol#titleize
Also in the extensions is a Debug
class to log stuff to the console.
It uses NSLog so you will have a separate copy in your application log.
This may be preferable to puts
just because it's easier to spot in
your code and it gives you the exact level and file/line number of the
info/warning/error in your console output:
- Debug.info(message)
- Debug.warning(message)
- Debug.error(message)
- Debug.silence / Debug.resume to turn on and off logging
- Debug.colorize (true/false) for pretty console display
Finally, there is an inflector singleton class based around the one Rails has implemented. You don't need to dig around in this class too much, as its core functionality is exposed through two methods:
String#singularize String#pluralize
These work, with the caveats that 1) The inflector is English-language based; 2) Irregular nouns are not handled; 3) Singularizing a singular or pluralizing a plural makes for good cocktail-party stuff, but in code, it mangles things pretty badly.
You may want to get into customizing your inflections using:
- Inflector.inflections.singular(rule, replacement)
- Inflector.inflections.plural(rule, replacement)
- Inflector.inflections.irregular(rule, replacement)
These allow you to add to the list of rules the inflector uses when processing singularize and pluralize. For each singular rule, you will probably want to add a plural one. Note that order matters for rules, so if your inflection is getting chewed up in one of the baked-in inflections, you may have to use Inflector.inflections.reset to empty them all out and build your own.
Of particular note is Inflector.inflections.irregular. This is for words that defy regular rules such as 'man' => 'men' or 'person' => 'people'. Again, a reversing rule is required for both singularize and pluralize to work properly.
Serialization
The ArrayModelAdapter
does not, by default perform any serialization. That's
because how often which parts of your object graph are serialized can affect
application performance. However, you will want to use the serialization
features. Here they are:
YourModel.deserialize_from_file(file_name = nil)
YourModel.serialize_to_file(file_name = nil)
What happens here? When you want to save a model, you call serialize_to_file
.
Each model's data must be saved to a different file so name them accordingly.
If you have a model that contains related model objects, you may want to save
both models. But you have complete say over that and the responsibility to
handle it.
When you call deserialize_from_file
, your model is populated from the file
previously serialized.
Formotion Support
Background
MotionModel has support for the cool Formotion gem.
Note that the Formotion project on GitHub appears to be way ahead of the gem on Rubygems, so you
might want to build it yourself if you want the latest gee-whiz features (like :picker_type
, as
I've shown in the first example).
High-Level View
class Event
include MotionModel::Model
include MotionModel::Formotion # <== Formotion support
columns :name => :string,
:date => {:type => :date, :formotion => {:picker_type => :date_time}},
:location => :string
end
This declares the class. The only difference is that you include MotionModel::Formotion
.
If you want to pass additional information on to Formotion, simply include it in the
:formotion
hash as shown above.
Note: the
:formation
stuff in thecolumns
specification is something I'm still thinking about. Read on to find out about the two alternate syntaxes forto_formotion
.
Details About to_formotion
There are two alternate syntaxes for calling this. The initial, or "legacy" syntax is as follows:
to_formotion(form_title, expose_auto_date_fields, first_section_title)
In the legacy syntax, all arguments are optional and sensible defaults are chosen. However, when you want to tune how your form is presented, the syntax gets a bit burdensome. The alternate syntax is:
to_formotion(options)
The options hash looks a lot like a Formotion hash might, except without the data. Here is an example:
{title: 'A very fine form',
sections: [
{title: 'First Section',
fields: [:name, :gender]
},
{title: 'Second Section',
fields: [:address, :city, :state]
}
]}
Note that in this syntax, you can specify a button in the fields array:
{title: 'A very fine form',
sections: [
{title: 'First Section',
fields: [:name, :gender]
},
{title: 'Second Section',
fields: [:address, :city, :state, {type: :submit, title: 'Ok'}]
}
]}
This specifies exactly what titles and fields appear where and in what order.
Finally, you can specify a button:
{title: 'A very fine form',
sections: [
{title: 'First Section',
fields: [:name, :gender]
},
{title: 'Second Section',
fields: [:address, :city, :state, {type: :submit, title: 'Ok'}],
{type: :button, title: 'add now!!!'}
}
]}
How Values Are Produced for Formotion
MotionModel has sensible defaults for each type supported, so any field of :date
type will default to a date picker in the Formotion form. However, if you want it
to be a string for some reason, just specify this in columns
:
:date => {:type => :date, :formotion => {:type => :string}}
To initialize a form from a model in your controller:
@form = Formotion::Form.new(@event.to_formotion('event details')) # Legacy syntax
@form_controller = MyFormController.alloc.initWithForm(@form)
The magic is in: MotionModel::Model#to_formotion(form_title)
.
The auto_date fields created_at
and updated_at
are not sent to
Formotion by default. If you want them sent to Formotion, set the
second argument to true. E.g.,
@form = Formotion::Form.new(@event.to_formotion('event details', true))
On the flip side you do something like this in your Formotion submit handler:
@event.from_formotion!(data)
This performs sets on each field. You'll, of course, want to check your validations before dismissing the form.
Moreover, Formotion support allows you to split one model fields in sections. By default all fields are put in a single untitled section. Here is a complete example:
class Event
include MotionModel::Model
include MotionModel::Formotion # <== Formotion support
columns :name => :string,
:date => {:type => :date, :formotion => {:picker_type => :date_time}},
:location => {:type => :string, :formotion => {:section => :address}}
has_formotion_sections :address => {:title => "Address"}
end
This will create a form with the name
and date
fields presented first, then a
section titled 'Address' will contain the location
field.
If you want to add a title to the first section, provide a :first_section_title
argument to to_formotion
:
@form = Formotion::Form.new(@event.to_formotion('event details', true, 'First Section Title'))
Problems/Comments
Please raise an issue on GitHub if you find something that doesn't work, some syntax that smells, etc.
If you want to stay on the bleeding edge, clone yourself a copy (or better yet, fork one).
Then be sure references to motion_model are commented out or removed from your Gemfile and/or Rakefile and put this in your Rakefile:
require "~/github/local/MotionModel/lib/motion_model.rb"
The ~/github/local
is where I cloned it, but you can put it anyplace. Next, make
sure you are following the project on GitHub so you know when there are changes.
Submissions/Patches/Bug Reports
For a submission, do this:
- Fork it
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'Add some feature')
- Push to the branch (git push origin my-new-feature)
- Create new Pull Request
For a bug report, the best bet is follow the above steps, but for #2 and 4, use the issue number in the branch. Once you have created the pull request, reference it in the issue.