motion-kit-events 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7d272150b20b160dfe25edeab5f893ef678a1a2a
-  data.tar.gz: 6d61019bd8534848a4eca225027ef697532678f8
+  metadata.gz: 13f62c76304cbae64f1916709ac22a1ce3555c8b
+  data.tar.gz: 0b8af2a3e3749e6f0186f2d3aef818d785e9ce4a
 SHA512:
-  metadata.gz: b878d15fec70347b73b7590945db80ee9ba8a538f1c086dfcefee0aeafe6430241e005400779d06dce3671fb5509f72ac7205a60505723267f0146ceeb0a9bf6
-  data.tar.gz: c5880fa77766864905f33fcaf890bdbbd5e91041432576581ea115a3a49e98b2052ab93395b92df416df4ab10269ba2f9f65839a7a882dd73d49766d0ed094ca
+  metadata.gz: 5dcc6e70e96079247e440665f2dd565a9789d75dc93adbb7569e21177d160ac577db7aaf4e9558a4964ddcf143865aebd1eb9fd7ac70a68bf2677a1e3a961f6f
+  data.tar.gz: 4ef2b080304f6258bde9f764bec5a145d105870a1fbe3ea71c7a26962e271c8e72080f81d135d221418fc20816950cf8cadcf2f38ed72c6864e8d194105249dd

data/README.md

@@ -2,8 +2,10 @@ MotionKit::Events
 --------
 
 In an effort to encourage even MORE separation of concerns in your Controllers
-and Layouts, the `motion-kit-events` gem provides a very way to emit generic
-events from your layout that you can respond to in your controller.
+and Layouts, the `motion-kit-events` gem provides a way to listen for custom
+events (usually triggered by buttons or other UI events) and respond in your
+controller. This keeps your views from being cluttered with business logic and
+your controllers from being cluttered with view code.
 
 ## LoginController
 
@@ -12,66 +14,39 @@ An example of a UIViewController using MotionKit::Events:
 ```ruby
 class LoginController < UIViewController
 
-  def loadView
-    @layout = LoginLayout.new
-    self.view = @layout.view
+  def viewDidLoad
+    @layout = LoginLayout.new(root: self.view).build
 
-    @layout.on :login do |username, password|
-      @layout.pause_ui
-      # send login info to the API (I would recommend using a separate class
-      # to handle the API conversation, e.g. a LoginStorage class).
-      storage.login(username, password) do |user, errors|
-        handle_login(user, errors)
-      end
-    end
+    @layout.on :login { |username, password| initiate_login(username, password) }
+    @layout.on :forgot_password { show_forgot_password }
+    @layout.on :help { show_help }
   end
 
-  def storage
-    @storage ||= LoginStorage.new
+  def initiate_login(username, password)
+    @layout.pause_ui
+    # send login info to the API
+    API::Client.login(username, password) do |user, errors|
+      handle_login_response(user, errors)
+    end
   end
 
-  def handle_login(user, errors)
+  def handle_login_response(user, errors)
     # ...
     @layout.resume_ui
   end
 
+  # ...
+
 end
 ```
 
-Before we go on to show the `LoginLayout`, consider for a second how *easy* it
-would be to write specs for a controller like this.  We don't need to test the
-UI (that will be done in isolation, using the `LoginLayout`) and our controller
-doesn't directly send any *requests*, so we can assign it (in our specs) a
-`TestLoginLayout` class as the storage, which can imitate the behaviors we are
-interested in.  We should also use a fake layout class in there, too.
-
-TL;DR: we can test just the behavior of the controller.  When it receives a
-`:login` event, it should send a `login` request to its storage, and handle
+Now we can test *just the behavior* of the controller.  When it receives a
+`:login` event, it should send a `login` request to its API and handle
 `user` or `errors`.
 
 
 ## LoginLayout
 
-We send the `:login` event along with the username and password when the user
-presses the login button or presses "Return" from the password field.  This is
-all code that would normally be in the UIViewController.  The tight coupling of
-the UIViewController and the UI is very common in iOS apps, but there is much to
-be gained be decoupling these roles.  The Controller can focus on the *movement*
-of the user.
-
-The user starts out in a "logging in" state.  Until they submit credentials, the
-controller need not be interested in what the UI is doing to accomodate this
-procedure.  It just cares about when the user is *done*, and it pauses the UI.
-
-When the login attempt is complete, the controller tells the UI what state to go
-in next, either resuming the UI if an error occurred, or just dimissing the
-controller and passing along the successful login info.
-
-If you look at the code provided by MotionKit::Events you'll be happy to see
-that it is a *tiny* little gem.  But using it to decouple your UI from your
-controller can provide a huge long term benefit in terms of keeping your code
-maintainable!
-
 ```ruby
 class LoginLayout < MK::Layout
 
@@ -85,7 +60,7 @@ class LoginLayout < MK::Layout
     end
 
     add UIButton, :login_button do
-      on :touch do
+      on :touch do # This is Sugarcube
         trigger_login
       end
     end
@@ -107,6 +82,47 @@ class LoginLayout < MK::Layout
 end
 ```
 
+### Testing
+
+The layout can be tested independently of the controller.
+
+```ruby
+describe LoginLayout do
+  before do
+    @subject = LoginLayout.new(root: UIView.new).build
+  end
+
+  it "triggers :login with username/password when the login button is tapped" do
+    @subject.on :login do |user, password|
+      user.should == "example"
+      password.should == "testing123"
+    end
+    @subject.get(:username_field).text = "example"
+    @subject.get(:password_field).text = "testing123"
+    # Simulate tap on button
+    @subject.get(:login_button).target.send(@subject.get(:login_button).action)
+  end
+end
+```
+
+### An explanation: State vs. UI/events
+
+The Controller focuses on the *movement* of the user and the state;
+the Layout handles displaying the UI state and responding to events.
+
+1. The user starts out in a "logging in" state. The controller doesn't care
+how this is represented -- it just cares about when the user is *done*, and
+then it pauses the UI.
+2. When the login attempt is complete, the controller tells the UI what state
+to go in next, either resuming the UI if an error occurred, or just dimissing
+the controller and passing along the successful login info.
+
+MotionKit::Events is a very lightweight gem.  But using it to decouple your UI
+from your controller can provide a huge long term benefit in terms of keeping
+your code maintainable!
+
+### Sample app
+
 The sample app (most of the code is in [app/ios/login/][login]) includes a working
 version of this example.
 

data/lib/motion-kit-events/layout.rb

@@ -21,6 +21,19 @@ module MotionKit
       end
     end
 
+    # Removes *all* event handlers for the specified event
+    def off(*args)
+      if @context || @assign_root
+        apply_with_target(:off, *args)
+      else
+        event = args.first
+        unless event
+          raise ArgumentError.new('`event` is a required argument to Layout#off')
+        end
+        motion_kit_event_handlers[event] = nil
+      end
+    end
+
     def trigger(*args, &handler)
       if @context
         apply(:trigger, *args, &handler)

data/lib/motion-kit-events/version.rb

@@ -1,5 +1,5 @@
 module MotionKit
   module Events
-    VERSION = '0.2.2'
+    VERSION = '0.3.0'
   end
 end

data/spec/ios/events_spec.rb

@@ -13,4 +13,15 @@ describe 'MotionKit::Events' do
     controller.success.should == true
   end
 
+  context 'when the event is removed' do
+
+    it 'should not respond to the test button' do
+      controller.remove_events
+      controller.success.should.not == true
+      controller.test_button.trigger(:touch)
+      controller.success.should.not == true
+    end
+
+  end
+
 end

data/spec/osx/events_spec.rb

@@ -20,4 +20,17 @@ describe 'MotionKit::Events' do
     @controller.success.should == true
   end
 
+  context 'when the event is removed' do
+
+    it 'should not respond to the test button' do
+      @controller.remove_events
+      @controller.success.should.not == true
+      target = @controller.test_button.target
+      action = @controller.test_button.action
+      target.send(action)
+      @controller.success.should.not == true
+    end
+
+  end
+
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: motion-kit-events
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Colin T.A. Gray
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-31 00:00:00.000000000 Z
+date: 2014-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: motion-kit