jskit_rails 2.0.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bcd9fbda4dcb8214247e55f4b44a5cc97e9b5d83
-  data.tar.gz: 645875d832923ce32348206255e18f544df2f486
+  metadata.gz: c91237c5bcdcaf3e07c63d3ea1d8fdf695f3d8cc
+  data.tar.gz: a97db69c109e60868568b1c96f700f1ceddbe860
 SHA512:
-  metadata.gz: 0f0ce3d5b2cf5f534c142a53db851957cd1f7025853106e4266e854d026cb89f993df5097c13b6512601dc901e56cc1d7d697e83ec30c6dbcfac8b7285892d17
-  data.tar.gz: 00f8b09e5ec97a0ebe0f40406be07e20a33969cd4dfd81366586b9aa8eca0d3a0f7d5c1267b2f90c7b0976920b7eceeb010f28d5a55100a4d99ddd6445f29243
+  metadata.gz: cd161b20e817067d9aba06c9237685fe769eb525b6f1291435e1cfbce738cb7f4619fa8d2356ee8de88d1db6af713e4cf50838f57669103db1c4d87c8152717e
+  data.tar.gz: 0db0caed9c124a807fb1409987c6cc03f342d6f53cea306a0fe7100fb2c1cecc3a48ae4846594639a3e05164dd3c5655722090568a2cd955a2c14ac2c7625b61

data/README.md

@@ -18,6 +18,9 @@ Bundle it up:
 bundle install
 ```
 
+Usage
+-----
+
 Add the `jskit` helper to your layout (i.e. `app/views/layouts/application.html.erb`):
 
 ```html
@@ -30,26 +33,169 @@ Add the jskit javascript (i.e. `app/assets/javascripts/application.js`):
 //= require jskit_rails
 ```
 
-That's it, now all controller actions will be triggered on the `JSKit` dispatcher. For example, assume you have a `PagesController` with an `index` action. When we visit the `pages#index` page the `jskit` helper will trigger the appropriate event:
+That's it, now all controller actions will be triggered on the `JSKit` dispatcher.
+
+### Controllers
+
+JSKit offers controllers as a basic building block for JavaScript functionality. Making a folder inside `app/assets/javascripts` named `controllers` is a great place to put these:
+
+```sh
+mkdir app/assets/javascripts/controllers
+```
+
+Now simply require that entire directory in your `application.js` file:
 
 ```js
+//= require_tree ./controllers
+```
+
+#### Events
+
+There are three events triggered on every page rendered: an application controller global event, a controller global event and a controller action event. Given a `Posts` controller, when rendering the `index` action, you will notice the three events triggered where the `<%= jskit %>` snippet was placed:
+
+```js
+App.Dispatcher.trigger("controller:application:all");
+App.Dispatcher.trigger("controller:pages:all");
 App.Dispatcher.trigger("controller:pages:index");
 ```
 
-If you wish to pass data to the event handler, simply set the payload from the controller:
+This allows you to integrate your JavaScript at key points in your rails application with minimal coupling. An event triggered with no corresponding `JSKit` controller or action defined has no effect. 
+
+#### Application Controller
+
+It's common to have some JavaScript that runs on every page of your application. In the past, you may have slapped random bits of code inside a jQuery `$(document).ready` block but not with JSKit. JSKit makes an explicit yet minimally coupled connection between your Rails app and your client-side code. To define application-wide behavior, define an application controller in `app/assets/controller/application_controller.js`:
+
+```js
+App.createController("Application", {
+  all: function() {
+    // This handler will be triggered on all pages
+  }
+});
+```
+
+The `all` method is automatically wired to the `controller:application:all` event, which is automatically triggered on each page via the `<%= jskit %>` snippet. You now have a simple, testable controller to define behavior in your application.
+
+All other controllers are defined in the same way, the only difference is that your other controllers will have actions defined. Assuming you have a `Posts` controller in ruby, whose index action needs a bit of JavaScript to spice up the template. You would simply create a corresponding `Posts` controller in `app/assets/javascripts/posts_controller.js`:
+
+```js
+App.createController("Posts", {
+  actions: ["index"],
+  
+  index: function() {
+    // do stuff on the index page
+  }
+});
+```
+
+Here you can see that the `actions` array tells JSKit to wire up the `index` method to the `controller:posts:index` event. This event is automatically fired by the `<%= jskit %>` snippet.
+
+#### Mapped Events
+
+Sometimes you may want to map and action to a method with a different name, or you may want to map multiple actions to the same method. This is accomplished using mapped actions. Instead of using a string in the actions array, use an object to map the action name to the controller's method:
+
+```js
+App.createController("Posts", {
+  actions: [
+    "index",
+    { new: "setupForm" },
+    { edit: "setupForm" },
+    { create: "setupForm" }
+  ],
+  
+  index: function() {
+    // do stuff on the index page
+  },
+  
+  setupForm: function() {
+    // setup the posts form
+  }
+});
+```
+
+Here you can see that the `new`, `edit`, and `create` actions are all being wired up to the same method `setupForm`. This allows you to reuse common behavior that is needed accross multiple actions.
+
+Finally, you may wish to have some functionality that runs on every action of a controller, to do this, simply define an all method. The `all` method is automatically wired to the `controller:<controller name>:all` event:
+
+```js
+App.createController("Posts", {
+  ...
+  
+  all: function() {
+    // do something on every action of the controller
+  },
+  
+  ...
+});
+```
+
+This event structure is a simple and powerful way to coordinate your Rails application with the client-side code.
+
+### Event Payloads
+
+In addition to simply triggering events, you may optionally pass data to these events. You can pass arbitrary data to any of the three events triggered on page render. To pass data to the application controller's `all` event:
+
 
 ```rb
-class PagesController < ApplicationController
-  def index
-    set_jskit_payload("foo", [1, 2, 3], { some: "object" })
+class ApplicationController < ApplicationController
+  before_action :set_jskit_payload
+  
+  ...
+  
+  private 
+  
+  def set_jskit_payload
+    set_app_payload(current_user)
   end
 end
 ```
 
-Everything passed to `set_payload` will be converted to json for you (via `to_json`) and passed to the dispatcher:
+This will pass the current user object to the `Application` controller. You can set the payload as an array if you wish to pass multiple values:
+
+```rb
+class ApplicationController < ApplicationController
+  before_action :set_jskit_payload
+  
+  ...
+  
+  private 
+  
+  def set_jskit_payload
+    set_app_payload(current_user, [1, 2, 3], { some: "hash" })
+  end
+end
+```
+
+This will pass each item in the array as an argument to the event handler on the controller. Note that each item will have `to_json` called on it automatically, so there is no need to do it yourself. The above example will produce the following triggered event:
 
 ```js
-App.Dispatcher.trigger("controller:pages:index", "foo", [1, 2, 3], { "some": "object" });
+...
+App.Dispatcher.trigger("controller:application:all", { first_name: "John", last_name: "Doe" }, [1, 2, 3], { "some": "hash" });
+...
 ```
 
-Here is an example application using `jskit_rails`: [jskit_rails-example](https://github.com/daytonn/jskit_rails-example)
+This allows you to share data from your Rails app without explicit knowldge of how your client-side code will consume it. You may also set the controller and action event payloads in the same way:
+
+```rb
+class PostsController < ApplicationController
+  before_action :set_jskit_payload
+  
+  def index
+    set_action_payload("PostsController#index")
+  end
+  
+  private
+  
+  def set_jskit_payload
+    set_controller_payload("PostsController")
+  end
+end
+```
+
+This should be everything you need to design and test basic client-side interactions with JSKit. If you'd like to see a working example check out [this repo](https://github.com/daytonn/jskit_rails-example).
+
+Traceur Compiler
+----------------
+
+The [jskit](https://github.com/daytonn/jskit) library is written with JavaScript [ES6 features](https://github.com/google/traceur-compiler/wiki/LanguageFeatures) using the [Traceur compiler](https://github.com/google/traceur-compiler). The [traceur runtime](https://github.com/google/traceur-compiler/wiki/Building-custom-Traceur-runtimes) is included in jskit to provide these features. 
+
+_Note: While the traceur-runtime is included with jskit, if you wish to write your own code with ES6 features, you will need a separate traceur-compiler for use with the asset pipeline. Something like: [sprockets-traceur](https://github.com/gunpowderlabs/sprockets-traceur) or [traceur-rails](https://github.com/aackerman/traceur-rails). You would not need to include the `traceur-runtime` from these tools since it is included in the jskit library itself. All of your es6 scripts would need to be loaded after jskit to take advantage of it's included runtime._

data/app/decorators/controllers/jskit_rails/application_controller_decorator.rb

@@ -1,68 +1,59 @@
 ApplicationController.class_eval do
   helper_method :jskit
 
-  module JSKit
-    mattr_reader :action_payload, :app_payload, :controller_payload
-    mattr_accessor :event_namespace, :controller_name, :action_name
-
-    def action_payload=(payload)
-      @@action_payload = payload_js([*payload])
-    end
-
-    def controller_payload=(payload)
-      @@controller_payload = payload_js([*payload])
-    end
+  def jskit(config = { namespace: nil })
+    events = [
+      application_event(config),
+      controller_event(config),
+      action_event(config)
+    ].join("\n")
 
-    def app_payload=(payload)
-      @@app_payload = payload_js([*payload])
-    end
+    view_context.javascript_tag(events)
+  end
 
-    private
+  def set_action_payload(*args)
+    @action_payload = payload_js(args)
+  end
 
-    def action_event
-      [
-        JskitRails.configuration.app_namespace,
-        "Dispatcher",
-        %Q(trigger("#{[event_namespace, "controller", controller_name, action_name].compact.join(":")}"#{JSKit.action_payload});)
-      ].join(".")
-    end
+  def set_controller_payload(*args)
+    @controller_payload = payload_js(args)
+  end
 
-    def controller_event
-      [
-        JskitRails.configuration.app_namespace,
-        "Dispatcher",
-        %Q(trigger("#{[event_namespace, "controller", controller_name, "all"].compact.join(":")}"#{JSKit.controller_payload});)
-      ].join(".")
-    end
+  def set_app_payload(*args)
+    @app_payload = payload_js(args)
+  end
 
+  private
 
-    def application_event
-      [
-        JskitRails.configuration.app_namespace,
-        "Dispatcher",
-        %Q(trigger("#{[event_namespace, "controller", "application", "all"].compact.join(":")}"#{JSKit.app_payload});)
-      ].join(".")
-    end
+  def payload_js(payload)
+    comma = ", "
+    comma + payload.map(&:to_json).join(comma)
+  end
 
-    def payload_js(payload)
-      payload.empty? ? "" : ", #{payload.map(&:to_json).join(', ')}"
-    end
+  def action_event(config)
+    build_event_trigger(config, controller_name, action_name, @action_payload)
+  end
 
-    module_function(
-      :action_payload=,
-      :app_payload=,
-      :controller_payload=,
-      :payload_js,
-      :application_event,
-      :action_event,
-      :controller_event)
+  def controller_event(config)
+    build_event_trigger(config, controller_name, "all", @controller_payload)
   end
 
-  def jskit(config = { namespace: nil })
-    JSKit.event_namespace = config[:namespace]
-    JSKit.controller_name = controller_name
-    JSKit.action_name = action_name
+  def application_event(config)
+    build_event_trigger(config, "application", "all", @app_payload)
+  end
 
-    view_context.javascript_tag [JSKit.application_event, JSKit.controller_event, JSKit.action_event].join("\n")
+  def build_event_trigger(config, middle_namespace, final_namespace, payload)
+    event = [
+      config[:namespace],
+      "controller",
+      middle_namespace,
+      final_namespace
+    ].compact.join(":")
+
+    [
+      JskitRails.configuration.app_namespace,
+      "Dispatcher",
+      %Q(trigger("#{event}"#{payload});)
+    ].join(".")
   end
 end

data/spec/controllers/application_controller_spec.rb

@@ -1,43 +1,59 @@
 require "rails_helper"
 
-describe ApplicationController, type: :controller do
-  describe "#action_payload" do
-    it "sets the action_payload to an array of the arguments passed" do
-      ApplicationController::JSKit.action_payload = "foo"
-      expect(ApplicationController::JSKit.action_payload).to eq(', "foo"')
-      ApplicationController::JSKit.action_payload = ["foo", "bar", "baz"]
-      expect(ApplicationController::JSKit.action_payload).to eq(', "foo", "bar", "baz"')
-    end
-  end
+class OrdersController < ApplicationController
+end
 
-  describe "#controller_payload" do
-    it "sets the controller_payload to an array of the arguments passed" do
-      ApplicationController::JSKit.controller_payload = "foo"
-      expect(ApplicationController::JSKit.controller_payload).to eq(', "foo"')
-      ApplicationController::JSKit.controller_payload = ["foo", "bar", "baz"]
-      expect(ApplicationController::JSKit.controller_payload).to eq(', "foo", "bar", "baz"')
-    end
-  end
+describe OrdersController, type: :controller do
+  shared_examples "a payload setter" do |payload_type|
+    describe "#set_#{payload_type}_payload" do
+      it "sets the #{payload_type}_payload to an array of the passed arguments" do
+        controller.send("set_#{payload_type}_payload", "foo")
+        expect(assigns("#{payload_type}_payload")).to eq(', "foo"')
 
-  describe "#app_payload" do
-    it "sets the app_payload to an array of the arguments passed" do
-      ApplicationController::JSKit.app_payload = "foo"
-      expect(ApplicationController::JSKit.app_payload).to eq(', "foo"')
-      ApplicationController::JSKit.app_payload = ["foo", "bar", "baz"]
-      expect(ApplicationController::JSKit.app_payload).to eq(', "foo", "bar", "baz"')
+        controller.send("set_#{payload_type}_payload", "foo", "bar", "baz")
+        expect(assigns("#{payload_type}_payload")).to eq(', "foo", "bar", "baz"')
+
+        controller.send("set_#{payload_type}_payload", ["foo", "bar", "baz"])
+        expect(assigns("#{payload_type}_payload")).to eq(', ["foo","bar","baz"]')
+      end
     end
   end
 
+  it_behaves_like "a payload setter", :action
+  it_behaves_like "a payload setter", :controller
+  it_behaves_like "a payload setter", :app
+
   describe "#jskit" do
+    let(:view_context) { controller.view_context }
+
+    before do
+      controller.action_name = "action"
+    end
+
     it "returns a script tag with the global event and the controller event" do
-      subject = ApplicationController.new
-      allow(ApplicationController::JSKit).to receive(:controller_name) { "test_controller" }
-      allow(ApplicationController::JSKit).to receive(:action_name) { "test_action" }
-      application_event = ApplicationController::JSKit.send(:application_event)
-      controller_event = ApplicationController::JSKit.send(:controller_event)
-      action_event = ApplicationController::JSKit.send(:action_event)
-
-      expect(subject.jskit).to eq(subject.view_context.javascript_tag([application_event, controller_event, action_event].join("\n")))
+      app_event = "App.Dispatcher.trigger(\"controller:application:all\", \"baz\");"
+      controller_event = "App.Dispatcher.trigger(\"controller:orders:all\", \"bar\");"
+      action_event = "App.Dispatcher.trigger(\"controller:orders:action\", \"foo\");"
+      expected_js = view_context.javascript_tag([app_event, controller_event, action_event].join("\n"))
+
+      controller.set_action_payload("foo")
+      controller.set_controller_payload("bar")
+      controller.set_app_payload("baz")
+
+      expect(controller.jskit).to eq(expected_js)
+    end
+
+    it "is exposed as a helper method" do
+      expect(controller.view_context.jskit).to eq(controller.jskit)
+    end
+
+    it "namespaces events based on the config" do
+      app_event = "App.Dispatcher.trigger(\"some_namespace:controller:application:all\");"
+      controller_event = "App.Dispatcher.trigger(\"some_namespace:controller:orders:all\");"
+      action_event = "App.Dispatcher.trigger(\"some_namespace:controller:orders:action\");"
+      expected_js = view_context.javascript_tag([app_event, controller_event, action_event].join("\n"))
+
+      expect(controller.jskit(namespace: "some_namespace")).to eq(expected_js)
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jskit_rails
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 3.0.0
 platform: ruby
 authors:
 - Dayton Nolan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-03 00:00:00.000000000 Z
+date: 2014-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails