reins 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: afbdfa48fc19a1f413c5f71527218bb1daaf3d3a
-  data.tar.gz: 612f9ff4237d55935bcbf3cf0b88c689c732ed57
+  metadata.gz: 4c94c1362681a7d1fc9abb25e1cdbcc9d77a5136
+  data.tar.gz: 5f59f0adb23f90acb5f8d448f9044088d8ce995e
 SHA512:
-  metadata.gz: d1aaa49ceda92281a40d5c96bdac4a8e598b2a026cca0ddd6ce9858b179adf545f5ba99681c067f26718dc3e980db539b7aa7abf3e5c8fe9cc52842256e6cc65
-  data.tar.gz: b9d4833090d527baeaf94a5ce298754e334d140023b8666d1cb380a67462e7debc5756f8ca78673ba5b2f5ffb4306f9d989fc967eff22810b2840ee38df35de0
+  metadata.gz: 9178864998b34cb92cd9a624f894291661b44267f37d3eb53c7555026846f1680e5e5409862fd5dafd3f4349a680ad239ebf0c0523253c7a5947375948b9112f
+  data.tar.gz: 555e9f4427efa2de4ec4d63cbeb9e4d395fe4e1021206e1c0ecc3e5ab5ee5ba36d99cdbcdfa09661a6d9d63a64e62ae61d1926c07715c9618a759dfae52f8ed1

data/README.md

@@ -1,30 +1,182 @@
-# Reins [![Gem Version](https://badge.fury.io/rb/reins.svg)](http://badge.fury.io/rb/reins) [![wercker status](https://app.wercker.com/status/6ea31467d299403dc3bac9f6bd962d96/s/master "wercker status")](https://app.wercker.com/project/bykey/6ea31467d299403dc3bac9f6bd962d96) ![](http://ruby-gem-downloads-badge.herokuapp.com/reins)
+# Reins!
 
-Reins is a ruby gem that automates the creation of javascript controllers that match the structure of your rails controllers.
-It enables you to keep javascript code out of your views by defining namespaced functions that get called automatically for each rails controller action that runs.
-
-This even works in the case of javascript code that needs data from the server (which almost always ends up inside a <script> tag somewhere with <%%> tags...).
-You just have to define the @reins_params hash on the controller and this hash will be JSONified and passed to the javascript controller as a dictionary object.
-
-Reins can be used with or without turbolinks.
+#### Reins brings some convention over configuration to your Rails application's javascript.
 
+[![wercker status](https://app.wercker.com/status/6ea31467d299403dc3bac9f6bd962d96/s/master "wercker status")](https://app.wercker.com/project/bykey/6ea31467d299403dc3bac9f6bd962d96)
+[![Code Climate](https://codeclimate.com/github/weareredlight/reins/badges/gpa.svg)](https://codeclimate.com/github/weareredlight/reins)
+[![Test Coverage](https://codeclimate.com/github/weareredlight/reins/badges/coverage.svg)](https://codeclimate.com/github/weareredlight/reins)
+[![Gem Version](https://badge.fury.io/rb/reins.svg)](http://badge.fury.io/rb/reins)
+![](http://ruby-gem-downloads-badge.herokuapp.com/reins)
 
-To start using it:
+### Why reins?
+Rails' convention over configuration approach to development is well known, however when it comes to javascript it is sorely missing.
+Every time you create a scaffold, resource, or controller you get a new javascript file with that controller's name, but that's it.
+Since all the code is minified and aggregated into application.js by the assets pipeline, it's very easy to end up with a big mess.
 
-add to your gemfile:
+This means that you need to manually find a way to keep the global scope clean, avoid name collisions and define a common structure for your javascript code.
 
-  gem 'reins'
 
+Reins is a ruby gem that automates the creation of javascript controllers that match the structure of your rails controllers.
+It creates a predefined structure for your javascript code where code for different controllers is kept in separate namespaces.
+It also enables you to keep javascript code out of your views by defining functions that get called automatically on jQuery.ready and Turbolinks page:load for each rails controller action that runs.
 
-add to application.js:
+This even works in the case of javascript code that needs data from the server (which almost always ends up inside a script tag somewhere with erb thrown in the mix to include server-side data...).
+You just have to define a special hash on the controller and this hash will be JSONified and passed to the reins javascript controller as a dictionary object.
 
-  //= require reins
+### How can I start using it?
 
+Add reins to your Gemfile:
 
-add to layouts/*.html.erb, right before </body> closing tag:
+```
+gem 'reins'
+```
 
-  <%= reins_script_tag %>
+Add reins.js to application.js:
 
+```
+//= require reins
+```
 
+Add the reins script tag to your application layout, or any layout/view where you want reins to automatically call your javascript controllers.
+I prefer just adding it to ```layouts/application.html.erb``` (and any other layouts I might have) right before closing the ```<body>``` tag:
 
-Reins is licenced under the MIT License. Please see the file MIT-LICENSE for more details.
+```
+...
+<body>
+  ...
+  <%= yield %>
+  ...
+  <%= reins_script_tag %>
+</body>
+...
+```
+
+### Ok, what now?
+
+After reins in installed, every time you generate a new scaffold/resource/controller you will get a new javascript file inside app/assets/controllers/resource_name.js that will have a specific structure.
+
+If the above steps went ok, now is the perfect time for an example:
+
+Suppose we generate a HelloController and add the following code inside:
+
+```
+class HelloController < ApplicationController
+
+  def index
+    @reins_params = {
+      name: 'Lebowski'
+    }
+  end
+
+end
+```
+
+Let's quickly create a controller and view by running:
+```
+rails g controller hello
+touch app/views/hello/index.html.erb
+```
+Don't worry about the empty view for now, as it is irrelevant for reins to work :)
+When you run the rails generator, reins will create a javascript file at
+/app/assets/javascripts/controllers/cookies.js with some boilerplate code. After
+changing a few lines it might look like this:
+
+```
+/**
+ * Anonymous self-running closure to avoid polluting the global namespace with
+ * definitions that should be kept private.
+ */
++function() {
+
+  /**
+   * Publicly accessible functions related to the hello rails
+   * controller.
+   * These can be called from anywhere like this:
+   *   r.hello.function_name(arg1, arg2);
+   *
+   * You can declare your javascript controllers inside this namespace. They
+   * should have the same name as your rails actions, but starting with an
+   * underscore (so for the show action, the corresponding function would be
+   * named _show).
+   *
+   * They will be called automatically by reins every time the corresponding
+   * action renders an HTML view, or manually from a js.erb view by using the
+   * call_reins_controller helper.
+   */
+  window.r.hello = {
+
+    /**
+     * Controller action corresponding to the #index rails action.
+     *
+     * This function is called on $.ready or page:load every time that the
+     * "index" action renders an html view.
+     */
+    _index: function(params) {
+      this.greet_user(params.name);
+    },
+
+
+    /**
+     * You can also declare your own functions here.
+     *
+     * Call this one from anywhere like this:
+     *   r.hello.greet_user('John Doe');
+     * Or from inside this namespace with:
+     *   this.greet_user('John Doe');
+     */
+    greet_user: function(name) {
+      show_msg('Have a nice day ' + name + '!');
+    }
+
+  };
+
+
+  ////////////////////////////////////////////////////////////////////////////
+  // Anything below this but still inside the anonymous function is private //
+  ////////////////////////////////////////////////////////////////////////////
+
+  /**
+   * This is a private function. It can be called by any function inside this
+   * closure, including the controllers above, but it's invisible to the outside
+   * world.
+   *
+   * It can be called from anywhere inside this closure like this:
+   *   my_function2('Hi there!');
+   * It cannot be called from anywhere else.
+   */
+  function show_msg(msg) {
+    alert(msg);
+  }
+
+}();
+```
+
+Functions inside the window.r.hello namespace that start with an underscore and match the name of a rails action will be called automatically by reins when that action is rendered. You can declare a hash called @reins_params on the rails controller and it will be JSONified and passed to your javascript controller as an argument.
+Most of the functionality is explained in the comments inside the javascript snippet above.
+
+### More stuff
+
+#### What if I'm rendering a js.erb view?
+
+Reins will not be called automatically for these, as the whole idea of js.erb views is to give you full control.
+However, to avoid repeating code, you can call your reins controller from js.erb views.
+You just need to do this:
+```
+<%= call_reins_controller %>
+```
+This will call the matching controller and pass the @reins_params hash if it was defined in the controller.
+
+#### Why do my controllers only get called on page:load when using turbolinks? I want page:change!
+
+Just add this to your application.js:
+```
+$(document).off('page:load').on('page:change', r.call_js_controller);
+```
+THIS WILL REMOVE any page:load event handlers that you may have attached to $(document), so be warned!
+
+Also of note is that calling the reins controller in this way will use the last params that were sent by the server.
+This means that if you are going back to a page that was cached by turbolinks, the controller could be called with params from another controller/action, which is probably not what you want.
+
+
+
+Reins is licenced under the MIT License. Please see the file MIT-LICENSE for details.

data/lib/rails/generators/reins/assets/templates/reins_controller.js

@@ -1,64 +1,44 @@
 /**
- * Anonymous self-running function to keep us from polluting the global namespace
- * with definitions that should be kept private.
+ * Anonymous self-running closure to avoid polluting the global namespace with
+ * definitions that should be kept private.
  */
 +function() {
 
   /**
-   * Publicly accessible functions related to <%= file_name %>.
-   * These can be called from anywhere as r.<%= file_name %>.function_name(arg1, arg2);
+   * Publicly accessible functions related to the <%= file_name %> rails
+   * controller.
+   * These can be called from anywhere like this:
+   *   r.<%= file_name %>.function_name(arg1, arg2);
    *
-   * This scope includes the JS controller action functions corresponding to the
-   * rails <%= file_name %> controller, so keep in mind that funcions
-   * that match the names of the actions will be called automatically by rails.
+   * You can declare your javascript controllers inside this namespace. They
+   * should have the same name as your rails actions, but starting with an
+   * underscore (so for the show action, the corresponding function would be
+   * named _show).
+   *
+   * They will be called automatically by reins every time the corresponding
+   * action renders an HTML view, or manually from a js.erb view by using the
+   * call_reins_controller helper.
    */
   window.r.<%= file_name %> = {
 
     /**
      * Controller action corresponding to the #new rails action.
-     * This code is run everytime that the new.html format is rendered by rails.
+     *
+     * This function is called on $.ready or page:load every time that the
+     * "new" action renders an html view.
      */
     // _new: function() {
     // },
 
 
-    /**
-     * Controller action corresponding to the #create rails action.
-     * This code is run everytime that the create.html format is rendered by rails.
-     */
-    // _create: function(params) {
-    // },
-
-
-    /**
-     * Controller action corresponding to the #index rails action.
-     * This code is run everytime that the create.html format is rendered by rails.
-     */
-    // _index: function(params) {
-    // },
-
-
     /**
      * Controller action corresponding to the #show rails action.
-     * This code is run everytime that the create.html format is rendered by rails.
+     *
+     * This function is called on $.ready or page:load every time that the
+     * "show" action renders an html view.
      */
     // _show: function(params) {
-    // },
-
-
-    /**
-     * Controller action corresponding to the #update rails action.
-     * This code is run everytime that the create.html format is rendered by rails.
-     */
-    // _update: function(params) {
-    // },
-
-
-    /**
-     * Controller action corresponding to the #destroy rails action.
-     * This code is run everytime that the create.html format is rendered by rails.
-     */
-    // _destroy: function(params) {
+    //   this.my_function(params.name);
     // },
 
 
@@ -67,9 +47,11 @@
      *
      * Call this one from anywhere like this:
      *   r.<%= file_name %>.my_function('John Doe');
+     * Or from inside this namespace with:
+     *   this.my_function('John Doe');
      */
     // my_function: function(name) {
-    //   alert('Have a nice day ' + name + '!');
+    //   my_function2('Have a nice day ' + name + '!');
     // }
 
   };
@@ -84,9 +66,13 @@
    * This is a private function. It can be called by any function inside this
    * closure, including the controllers above, but it's invisible to the outside
    * world.
+   *
+   * It can be called from anywhere inside this closure like this:
+   *   my_function2('Hi there!');
+   * It cannot be called from anywhere else.
    */
-  // function my_function2() {
-  //   // do stuff...
+  // function my_function2(msg) {
+  //   alert(msg);
   // }
 
 

data/lib/reins/version.rb

@@ -1,3 +1,3 @@
 module Reins
-  VERSION = '0.0.3'
+  VERSION = '0.0.4'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reins
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Tony Goncalves
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-04-22 00:00:00.000000000 Z
+date: 2015-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails