motion-kit-events 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1dff0c162d7aa79745f3688409745e9a096b5af0
+  data.tar.gz: 9e8bc6302c39eb7c3fa2ee82a2f2e3c42221fda7
+SHA512:
+  metadata.gz: 4bfcebe914349985e9d232779761fa8d579058daf73f76d1912a54d6ee1e5a8174524cc9d6bea87dd3a90c6f1ffb2c679530b5d86d63dc45d7cd67b1be32bfda
+  data.tar.gz: 8ce463671100d3867c42658b3f10def5192a461eb6df7cb9e3873ffcd863273b157eee5597ab4d741b76ff56b6e811e054b5756cca37102406a7e370fe0b6ee7

data/README.md

@@ -0,0 +1,119 @@
+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.
+
+## LoginController
+
+An example of a UIViewController using MotionKit::Events:
+
+```ruby
+class LoginController < UIViewController
+
+  def loadView
+    @layout = LoginLayout.new
+    self.view = @layout.view
+
+    @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
+  end
+
+  def storage
+    @storage ||= LoginStorage.new
+  end
+
+  def handle_login(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
+`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
+
+  def layout
+    add UITextField, :username_field do
+      delegate self
+    end
+
+    add UITextField, :password_field do
+      delegate self
+    end
+
+    add UIButton, :login_button do
+      on :touch do
+        trigger_login
+      end
+    end
+  end
+
+  def trigger_login
+    # send the username and password to our controller
+    trigger :login, get(:username_field).text.to_s, get(:password_field).text.to_s
+  end
+
+  def textFieldShouldReturn(field)
+    if field == get(:password_field)
+      trigger_login
+    else
+      get(:password_field).becomeFirstResponder
+    end
+  end
+
+end
+```
+
+The sample app (most of the code is in [app/ios/login/][login]) includes a working
+version of this example.
+
+[login]: https://github.com/rubymotion/motion-kit-events/tree/master/app/ios/login/
+
+###### Note
+
+The example and specs all require SugarCube to run; this is just because I
+wanted to have the specs make sure that the `on` method (used in so many gems)
+behaves the way you would expect it to.

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

@@ -0,0 +1,45 @@
+# @requires MotionKit::BaseLayout
+module MotionKit
+  class BaseLayout
+
+    def motion_kit_event_handlers
+      @motion_kit_event_handlers ||= {}
+    end
+
+    def on(*args, &handler)
+      if @context || @assign_root
+        apply_with_target(:on, *args, &handler)
+      else
+        event = args.first
+        unless event
+          raise ArgumentError.new('`event` is a required argument to Layout#on')
+        end
+        motion_kit_event_handlers[event] ||= []
+        motion_kit_event_handlers[event] << handler.weak!
+
+        self
+      end
+    end
+
+    def trigger(*args, &handler)
+      if @context
+        apply(:trigger, *args, &handler)
+      else
+        event = args.first
+        unless event
+          raise ArgumentError.new('`event` is a required argument to Layout#on')
+        end
+
+        if motion_kit_event_handlers[event]
+          motion_kit_event_handlers[event].each do |handler|
+            handler.call(args[1..-1])
+          end
+        end
+
+        self
+      end
+    end
+
+  end
+
+end

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

@@ -0,0 +1,5 @@
+module MotionKit
+  module Events
+    VERSION = '0.1.0'
+  end
+end

data/lib/motion-kit-events.rb

@@ -0,0 +1,23 @@
+unless defined?(Motion::Project::Config)
+  raise "The MotionKit::Events gem must be required within a RubyMotion project Rakefile."
+end
+
+
+require 'motion-kit'
+require 'dbt'
+
+
+Motion::Project::App.setup do |app|
+  lib = File.join(File.dirname(__FILE__), 'motion-kit-events')
+
+  # scans app.files until it finds app/ (the default)
+  # if found, it inserts just before those files, otherwise it will insert to
+  # the end of the list
+  insert_point = app.files.find_index { |file| file =~ /^(?:\.\/)?app\// } || 0
+
+  Dir.glob(File.join(lib, '**/*.rb')).reverse.each do |file|
+    app.files.insert(insert_point, file)
+  end
+
+  DBT.analyze(app)
+end

data/spec/ios/events_spec.rb

@@ -0,0 +1,16 @@
+describe 'MotionKit::Events' do
+  tests EventsController
+
+  it 'should respond to the layout trigger' do
+    controller.success.should.not == true
+    controller.layout.trigger(:test)
+    controller.success.should == true
+  end
+
+  it 'should respond to the test button' do
+    controller.success.should.not == true
+    controller.test_button.trigger(:touch)
+    controller.success.should == true
+  end
+
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: motion-kit-events
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Colin T.A. Gray
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-05-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: motion-kit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: dbt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  Use +on+ and +trigger+ to send generic events from the layout to the controller.
+email:
+- colinta@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/motion-kit-events/layout.rb
+- lib/motion-kit-events/version.rb
+- lib/motion-kit-events.rb
+- README.md
+- spec/ios/events_spec.rb
+homepage: https://github.com/rubymotion/motion-kit-events
+licenses:
+- BSD
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: Adds simple event methods to MotionKit::Layout classes.
+test_files:
+- spec/ios/events_spec.rb