vjt-zendesk 1.2.0

data/README.md

@@ -0,0 +1,127 @@
+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
+------------
+
+In Gemfile
+
+    gem 'vjt-zendesk', :require => 'zendesk'
+
+Configuration
+-------------
+
+In your `config/routes.rb`:
+
+    zendesk :on => '/support', :controller => 'root'
+
+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.
+
+Finally, in your config/application.rb:
+
+    config.zendesk = {
+      :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/vjt/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.
+
+[Panmind](http://panmind.com), where this project originated, is doing
+this, 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.
+
+
+Compatibility
+-------------
+
+Tested with Rails 3.0.x running under Ruby 1.9.2.
+
+
+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
+ * Allow options passing to the `zendesk_dropbox_link_to` helper
+ * Code documentation
+ * 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/zendesk/version'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name             = 'vjt-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/vjt/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          = Zendesk::Version
+    gemspec.date             = '2010-11-23'
+
+    gemspec.require_path     = 'lib'
+
+    gemspec.add_dependency('rails', '~> 3.0')
+  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/zendesk.rb

@@ -0,0 +1,72 @@
+require 'zendesk/controller'
+require 'zendesk/helpers'
+require 'zendesk/routing'
+require 'zendesk/version'
+require 'zendesk/railtie'
+
+# 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.
+# (C) 2011 vjt@openssl.it
+#
+#   - vjt  Wed May 18 23:01:09 CEST 2011
+#
+module Zendesk
+  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, :js_asset_path, :js_asset_name, :css_asset_path, :css_asset_name
+
+    def check_configuration!
+      options = Rails.application.config.zendesk rescue nil
+
+      bail "Zendesk configuration missing: please define config.zendesk" unless options.present?
+
+      self.token, self.hostname, self.login, self.login_url =
+        options.values_at(:token, :hostname, :login, :login_url)
+
+      bail "API token is missing"             unless self.token.present?
+      bail "Support hostname is missing"      unless self.hostname.present?
+      bail "Login proc is missing"            unless self.login.present?
+      bail "Login URL named route is missing" unless self.login_url.present?
+
+      # Dropbox specific customizations, defaults in place
+      self.dropbox = (options[:dropbox] || {}).reverse_merge(
+        :dropboxID => 'feedback',
+        :url       => Zendesk.hostname
+      ).freeze
+
+      # Path and name for css and asset required for zenbox 2.0
+      self.js_asset_path  = options[:js_asset_path]  || '//assets0.zendesk.com/external/zenbox'
+      self.js_asset_name  = options[:js_asset_name]  || 'zenbox-2.0'
+      self.css_asset_path = options[:css_asset_path] || '//assets0.zendesk.com/external/zenbox'
+      self.css_asset_name = options[:css_asset_name] || 'zenbox-2.0'
+    end
+
+    def enabled?
+      # FIXME we should not disable this code in the
+      # test environment, rather test it appropriately
+      Rails.env.production? || Rails.env.development?
+    end
+
+    private
+      def token=(token);       @token    = token.freeze    rescue nil end
+      def hostname=(hostname); @hostname = hostname.freeze            end
+
+      def bail(message)
+        raise ConfigurationError, message
+      end
+  end
+
+end

data/lib/zendesk/controller.rb

@@ -0,0 +1,53 @@
+require 'digest/md5'
+
+module Zendesk
+
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      before_filter :zendesk_handle_guests, :only => :zendesk_login
+    end
+
+    def zendesk_login
+      name, email = instance_exec(&Zendesk.login)
+
+      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
+
+      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
+
+end

data/lib/zendesk/helpers.rb

@@ -0,0 +1,32 @@
+module Zendesk
+
+  module Helpers
+    def zendesk_dropbox_config
+      config = Zendesk.dropbox
+
+      [:requester_email, :requester_name].each do |key|
+        config = config.merge(key => instance_exec(&config[key])) if config[key].kind_of?(Proc)
+      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' media='screen,projection'>@import url('#{Zendesk.css_asset_path}/#{Zendesk.css_asset_name}.css');</style>
+      <script type='text/javascript' src='#{Zendesk.js_asset_path}/#{Zendesk.js_asset_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
+
+end

data/lib/zendesk/railtie.rb

@@ -0,0 +1,20 @@
+require 'zendesk'
+
+module Zendesk
+
+  class Railtie < Rails::Railtie
+    initializer 'zendesk.insert_into_action_view' do
+      ActiveSupport.on_load :action_view do
+        ActionView::Base.instance_eval { include Zendesk::Helpers }
+        ActionDispatch::Routing::Mapper.instance_eval { include Zendesk::Routing }
+      end
+    end
+
+    initializer 'zendesk.check_configuration' do
+      ActiveSupport.on_load :after_initialize do
+        Zendesk.check_configuration!
+      end
+    end
+  end
+
+end

data/lib/zendesk/routing.rb

@@ -0,0 +1,24 @@
+module Zendesk
+
+  module Routing
+    def zendesk(options = {})
+      return unless Zendesk.enabled?
+
+      base = options[:on] || '/zendesk'
+      ctrl = options[:controller]
+
+      unless ctrl.present?
+        raise ConfigurationError, "Missing :controller option"
+      end
+
+      scope base.to_s, :controller => ctrl do
+        get '/',     :action => :zendesk_login,  :as => base.to_sym
+        get '/exit', :action => :zendesk_logout, :as => nil
+      end
+
+      # Install the methods into the given controller
+      "#{ctrl.camelize}Controller".constantize.instance_eval { include Controller }
+    end
+  end
+
+end

data/lib/zendesk/version.rb

@@ -0,0 +1,3 @@
+module Zendesk
+  Version = '1.2.0'
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification 
+name: vjt-zendesk
+version: !ruby/object:Gem::Version 
+  hash: 31
+  prerelease: 
+  segments: 
+  - 1
+  - 2
+  - 0
+  version: 1.2.0
+platform: ruby
+authors: 
+- Marcello Barnaba
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-23 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: 7
+        segments: 
+        - 3
+        - 0
+        version: "3.0"
+  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/zendesk.rb
+- lib/zendesk/controller.rb
+- lib/zendesk/helpers.rb
+- lib/zendesk/railtie.rb
+- lib/zendesk/routing.rb
+- lib/zendesk/version.rb
+has_rdoc: true
+homepage: http://github.com/vjt/zendesk
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+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.4.1
+signing_key: 
+specification_version: 3
+summary: Zendesk on Rails - Dropbox and Remote Authentication
+test_files: []
+