context_help 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in context_help.gemspec
+gemspec

data/README.rdoc

@@ -0,0 +1,17 @@
+= ContextHelp
+
+ContexHelp is a ruby gem for discovering documentable elements in rails applications
+and showing help for them. Currently ContextHelp detects form_tag elements, models and
+attributes in forms rendered by form_for or formtastic, and other html elements rendered
+by *_tag helpers.
+
+== Features
+
+* Autodetection of model and attributes present on a view from formtastic y form_for helpers.
+* Autodetection of html tags rendered by *_tag helpers
+* Custom documentation for custom elements through I18n like routes. Ej: 'en.context_help.custom.tree_view'
+* Basic inline and contextual help HTML renderer
+* Customizable renderers
+* Internationalized text. ContextHelp gets help texts from I18n files.
+
+==

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/context_help.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "context_help/version"
+
+Gem::Specification.new do |s|
+  s.name        = "context_help"
+  s.version     = ContextHelp::VERSION
+  s.authors     = ["Juan Pablo Marzetti"]
+  s.email       = ["jmarzetti@sequre.com.ar"]
+  s.homepage    = "http://sequre.com.ar"
+  s.summary     = %q{A Rails context help facility to offer help about yor models and attributes}
+  s.description = %q{ContextHelp is a gem that allows you to show inline or aside help about every input item found in a form tag, a model, its attributes and even custom help about other HTML tags}
+
+  s.rubyforge_project = "context_help"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/context_help/base.rb

@@ -0,0 +1,181 @@
+module ContextHelp
+  module Base
+    @help_items = []
+    @config = {
+       :show_inline => false,
+       :title_tag => 'h1',
+       :title_class => 'help_title',
+       :text_tag => 'span',
+       :text_class => 'help_text',
+       :level_classes => {
+         :model => 'help_level_1',
+         :model_attribute => 'help_level_2',
+         :html => {
+           :default => 'help_level_2',
+
+           :form => 'help_level_1',
+           :fieldset => 'help_level_2',
+         },
+         :custom => 'help_level_3'
+       },
+       :exclude_tags => [:script, :link, :li],
+       :exclude_models => [],
+       :show_missing => false,
+       :link_to_object => false,
+       :link_to_help => false
+    }
+
+    def self.help_for(options)
+      help_options = options[:context_help]
+      self.help_path_for(help_options)
+      self.inline_help(help_options)
+    end
+    def self.context_help(&block)
+      help = ''
+      @help_items.each do |item|
+        item[:calculated_path] = self.help_path_for(item, false) if !item[:calculated_path]
+        if block_given?
+          help += yield(item)
+        elsif !item[:skip] and item[:calculated_path]
+          help += self.html_help(item)
+        end
+      end
+      help.strip
+    end
+    def self.help_items
+      @help_items
+    end
+    def self.config
+      @config
+    end
+    def self.flush_items
+      @help_items = []
+    end
+    def self.inline_help(options)
+      return '' if options[:skip] or !options[:calculated_path]
+      if options[:inline_help_builder].is_a?(Proc) 
+        options[:inline_help_builder].call(options)
+      elsif options[:show_inline]
+        self.html_help(options)
+      else
+        ''
+      end
+    end
+    def self.help_path_for(options,register=true)
+      path = options[:path]
+      return path if path.is_a?(String)
+
+      ruta = nil
+      if !options[:skip]
+        if path[:model] and @config[:exclude_models].index(path[:model].to_sym).nil?
+          ruta = 'context_help.models.'+model_name(path[:model])
+          options[:pre_level_class] = @config[:level_classes][:model]
+          
+          if (path[:attribute])
+            ruta = ruta + '.attributes.'+ path[:attribute].to_s.underscore
+            options[:pre_level_class] = @config[:level_classes][:model_attribute]
+          end  
+        elsif path[:tag] and @config[:exclude_tags].index(path[:tag].to_sym).nil?
+          ruta = 'context_help.html.'+path[:tag].to_s.downcase
+          ruta = ruta + '.' + path[:tag_options][:id].to_s if path[:tag_options][:id]
+          
+          if @config[:level_classes][:html].include?(path[:tag])
+            options[:pre_level_class] = @config[:level_classes][:html][path[:tag]]
+          else
+            options[:pre_level_class] = @config[:level_classes][:html][:default]
+          end
+        elsif path[:custom]
+          ruta = 'context_help.custom.'+path[:custom]
+          options[:pre_level_class] = @config[:level_classes][:custom]
+        end
+      end
+      if ruta              
+        options[:calculated_path] = ruta if (I18n.t(ruta+'.title', :default => '') != '') or (Rails.env.development? and @config[:show_missing])
+        self.register_item(options) if register
+        return options[:calculated_path]
+      end
+      nil
+    end
+    def self.html_help(options)
+      if options[:help_builder].is_a?(Proc) 
+        options[:help_builder].call(options)
+      elsif options[:calculated_path]
+        title = options[:title] || I18n.t(options[:calculated_path]+'.title')
+        text = options[:text] || I18n.t(options[:calculated_path]+'.text')
+        html = "<#{options[:title_tag]} id=\"#{options[:item_id]}\" class=\"#{options[:title_class]} #{options[:level_class]}\">#{title}</#{options[:title_tag]}>
+        <#{options[:text_tag]} class=\"#{options[:text_class]} #{options[:level_class]}\">#{text}</#{options[:text_tag]}>"
+        html += self.link_to_object(options)
+        html
+      end
+    end
+    def self.link_to_help(options)  
+      if options[:link_to_help_builder].is_a?(Proc)
+        options[:link_to_help_builder].call(options)
+      elsif options[:link_to_help] and !I18n.t(options[:calculated_path]+'.title', :default => {}).is_a?(Hash)
+        "<a href=\"##{options[:item_id]}\" id=\"#{options[:item_id]}_object\" class=\"context_help_link_to_help\">help</a>"
+      else
+        ''
+      end
+    end
+    def self.link_to_object(options)  
+      if options[:link_to_object_builder].is_a?(Proc)
+        options[:link_to_object_builder].call(options)
+      elsif options[:link_to_object]
+        "<a href=\"#link_to_help_#{options[:item_id]}\">help</a>"
+      else
+        ''
+      end
+    end
+    def self.register_item(options)
+      def self.get_option(name, options)
+        return @config[name] if options[:calculated_path].nil?
+        value = I18n.t(options[:calculated_path]+'.'+name.to_s, :default => {})
+        if value.is_a?(Hash)
+          @config[name]
+        else
+          value
+        end
+      end
+      found = false
+      @help_items.each do |item|
+        found = (item[:calculated_path] == options[:calculated_path])
+        break if found
+      end
+      if not found
+        options[:show_inline] ||= get_option(:show_inline, options)
+        options[:title_tag] ||= get_option(:title_tag, options)
+        options[:title_class] ||= get_option(:title_class, options)
+        options[:text_tag] ||= get_option(:text_tag, options)
+        options[:text_class] ||= get_option(:text_class, options)
+        options[:link_to_object] ||= get_option(:link_to_object, options)
+        options[:link_to_help] ||= get_option(:link_to_help, options)
+        options[:level_class] ||= I18n.t(options[:calculated_path]+'.level_class', :default => (options[:pre_level_class] || 'help_level_1'))
+        options[:link_to_help_builder] ||= @config[:link_to_help_builder]
+        options[:link_to_object_builder] ||= @config[:link_to_object_builder]
+        options[:inline_help_builder] ||= @config[:inline_help_builder]
+        options[:help_builder] ||= @config[:help_builder]
+        
+        options[:item_id] = "context_help_item_#{(@help_items.length+1).to_s}"
+        @help_items << options 
+      end
+    end 
+    def self.model_name(model)
+      model = model.to_s.underscore
+      if model =~ /^[a-z][a-z0-9_]*\[[a-z][a-z0-9_]*_attributes\]/
+        model.match(/^[a-z][a-z0-9_]*\[([a-z][a-z0-9_]*)_attributes\]/)[1].singularize
+      else
+        model
+      end
+    end
+    def self.merge_options(base, added)
+      if base.is_a?(Hash) and added.is_a?(Hash)
+        added.each do |key,value|
+          base[key] = self.merge_options(base[key], value)
+        end
+        return base
+      else
+        return base || added
+      end
+    end
+  end
+end

data/lib/context_help/patches/form_helper_patch.rb

@@ -0,0 +1,69 @@
+module ActionView
+  module Helpers
+    module FormHelper
+      def fields_for_with_context_help_fields_for(record_or_name_or_array, *args, &block)
+        case record_or_name_or_array
+        when String, Symbol
+          object_name = record_or_name_or_array
+        else
+          object_name = ActionController::RecordIdentifier.singular_class_name(record_or_name_or_array)
+        end
+
+        options = ContextHelp::Base.merge_options({:context_help => {:path => {:model => object_name.to_sym} } }, args.last.is_a?(::Hash)? args.last : {})
+        help = ContextHelp::Base.help_for(options)
+        help + fields_for_without_context_help_fields_for(record_or_name_or_array, *args, &block)
+      end       
+      def label_with_context_help_label(object_name, method, text = nil, options = {})
+        help_options = ContextHelp::Base.merge_options({:context_help => {:path => {:model => object_name.to_sym, :attribute=> method.to_sym}}}, options)
+        ContextHelp::Base.help_for(help_options)
+        link_to_help = ContextHelp::Base.link_to_help(help_options[:context_help])
+        label_without_context_help_label(object_name, method, text.to_s + link_to_help, options)
+      end
+      def text_field_with_context_help_text_field(object_name, method, options = {})
+        help_options = ContextHelp::Base.merge_options({:context_help => {:path => {:model => object_name.to_sym, :attribute=> method.to_sym}}}, options)
+        help = ContextHelp::Base.help_for(help_options)
+        text_field_without_context_help_text_field(object_name, method, options) + help
+      end
+      def password_field_with_context_help_password_field(object_name, method, options = {})
+        help_options = ContextHelp::Base.merge_options({:context_help => {:path => {:model => object_name.to_sym, :attribute=> method.to_sym}}}, options)
+        help = ContextHelp::Base.help_for(help_options)
+        password_field_without_context_help_password_field(object_name, method, options) + help
+      end
+      def hidden_field_with_context_help_hidden_field(object_name, method, options = {})
+        help_options = ContextHelp::Base.merge_options({:context_help => {:path => {:model => object_name.to_sym, :attribute=> method.to_sym}}}, options)
+        help = ContextHelp::Base.help_for(help_options)
+        hidden_field_without_context_help_hidden_field(object_name, method, options) + help
+      end
+      def file_field_with_context_help_file_field(object_name, method, options = {})
+        help_options = ContextHelp::Base.merge_options({:context_help => {:path => {:model => object_name.to_sym, :attribute=> method.to_sym}}}, options)
+        help = ContextHelp::Base.help_for(help_options)
+        file_field_without_context_help_file_field(object_name, method, options) + help
+      end
+      def text_area_with_context_help_text_area(object_name, method, options = {})
+        help_options = ContextHelp::Base.merge_options({:context_help => {:path => {:model => object_name.to_sym, :attribute=> method.to_sym}}}, options)
+        help = ContextHelp::Base.help_for(help_options)
+        text_area_without_context_help_text_area(object_name, method, options) + help
+      end
+      def check_box_with_context_help_check_box(object_name, method, options = {}, checked_value = "1", unchecked_value = "0")
+        help_options = ContextHelp::Base.merge_options({:context_help => {:path => {:model => object_name.to_sym, :attribute=> method.to_sym}}}, options)
+        help = ContextHelp::Base.help_for(help_options)
+        check_box_without_context_help_check_box(object_name, method, options, checked_value, unchecked_value) + help
+      end
+      def radio_button_with_context_help_radio_button(object_name, method, tag_value, options = {})
+        help_options = ContextHelp::Base.merge_options({:context_help => {:path => {:model => object_name.to_sym, :attribute=> method.to_sym}}}, options)
+        help = ContextHelp::Base.help_for(help_options)
+        radio_button_without_context_help_radio_button(object_name, method, tag_value, options) +help
+      end
+
+      alias_method_chain :fields_for, :context_help_fields_for
+      alias_method_chain :label, :context_help_label
+      alias_method_chain :text_field, :context_help_text_field
+      alias_method_chain :password_field, :context_help_password_field
+      alias_method_chain :hidden_field, :context_help_hidden_field
+      alias_method_chain :file_field, :context_help_file_field
+      alias_method_chain :text_area, :context_help_text_area
+      alias_method_chain :check_box, :context_help_check_box
+      alias_method_chain :radio_button, :context_help_radio_button
+    end
+  end
+end

data/lib/context_help/patches/formtastic_patch.rb

@@ -0,0 +1,27 @@
+module ContextHelp
+  class SemanticFormBuilder < Formtastic::SemanticFormBuilder
+    def inputs(*args, &block)
+      title = field_set_title_from_args(*args)
+      html_options = args.extract_options!
+      help_options = ContextHelp::Base.merge_options({:context_help => {:path => {:tag => 'fieldset', :tag_options => html_options}}}, html_options)
+      help_options[:context_help][:title] = title if help_options[:context_help][:path][:tag]
+      help = ContextHelp::Base.help_for(help_options)
+      super *(args<<help_options), &block
+    end
+    def input(method, options = {})   
+      options = ContextHelp::Base.merge_options({:context_help => {:path => {:model => model_name.to_sym, :attribute=> method.to_sym}}}, options || {})
+      html = super
+    end
+    def legend_tag(method, options = {})
+      if options[:label] == false
+        Formtastic::Util.html_safe("")
+      else
+        text = localized_string(method, options[:label], :label) || humanized_attribute_name(method)
+        text += required_or_optional_string(options.delete(:required))
+        text = Formtastic::Util.html_safe(text)
+        text += ContextHelp::Base.link_to_help(options[:context_help])
+        template.content_tag :legend, template.label_tag(nil, text, :for => nil), :class => :label
+      end
+    end
+  end
+end

data/lib/context_help/patches/tag_helper_patch.rb

@@ -0,0 +1,19 @@
+module ActionView
+  module Helpers
+    module TagHelper
+      def tag_with_context_help_tag(name, options = {}, open = false, escape = true)
+        help_options = ContextHelp::Base.merge_options({:context_help => {:path => {:tag => name.to_sym, :tag_options => options}}}, options)
+        help = ContextHelp::Base.help_for(help_options)
+        tag_without_context_help_tag(name, options, open, escape) + help
+      end
+      def content_tag_with_context_help_content_tag(name, content_or_options_with_block = nil, options = {}, escape = true, &block)
+        help_options = ContextHelp::Base.merge_options({:context_help => {:path => {:tag => name.to_sym, :tag_options => options}}}, options)
+        help = ContextHelp::Base.help_for(help_options)
+        html = content_tag_without_context_help_content_tag(name, content_or_options_with_block, options, escape, &block) + help
+      end
+
+      alias_method_chain :tag, :context_help_tag
+      alias_method_chain :content_tag, :context_help_content_tag
+    end
+  end
+end

data/lib/context_help/version.rb

@@ -0,0 +1,3 @@
+module ContextHelp
+  VERSION = "0.0.1"
+end

data/lib/context_help.rb

@@ -0,0 +1,7 @@
+require 'context_help/patches/tag_helper_patch'
+require 'context_help/patches/form_helper_patch'
+require 'context_help/patches/formtastic_patch'
+require "context_help/version"
+require 'context_help/base'
+
+Formtastic::SemanticFormHelper.builder = ContextHelp::SemanticFormBuilder if defined?(Formtastic)

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: context_help
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Juan Pablo Marzetti
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-08-10 00:00:00.000000000 -03:00
+default_executable: 
+dependencies: []
+description: ContextHelp is a gem that allows you to show inline or aside help about
+  every input item found in a form tag, a model, its attributes and even custom help
+  about other HTML tags
+email:
+- jmarzetti@sequre.com.ar
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.rdoc
+- Rakefile
+- context_help.gemspec
+- lib/context_help.rb
+- lib/context_help/base.rb
+- lib/context_help/patches/form_helper_patch.rb
+- lib/context_help/patches/formtastic_patch.rb
+- lib/context_help/patches/tag_helper_patch.rb
+- lib/context_help/version.rb
+has_rdoc: true
+homepage: http://sequre.com.ar
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: context_help
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: A Rails context help facility to offer help about yor models and attributes
+test_files: []