pagescript 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 209386553acce320c125f04412f86c3b980e1d39
-  data.tar.gz: 4d9bd8086a239d56595d7a84c196849ece8abe85
+  metadata.gz: cf788c27bc7710e84c048a762da8f5ea3de504d3
+  data.tar.gz: 712e21fa0c410c61db48cc8cac287424fd7831c0
 SHA512:
-  metadata.gz: 363a152f746ae6478b181f195893b84295e72c4696916288723767a8cd3c2624f0aa4c00f09f42f6a48c5a03943e06a900b49dd6a57002d4209301529910b861
-  data.tar.gz: 834d210617c0302b15b99e0ecc2cc7b66e5953158ad633b1882a61bfd7d13f5052a4c2965e848b3730d9bf982c4cf409dc7f5c860241eb40b8f377f84359cf47
+  metadata.gz: fb896ad96e0ff850547c6919c9757c77045abcbd5f74be4db91377569ad998768eabfe1a8163c63522c1729b82253c084cc687c663f89b449a0201f85e49b939
+  data.tar.gz: 7c2e61a82c66b59bfaaf17324fcc61b902c608b1b6926a3f74b05d97fc672ca79711f0cd5cc0ec347f6c9f066b4299ace8f64ecd13924e25d181c38f548786ba

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2016 Max Calabrese
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,137 @@
+# Pagescript
+
+So you're ready to put on the big girl/boy pants and stop using inline
+script tags in your views?
+
+Can't figure out how to hook javascript to specific actions in your Rails app?
+
+Pagescript can help. It fires custom events based on what controller / action
+was called and makes it simple to add event handlers.
+
+Pagescript is intended for classical web applications where Rails
+handles rendering views. SPA's have better mechanisms for this anyways.
+
+It is designed to integrate seamlessly with [Turbolinks](https://github.com/turbolinks/turbolinks).
+
+## Dependencies
+- Sprockets
+- jQuery
+- Turbolinks (optional)
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pagescript'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+## Usage
+
+Replace your the body tag in your `app/views/layouts/application.html.erb`
+with `<%= body_tag %>`. This adds [*data* attributes](https://developer.mozilla.org/docs/Web/Guide/HTML/Using_data_attributes) that we can hook onto.
+
+You can optionally pass the `params_as_metadata: true` option to attach
+the url parameters to the body element. See [The pagescript event][#the-pagescript-event] for more details.
+
+```javascript
+//= pagescript
+Pagescript.on('users#*', function(){
+    console.log('some action belonging to UsersController was rendered');
+  }) // all methods are chainable
+  .on('users#show', function(){
+    console.log('Users#show action was called');
+  }) // you can remove handlers as well.
+  .off('users#*');
+
+// This is only required if you are not using Turbolinks
+Pagescript.jumpstart();
+```
+
+Note that you should not wrap this in a `$(document).ready` callback.
+
+## Pagescript Event types
+On each page replacement (or load) Pagescript will fire multiple events that you can listen to.
+`*` symbolizes a wildcard.
+
+```JS
+// A specific controller_name and action
+$.on('pagescript:controller_name#action_name')
+// Any action belonging to a specific controller
+$.on('pagescript:controller_name#*')
+// Any action matching action_name
+$.on('pagescript:*#action_name')
+// Any page load
+$.on('pagescript:*')
+```
+
+When using the Pagescript API methods you don't need to include the `pagescript:`
+"namespace".
+
+## The Pagescript Event
+The [Event object](https://api.jquery.com/category/events/event-object/) which
+is passed to event handlers has the following extra properties:
+
+- controller [String]
+- action [String]
+- params [object]
+
+The params object is only populated if you have used the `params_as_metadata: true` option.
+
+```erb
+<%= body_tag(params_as_metadata: true) %>
+```
+
+The param keys are cast to `camelCase` by jQuery.
+
+## Javascript API
+All methods return the Pagescript module and can be chained.
+
+When using the Pagescript API methods you don't need to include the `pagescript:`
+"namespace" in the event name.
+
+`on`, `off` and `one` proxy to their jQuery counterparts. Please see the jQuery
+documentation for more details.
+
+### Pagescript.kickstart
+Used to start hook Pagescript to the `document.ready` event in the absense of
+Turbolinks
+
+### Pagescript.off
+Removes all handlers for the given event.
+See [jQuery.off](http://api.jquery.com/off/)
+
+### Pagescript.on
+Attaches an event handler to a controller, a particular action or any action
+matching the name.
+
+```JS
+Pagescript.on('foo#bar', function(e){
+  console.log( e.controller, e.action_name, e.params );
+  // "foo", "bar", {}
+});
+```
+
+See [jQuery.on](http://api.jquery.com/on/)
+
+### Pagescript.one
+Like `.on`, but the handler only fires once.
+
+See [jQuery.one](http://api.jquery.com/one/)
+
+### Pagescript.start
+Adds the main event handler which Pagescript hinges on.
+
+### Pagescript.stop
+Halts any Pagescript events from being fired - does not remove user created handlers. Call `.start` to reverse the effect.
+
+## License
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+## Want to help?
+See [Contributing](CONTRIBUTING.md) for how you can help and [Devlopment](DEVELOPMENT.md) for instructions to setup the test suite and
+what is expected of you.

data/Rakefile

@@ -0,0 +1,21 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+require 'bundler/gem_tasks'
+require 'yard'
+require 'rspec/core/rake_task'
+
+Bundler::GemHelper.install_tasks
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load 'rails/tasks/engine.rake'
+load 'rails/tasks/statistics.rake'
+
+YARD::Rake::YardocTask.new
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/app/assets/config/pagescript_manifest.js

@@ -0,0 +1 @@
+//= link_directory ../javascripts/pagescript .js

data/app/assets/javascripts/pagescript.js

@@ -0,0 +1,125 @@
+//= require jquery
+var Pagescript = (function(ps, $){
+  var $doc = $(document);
+
+  // "private" methods
+  function namespace(str){
+    return str.match(/pagescript:/) ? str : 'pagescript:' + str;
+  }
+
+  function trigger(str, data){
+    return $doc.trigger({
+      type: namespace(str),
+      controller: data.controller,
+      action: data.action,
+      params: filter_params(data)
+    });
+  }
+
+  function filter_params(obj) {
+    var re = /^params([A-Z])(.*)/;
+    var filtered = {};
+    $.each( obj, function( key, value ) {
+      var matches = key.match(re);
+      if (matches) {
+        filtered[ matches[1].toLowerCase() + (matches[2] ||  "") ] = value;
+      }
+    });
+    return filtered;
+  }
+
+
+  function parseEvents(str) {
+    return jQuery.map(str.split(' '), function(s){
+      return namespace(s);
+    }).join(' ');
+  }
+
+  // Integrate with turbolinks
+  // 'page:change' is the turbolinks-classic api
+  // 'turbolinks:load' is the Turbolinks 5+ api
+  $doc.on('page:change turbolinks:load', function(){
+    $doc.trigger('pagescript:load');
+  });
+
+  /**
+  * Adds the main event handler
+  * @api
+  * @return this [Object]
+  */
+  ps.start = function() {
+    ps.stop();
+    $doc.on('pagescript:load', function(){
+      var data = $('body').data();
+      trigger(data.controller + "#" + data.action, data);
+      trigger(data.controller + "#*", data);
+      trigger("*#" + data.action , data);
+      trigger('*', data);
+    });
+    return ps;
+  };
+  /**
+  * Halts any Pagescript events from being fired - does not remove the handlers.
+  * @api
+  * @return this [Object]
+  **/
+  ps.stop = function(){
+    $doc.off('pagescript:load');
+    return this;
+  };
+  /**
+  * Used to hook Pagescript to the `document.ready`
+  * event in the absense of Turbolinks.
+  * @api
+  * @return this [Object]
+  **/
+  ps.kickstart = function(){
+    $doc.ready(function(){ $doc.trigger('pagescript:load'); });
+    return this;
+  };
+  /**
+  * Attaches an event handler to a controller, a particular action or any action.
+  * @api
+  * @param events [String]
+  * @param selector [String] optional
+  * @param data [Object] optional
+  * @param handler [Function]
+  * @return this [Object]
+  **/
+  ps.on = function( events, selector, data, handler ){
+    var args = $.makeArray( arguments );
+    args[0] = parseEvents(args[0]);
+    $doc.on.apply($doc, args);
+    return this;
+  };
+  /**
+  * @api
+  * @param events [String]
+  * @param selector [String] optional
+  * @param handler [Function]
+  * @return this [Object]
+  **/
+  ps.off = function( events, selector, handler ){
+    var args = $.makeArray( arguments );
+    args[0] = parseEvents(args[0]);
+    $doc.off.apply($doc, args);
+    return this;
+  };
+  /**
+  * @api
+  * @param events [String]
+  * @param selector [String] optional
+  * @param data [Object] optional
+  * @param handler [Function]
+  * @return this [Object]
+  **/
+  ps.one = function( events, selector, data, handler ){
+    var args = $.makeArray( arguments );
+    args[0] = parseEvents(args[0]);
+    $doc.one.apply($doc, args);
+    return this;
+  }
+
+  // Export module
+  return ps.start();
+}(Pagescript || {}, jQuery));

data/app/assets/stylesheets/pagescript/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/lib/pagescript.rb

@@ -0,0 +1,6 @@
+require 'pagescript/helpers/tags_helper'
+require 'pagescript/engine'
+
+# Main level module for engine
+module Pagescript
+end

data/lib/pagescript/engine.rb

@@ -0,0 +1,9 @@
+module Pagescript
+  # Main Rails integration.
+  # Used primarily to add the gem assets to the Sprockets pipeline.
+  class Engine < ::Rails::Engine
+    require 'jquery-rails'
+    isolate_namespace Pagescript
+    ActionView::Base.send :include, Pagescript::TagsHelper
+  end
+end

data/lib/pagescript/helpers/tags_helper.rb

@@ -0,0 +1,60 @@
+module Pagescript
+  # A helper that creates elements with metadata attached as data attributes.
+  module TagsHelper
+    # Generates a `<body>` tag
+    # with HTML5 data attributes for the controller & action name.
+    # The keyword arguments are forwarded to tag and content_tag.
+    # @see http://api.rubyonrails.org/classes/ActionView/Helpers/TagHelper.html ActionView::Helpers::TagHelper
+    # @return [String]
+    # @yield Yields flow to an optional block.
+    #   Using a block adds a closing </body> tag.
+    # @param [Boolean] params_as_metadata default: false.
+    #   Includes params from the URL as data attributes.
+    #   The data attributes are prefixed with `param-`.
+    #   Underscores in the param name are converted to '-'.
+    # @example when called without a block
+    #   body_tag
+    #   =>  <body data-controller="foo" data-action="bar">
+    # @example when called with a block
+    #   body_tag { 'hello world' }
+    #   =>  <body data-controller="foo" data-action="bar">Hello World</body>
+    # @example when called with keyword arguments
+    #   body_tag(foo: 'bar', data: { x: 2 })
+    #   =>  <body data-controller="foo" data-action="bar" foo="" data-x="2">
+    # @example when params_as_metadata is true
+    #   body_tag(params_as_metadata: true)
+    #   =>  <body data-controller="foo" data-action="bar" data-params-user-id="2">
+    # @since 0.1.0
+    # @api
+    def body_tag(params_as_metadata: false, **kwargs)
+      options = kwargs.deep_merge( data: data_attrs(params_as_metadata) )
+      if block_given?
+        content_tag(:body, options) { yield }
+      else
+        tag(:body, options, true)
+      end
+    end
+
+    private
+
+    def data_attrs(params_as_metadata = false)
+      {
+        controller: controller_name,
+        action: action_name
+      }.tap do |hash|
+        if params_as_metadata
+          params_from_url.each do |k, v|
+            hash["params-#{k}"] = v
+          end
+        end
+      end
+    end
+
+    def params_from_url
+      {}.tap do |h|
+        h.merge! request.path_parameters
+        h.merge! request.query_parameters
+      end.except(:controller, :action)
+    end
+  end
+end

data/lib/pagescript/version.rb

@@ -0,0 +1,3 @@
+module Pagescript
+  VERSION = '0.3.0'.freeze
+end

data/spec/dummy/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require_relative 'config/application'
+
+Rails.application.load_tasks

data/spec/dummy/app/assets/config/manifest.js

@@ -0,0 +1,5 @@
+
+//= link_tree ../images
+//= link_directory ../javascripts .js
+//= link_directory ../stylesheets .css
+//= link pagescript_manifest.js

data/spec/dummy/app/assets/javascripts/application.js

@@ -0,0 +1,33 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or any plugin's vendor/assets/javascripts directory can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// compiled file. JavaScript code in this file should be added after the last require_* statement.
+//
+// Read Sprockets README (https://github.com/rails/sprockets#sprockets-directives) for details
+// about supported directives.
+//= require jquery
+//= require jquery_ujs
+//= require pagescript
+//= require_tree .
+
+function log(e){
+  $("#logger").append('<li>'+e.type+'</li>');
+}
+
+Pagescript
+  .on('haikus#* *#index haikus#index', log)
+  .on('*#show', log)
+  .on('haikus#show', log)
+  .on('pagescript:*', function(e){
+    $('#test').text(JSON.stringify({
+      type: e.type,
+      params: e.params,
+      action: e.action,
+      controller: e.controller
+    }));
+  })
+  .kickstart();