panmind-zendesk 1.0

data/README.md

@@ -0,0 +1,143 @@
+Zendesk on Rails - Dropbox and Remote Authentication
+====================================================
+
+Purpose
+-------
+
+The plugin implements the HTML generation code for the
+[Zendesk dropbox](http://www.zendesk.com/blog/instant-support-access-with-drop-box)
+and the necessary controller and routing code to implement
+[Zendesk's remote authentication](http://www.zendesk.com/api/remote-authentication)
+
+
+Installation
+------------
+
+Via RubyGems:
+
+    gem install panmind-zendesk
+
+Or via Rails Plugin:
+
+    script/plugin install git://github.com/Panmind/zendesk.git
+
+
+Configuration
+-------------
+
+In your `config/routes.rb`:
+
+    map.zendesk '/support', :controller => 'sessions'
+
+The `/support` path will then respond to the methods that generate the query
+string parameters required for Remote Authentication, while the `/support/exit`
+path will simply set a notice in the flash and redirect the user to the app
+`root_url`. You can override this behaviour by implementing a `zendesk_logout`
+method in the controller.
+
+You can define these methods in any of your controllers, in this example we
+defined it in the `SessionsController`: so, in your `sessions_controller.rb`:
+
+    include Panmind::Zendesk::Controller if Panmind::Zendesk.enabled?
+
+Finally, in your config/environment.rb:
+
+    Panmind::Zendesk.set(
+      :token     => 'Your Zendesk token',
+      :hostname  => 'example.zendesk.com',
+      :login     => proc { [current_user.name, current_user.email] },
+      :login_url => :login_url,
+      :dropbox   => {
+        :title => 'Dropbox title',
+        :email => proc { current_user.email rescue nil }
+      }
+    )
+
+The required options are:
+
+ * `:token` -- your zendesk [shared secret](http://www.zendesk.com/api/remote-authentication)
+ * `:hostname` -- your zendesk account host name
+ * `:login` -- a `Proc` object evaluated in the controller instance context,
+   that must return an `Array` whose first element is the current user name and the second its email.
+   This `Proc` is evaluated iff the `logged_in?` instance method of your controller returns true.
+ * `:login_url` -- The name of the named route helper that generates the full URL of your login page.
+   We use `:ssl_login_url` thanks to our [SSL Helper](http://github.com/Panmind/ssl_helper) plugin.
+
+The `:dropbox` option is for the [Zendesk dropbox](http://www.zendesk.com/blog/instant-support-access-with-drop-box)
+configuration, it should be an hash with symbolized keys and it is converted to
+`JSON` and bound to the `zendesk_params` Javascript variable.
+
+To facilitate the Dropbox usage, the `:email` option can be a `Proc` object that
+is then evaluated in the controller instance context and should return the current
+user e-mail or nil if the user is not logged in. If the `:email` option is unset
+no e-mail appears precompiled in the Dropbox for, or you could even set a static
+email for every feedback request (dunno why should you do that, though :-).
+
+
+Usage
+-----
+
+To embed the Dropbox tags, use the `zendesk_dropbox_tags` helper
+in your layout:
+
+    <%= zendesk_dropbox_tags %>
+
+To display a link that displays the dropbox when clicked use the
+`zendesk_dropbox_link_to` helper in your views:
+
+    <%= zendesk_dropbox_link_to 'Send feedback' %>
+
+To display a link that starts the Remote Authentication process
+use the `zendesk_link_to` helper in your views:
+
+    <%= zendesk_link_to 'Support' %>
+
+The second parameter of said helper is passed to Rails' `link_to`
+one to customize the link tag attributes.
+
+
+Caching
+-------
+
+If you implement asset minifization and concatenation, you'll surely
+want to reduce HTTP requests to external services. While it's not the
+best practice in the world to cache said services assets, to speed up
+your application you may be forced to do it.
+
+We're doing it on [Panmind](http://panmind.org) - both to reduce the
+number of HTTP requests and because the lag with `assets0.zendesk.com`
+from Europe is quite high.
+
+To make a long story short, if you're including the Zendesk assets in
+your minified blobs, you can use just the `zendesk_dropbox_config` view
+helper to generate the dropbox configuration, placing it before the
+inclusion of your JS blobs: this way the `zenbox_params` variable will
+be already defined when the JS is evaluated.
+
+If you're wondering how we're minifying and concatenating our JS and CSS
+assets, follow us on GitHub: we plan to release that code as well. :-)
+
+
+Compatibility
+-------------
+
+Tested with Rails 2.3.8 with the `rails_xss` plugin installed,
+running under Ruby 1.9.1-p378.
+
+
+TODO
+----
+
+ * Your login action must implement a `redirect_to params[:return_to] || some_other_url`
+   or redirects to Zendesk won't work: remove relying on this assumption. Cleanly.
+ * Clean up configuration by requiring less variables: *convention over configuration*!
+ * Configuration of the `logged_in?` method name
+ * Remove the `String#force_utf8` patch and its usage
+ * Allow options passing to the `zendesk_dropbox_link_to` helper
+ * Code documentation
+ * Gem
+ * Tests (yuck!)
+
+Please fork the project and send us a pull request if you check off any of these items
+from the to-do list, or for any other improvement. Thanks! :-)
+

data/Rakefile

@@ -0,0 +1,48 @@
+require 'rake'
+require 'rake/rdoctask'
+
+require 'lib/panmind/zendesk'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name             = 'panmind-zendesk'
+
+    gemspec.summary          = 'Zendesk on Rails - Dropbox and Remote Authentication'
+    gemspec.description      = 'The plugin implements the HTML generation code for the '   \
+                               'Zendesk dropbox and the necessary controller and routing ' \
+                               'code to implement remote authentication'
+
+    gemspec.authors          = ['Marcello Barnaba']
+    gemspec.email            = 'vjt@openssl.it'
+    gemspec.homepage         = 'http://github.com/Panmind/zendesk'
+
+    gemspec.files            = %w( README.md Rakefile rails/init.rb ) + Dir['lib/**/*']
+    gemspec.extra_rdoc_files = %w( README.md )
+    gemspec.has_rdoc         = true
+
+    gemspec.version          = Panmind::Zendesk::Version
+    gemspec.date             = '2010-11-17'
+
+    gemspec.require_path     = 'lib'
+
+    gemspec.add_dependency('rails', '~> 2.3.8')
+  end
+rescue LoadError
+  puts 'Jeweler not available. Install it with: gem install jeweler'
+end
+
+desc 'Generate the rdoc'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_files.add %w( README.md lib/**/*.rb )
+
+  rdoc.main  = 'README.md'
+  rdoc.title = 'Zendesk on Rails - Dropbox and Remote Authentication'
+end
+
+desc 'Will someone help write tests?'
+task :default do
+  puts
+  puts 'Can you help in writing tests? Please do :-)'
+  puts
+end

data/lib/panmind/string_force_utf8_patch.rb

@@ -0,0 +1,29 @@
+# Adds a .force_utf8 to the String class: it forces the instance
+# encoding to utf-8 and then normalizes in NFKC form.
+#
+# For now, we're using ActiveSupport because it has proven to be
+# 33% faster than UnicodeUtils.. but in the future you can never
+# know whether the AS::Multibyte::Chars class will be supported.
+#
+# Please read http://www.cl.cam.ac.uk/~mgk25/unicode.html#ucsutf
+# for more information about Unicode Normalization Forms.
+#
+#   - vjt  Wed Jul 21 16:51:25 CEST 2010
+#
+unless 'the string'.respond_to?(:force_utf8)
+  class String
+    if '1.9'.respond_to?(:force_encoding)
+      #require 'unicode_utils/nfkc'
+
+      def force_utf8
+        #force_encoding('UTF-8')
+        #replace UnicodeUtils.nfkc(self)
+        replace ActiveSupport::Multibyte::Chars.new(self).normalize(:kc)
+      end
+    else
+      def force_utf8
+        replace mb_chars.normalize(:kc)
+      end
+    end
+  end
+end

data/lib/panmind/zendesk.rb

@@ -0,0 +1,144 @@
+require 'digest/md5'
+
+module Panmind
+  # Zendesk remote authentication helper for Rails. Implements JS generation,
+  # controller actions and route helpers. Have a look at the code, because it
+  # is more explanatory than a thousand words :-)
+  #
+  # Kudos to the Zendesk staff for such a simple and effective interface.
+  #
+  # (C) 2010 Panmind, Released under the terms of the Ruby License.
+  #
+  #   - vjt  Wed Jul 21 13:00:42 CEST 2010
+  #
+  module Zendesk
+    Version = 1.0
+
+    class ConfigurationError < StandardError; end
+
+    class << self
+      attr_reader :token, :hostname
+
+      def auth_url;    @auth_url    ||= "http://#{hostname}/access/remote/".freeze end
+      def return_url;  @return_url  ||= "http://#{hostname}/login".freeze          end
+      def support_url; @support_url ||= "http://#{hostname}/home".freeze           end
+
+      # TODO these should become attr_readers and we set @variables directly
+      attr_accessor :dropbox, :login, :login_url, :assets_path, :assets_name
+
+      def set(options)
+        self.token, self.hostname, self.login, self.login_url =
+          options.values_at(:token, :hostname, :login, :login_url)
+
+        if %w( token hostname login login_url ).any? {|conf| send(conf).blank?}
+          raise ConfigurationError, "Zendesk requires the API token, an hostname a proc to infer the user name "\
+                                    "and e-mail and the login route helper name" # TODO don't require all these things
+        end
+
+        self.dropbox = (options[:dropbox] || {}).reverse_merge(
+          :tab_id    => 'feedback',
+          :tab_color => 'black',
+          :title     => 'Support',
+          :text      => "How may we help you? Please fill in details below, and we'll get back to you as soon as possible.",
+          :url       => Zendesk.hostname
+        ).freeze
+
+        # TODO better configuration
+        self.assets_path = options[:assets_path] || '//assets0.zendesk.com/external/zenbox'
+        self.assets_name = options[:assets_name] || 'overlay'
+      end
+
+      def enabled?
+        Rails.env.production?
+      end
+
+      private
+        def token=(token);       @token    = token.force_utf8.freeze rescue nil end
+        def hostname=(hostname); @hostname = hostname.freeze                    end
+    end
+
+    module Helpers
+      def zendesk_dropbox_config
+        config = Zendesk.dropbox
+        if config[:email].kind_of?(Proc)
+          config = config.merge(:email => instance_exec(&config[:email]))
+        end
+
+        javascript_tag("var zenbox_params = #{config.to_json};").html_safe
+      end
+
+      def zendesk_dropbox_tags
+        return unless Zendesk.enabled?
+
+        %(#{zendesk_dropbox_config}
+        <style type='text/css'>@import url('#{Zendesk.assets_path}/#{Zendesk.assets_name}.css');</style>
+        <script type='text/javascript' src='#{Zendesk.assets_path}/#{Zendesk.assets_name}.js'></script>).html_safe
+      end
+
+      def zendesk_link_to(text, options = {})
+        return unless Zendesk.enabled?
+        link_to text, support_path, options
+      end
+
+      def zendesk_dropbox_link_to(text)
+        link_to text, '#', :onclick => 'Zenbox.render (); return false'
+      end
+    end
+
+    module Controller
+      def self.included(base)
+        base.before_filter :zendesk_handle_guests, :only => :zendesk_login
+      end
+
+      def zendesk_login
+        name, email = instance_exec(&Zendesk.login).map!(&:force_utf8)
+
+        now  = params[:timestamp] || Time.now.to_i.to_s
+        hash = Digest::MD5.hexdigest(name + email + Zendesk.token + now)
+        back = params[:return_to] || Zendesk.return_url
+
+        auth_params = [
+          '?name='      + CGI.escape(name),
+          '&email='     + CGI.escape(email),
+          '&timestamp=' + now,
+          '&hash='      + hash,
+          '&return_to=' + back
+        ].join.force_utf8
+
+        redirect_to(Zendesk.auth_url + auth_params)
+      end
+
+      def zendesk_logout
+        flash[:notice] = "Thanks for visiting our support forum."
+        redirect_to root_url
+      end
+
+      private
+        def zendesk_handle_guests
+          return if logged_in? rescue false # TODO add another option
+
+          if params[:timestamp] && params[:return_to]
+            # User clicked on Zendesk "login", thus redirect to our
+            # login page, that'll redirect him/her back to Zendesk.
+            #
+            redirect_to send(Zendesk.login_url, :return_to => support_url)
+          else
+            # User clicked on our "support" link, and maybe doesn't
+            # have an account yet: redirect him/her to the support.
+            #
+            redirect_to Zendesk.support_url
+          end
+        end
+    end
+
+    module Routes
+      def zendesk(base, options)
+        return unless Zendesk.enabled?
+
+        self.support base,           :controller => options[:controller], :action => :zendesk_login
+        self.connect "#{base}/exit", :controller => options[:controller], :action => :zendesk_logout
+      end
+    end
+
+  end
+end

data/rails/init.rb

@@ -0,0 +1,5 @@
+require 'panmind/zendesk'
+require 'panmind/string_force_utf8_patch'
+
+ActionView::Base.instance_eval { include Panmind::Zendesk::Helpers }
+ActionController::Routing::RouteSet::Mapper.instance_eval { include Panmind::Zendesk::Routes }

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification 
+name: panmind-zendesk
+version: !ruby/object:Gem::Version 
+  hash: 15
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  version: "1.0"
+platform: ruby
+authors: 
+- Marcello Barnaba
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-17 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rails
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 19
+        segments: 
+        - 2
+        - 3
+        - 8
+        version: 2.3.8
+  type: :runtime
+  version_requirements: *id001
+description: The plugin implements the HTML generation code for the Zendesk dropbox and the necessary controller and routing code to implement remote authentication
+email: vjt@openssl.it
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- README.md
+- Rakefile
+- lib/panmind/string_force_utf8_patch.rb
+- lib/panmind/zendesk.rb
+- rails/init.rb
+has_rdoc: true
+homepage: http://github.com/Panmind/zendesk
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Zendesk on Rails - Dropbox and Remote Authentication
+test_files: []
+