motion_model 0.3.2 → 0.3.3

data/CHANGELOG

@@ -1,3 +1,11 @@
+2012-01-09: Added automatic date/timestamp support for created_at and updated_at columns
+            Added Hash extension except, Array introspection methods has_hash_key? and
+            has_hash_value?
+            Commit of Formotion module including optional inclusion/suppression of the
+            auto-date fields
+            Specs
+
+
 2012-12-30: Added Formotion module. This allows for tighter integration with Formotion
             Changed options for columns such that any arbitrary values can be inserted
             allowing for future expansion.

data/README.md

@@ -3,32 +3,32 @@
 MotionModel -- Simple Model, Validation, and Input Mixins for RubyMotion
 ================
 
-MotionModel is for cases where Core Data is too heavy to lift but you are
-still intending to work with your data.
+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.
 
-MotionModel is a bunch of "I don't ever want to have to write that code
-again if I can help it" things extracted into modules. The four modules
-are:
-
-- ext: Core Extensions that provide a few Rails-like niceties. Nothing
-  new here, moving on...
-  
-- model.rb: You can read about it in "What Model Can Do" but it's a
-  mixin that provides you accessible attributes, row indexing,
-  serialization for persistence, and some other niceties like row
-  counting.
-  
-- validatable.rb: Provides a basic validation framework for any
-  arbitrary class. You can also create custom validations to suit
-  your app's unique needs.
-  
-- input_helpers: Hooking a collection up to a data form, populating
-  the form, and retrieving the data afterwards can be a bunch of code.
-  Not something I'd like to write more often that I have to.
+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 can read about it in "What Model Can Do" but it's a mixin that provides you accessible attributes, row indexing, serialization for persistence, and some other niceties like row counting.
+**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
 
 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][]
+* [What Model Can Do][]
+* [Model Data Types][]
+* [Validation Methods][]
+* [Model Instances and Unique IDs][]
+* [Using MotionModel][]
+* [Notifications][]
+* [Core Extensions][]
+* [Formotion Support][]
+* [Problems/Comments][]
+* [pSubmissions/Patches][]
+
 Getting Going
 ================
 
@@ -125,6 +125,9 @@ a_task = Task.create(:name => 'joe-bob', :due_date => '2012-09-15')     # due_da
 a_task.due_date = '2012-09-19'    # due_date is cast to NSDate
 ```
 
+Model Data Types
+-----------
+
 Currently supported types are:
 
 * `:string`
@@ -138,9 +141,29 @@ Currently supported types are:
 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.
 
-What Validation Methods Exist
+### 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:
+
+```ruby
+class MyValidatableModel
+  include MotionModel::Model
+  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
@@ -166,11 +189,17 @@ 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`.
+
 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. 
+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
@@ -300,7 +329,7 @@ The key to how the `destroy` variants work in how the relation is declared. You
 and `assignees` will *not be considered* when deleting `Task`s. However, by modifying the `has_many`,
 
 ```ruby
-    has_many    :assignees, :dependent => :destroy
+has_many    :assignees, :dependent => :destroy
 ```
 
 When you `destroy` an object, all of the objects related to it, and only those related
@@ -311,7 +340,7 @@ are left untouched.
 You can also specify:
 
 ```ruby
-    has_many    :assignees, :dependent => :delete
+has_many    :assignees, :dependent => :delete
 ```
 
 The difference here is that the cascade stops as the `assignees` are deleted so anything
@@ -322,34 +351,36 @@ Note: This syntax is modeled on the Rails `:dependent => :destroy` options in `A
 Notifications
 -------------
 
-  Notifications are issued on object save, update, and delete. They work like this:
-  
-  ```ruby
-  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
+Notifications are issued on object save, update, and delete. They work like this:
   
-  # ... more stuff ...
+```ruby
+def viewDidAppear(animated)
+  super
+  # other stuff here to set up your view
   
-  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
-  ```
+  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,
+  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`.
   
@@ -361,35 +392,35 @@ Notifications
   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:
   
-  ```ruby
-  class Task
-    include MotionModel::Model
-    has_many :assignees
-    # etc
-  end
-  
-  class Assignee
-    include MotionModel::Model
-    belongs_to :task
-    # etc
-  end
+```ruby
+class Task
+  include MotionModel::Model
+  has_many :assignees
+  # 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
-  ```
+class Assignee
+  include MotionModel::Model
+  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
@@ -397,6 +428,7 @@ Notifications
   should recognize the change to assignee objects.
   
 Core Extensions
+----------------
 
   - String#humanize
   - String#titleize
@@ -450,7 +482,7 @@ Core Extensions
   Again, a reversing rule is required for both singularize and 
   pluralize to work properly.
 
-Experimental: Formotion Support
+Formotion Support
 ----------------------
 
 MotionModel now has support for the cool [Formotion gem](https://github.com/clayallsopp/formotion).
@@ -492,7 +524,15 @@ To initialize a form from a model in your controller:
 
 The magic is in: `MotionModel::Model#to_formotion(section_header)`.
 
-and on the flip side you do something like this in your submit handler:
+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.,
+
+```ruby
+@form = Formotion::Form.new(@event.to_formotion('event details', true))
+```
+
+On the flip side you do something like this in your Formotion submit handler:
 
 ```ruby
 @event.from_formotion!(data)

data/lib/motion_model/ext.rb

@@ -158,12 +158,38 @@ class Array
   def empty?
     self.length < 1
   end
+
+  # If any item in the array has the key == `key` true, otherwise false.
+  # Of good use when writing specs.
+  def has_hash_key?(key)
+    self.each do |entity|
+      return true if entity.has_key? key
+    end
+    return false
+  end
+
+  # If any item in the array has the value == `key` true, otherwise false
+  # Of good use when writing specs.
+  def has_hash_value?(key)
+    self.each do |entity|
+      entity.each_pair{|hash_key, value| return true if value == key}
+    end
+    return false
+  end
 end
 
+
+
 class Hash
   def empty?
     self.length < 1
   end
+
+  # Returns the contents of the hash, with the exception
+  # of the keys specified in the keys array.
+  def except(*keys)
+    self.dup.reject{|k, v| keys.include?(k)}
+  end
 end
 
 class Symbol

data/lib/motion_model/model/formotion.rb

@@ -0,0 +1,55 @@
+module MotionModel
+  module Formotion
+    FORMOTION_MAP = {
+      :string   => :string,
+      :date     => :date,
+      :int      => :number,
+      :integer  => :number,
+      :float    => :number,
+      :double   => :number,
+      :bool     => :check,
+      :boolean  => :check,
+      :text     => :text
+    }
+
+    def returnable_columns
+      cols = columns.select do |column|
+        exposed = @expose_auto_date_fields ? true : ![:created_at, :updated_at].include?(column)
+        column != :id &&                # don't ship back id by default
+        !relation_column?(column) &&    # don't ship back relations -- formotion doesn't get them
+        exposed                         # don't expose auto_date fields unless specified
+      end
+      cols
+    end
+
+    def to_formotion(section_title = nil, expose_auto_date_fields = false)
+      @expose_auto_date_fields = expose_auto_date_fields
+      form = {
+        sections: [{}]
+      }
+
+      section = form[:sections].first
+      section[:title] ||= section_title
+      section[:rows] = []
+
+      returnable_columns.each do |column|
+        value = self.send(column)
+        value = value.to_f if type(column) == :date && value
+        h = {:key         => column.to_sym,
+             :title       => column.to_s.humanize,
+             :type        => FORMOTION_MAP[type(column)],
+             :placeholder => column.to_s.humanize,
+             :value       => value
+             }
+        options = column_named(column).options[:formotion]
+        h.merge!(options) if options
+        section[:rows].push h
+      end
+      form
+    end
+    
+    def from_formotion!(data)
+      self.returnable_columns.each{|column| self.send("#{column}=", data[column])}
+    end
+  end
+end

data/lib/motion_model/model/model.rb

@@ -402,8 +402,10 @@ module MotionModel
 
         # Existing object implies update in place
         action = 'add'
+        set_auto_date_field 'created_at'
         if obj = collection.find{|o| o.id == @data[:id]}
           obj = self
+          set_auto_date_field 'updated_at'
           action = 'update'
         else
           collection << self
@@ -412,8 +414,12 @@ module MotionModel
       end
     end
 
-    # Deletes the current object. The object can still be used.
+    # Set created_at and updated_at fields
+    def set_auto_date_field(field_name)
+      self.send("#{field_name}=", Time.now) if self.respond_to? field_name
+    end
 
+    # Deletes the current object. The object can still be used.
     def call_hook(hook_name, postfix)
       hook = "#{hook_name}_#{postfix}"
       self.send(hook, self) if respond_to? hook.to_sym

data/lib/motion_model/version.rb

@@ -1,3 +1,3 @@
 module MotionModel
-  VERSION = "0.3.2"
+  VERSION = "0.3.3"
 end

data/spec/date_spec.rb

@@ -10,4 +10,32 @@ describe "time conversions" do
       strftime("%m-%d-%Y | %I:%M %p").
       should == "03-18-2012 | 07:00 PM"
   end
+
+  it "Sets created_at when an item is created" do
+    class Creatable
+      include MotionModel::Model
+      columns :name => :string,
+              :created_at => :date
+    end
+
+    c = Creatable.new(:name => 'test')
+    lambda{c.save}.should.change{c.created_at}
+  end
+
+    it "Sets updated_at when an item is created" do
+    class Updateable
+      include MotionModel::Model
+      columns :name => :string,
+              :created_at => :date,
+              :updated_at => :date
+    end
+
+    c = Updateable.create(:name => 'test')
+    c.name = 'test 1'
+    lambda{c.save}.should.not.change{c.created_at}
+    d = Updateable.create(:name => 'test')
+    d.name = 'test 2'
+    lambda{d.save}.should.change{d.updated_at}
+  end
+
 end

data/spec/formotion_spec.rb

@@ -4,7 +4,18 @@ class ModelWithOptions
 
   columns :name => :string,
           :date => {:type => :date, :formotion => {:picker_type => :date_time}},
-          :location => :string
+          :location => :string,
+          :created_at => :date,
+          :updated_at => :date
+
+  has_many :related_models
+end
+
+class RelatedModel
+  include MotionModel::Model
+
+  columns :name => :string
+  belongs_to :model_with_options
 end
 
 describe "formotion" do
@@ -30,4 +41,18 @@ describe "formotion" do
     @subject.date.strftime("%Y-%d-%d %H:%M:%S").should == '2013-03-03 12:00:00'
     @subject.location.should == "Q's Lab"
   end
+
+  it "does not include auto date fields in the hash by default" do
+    @subject.to_formotion[:sections].first[:rows].has_hash_key?(:created_at).should == false
+    @subject.to_formotion[:sections].first[:rows].has_hash_key?(:updated_at).should == false
+  end
+
+  it "can optionally include auto date fields in the hash" do
+    result = @subject.to_formotion(nil, true)[:sections].first[:rows].has_hash_value?(:created_at).should == true
+    result = @subject.to_formotion(nil, true)[:sections].first[:rows].has_hash_value?(:updated_at).should == true
+  end
+
+  it "does not include related columns in the collection" do
+    result = @subject.to_formotion[:sections].first[:rows].has_hash_value?(:related_models).should == false
+  end
 end

data/spec/validation_spec.rb

@@ -1,9 +1,3 @@
-class Hash
-  def except(keys)
-    self.dup.reject{|k, v| keys.include?(k)}
-  end
-end
-
 class ValidatableTask
   include MotionModel::Model
   include MotionModel::Validatable

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: motion_model
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-03 00:00:00.000000000 Z
+date: 2013-01-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bubble-wrap
@@ -45,6 +45,7 @@ files:
 - lib/motion_model/input_helpers.rb
 - lib/motion_model/model/column.rb
 - lib/motion_model/model/finder_query.rb
+- lib/motion_model/model/formotion.rb
 - lib/motion_model/model/model.rb
 - lib/motion_model/model/model_casts.rb
 - lib/motion_model/model/persistence.rb