josevalim-rails-footnotes 3.3.1

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2006 Coda Hale
+Copyright (c) 2008 José Valim (jose.valim at gmail dot com)
+
+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

@@ -0,0 +1,147 @@
+Copyright (c) 2008 José Valim (jose.valim at gmail dot com)
+Site: http://www.pagestacker.com/
+Blog: http://josevalim.blogspot.com/
+License: MIT
+Version: 3.3.1
+
+You can also read this README in pretty html at the GitHub project Wiki page
+
+  http://github.com/josevalim/rails-footnotes/wikis/home
+
+
+Description
+-----------
+
+If you are developing in Rails you should know the plugin! It displays
+footnotes in your application for easy debugging, such as sessions,
+request parameters, cookies, filter chain, routes, queries, etc.
+
+Even more, it contains links to open files directly in your editor including
+your backtrace lines.
+
+
+Installation
+------------
+
+Install Rails Footnotes is very easy. It is stored in GitHub, so if you
+have never installed a gem via GitHub run the following:
+
+  gem sources -a http://gems.github.com
+
+Then install the gem:
+
+  sudo gem install josevalim-rails-footnotes
+
+In RAILS_ROOT/config/environments/development.rb (yes, you want it only in development):
+
+  config.gem "josevalim-rails-footnotes",  :lib => "rails-footnotes", :source => "http://gems.github.com"
+
+If you want it as plugin, just do:
+
+    cd myapp
+    git clone git://github.com/josevalim/rails-footnotes.git
+    rm -rf vendor/plugins/rails-footnotes/.git
+
+
+Configuration
+-------------
+
+If you are not using Textmate as text editor, in your environment.rb or
+in an initializer do:
+
+  if defined?(Footnotes)
+    Footnotes::Filter.prefix = 'txmt://open?url=file://%s&line=%d&column=%d'
+  end
+
+Where you are going to choose a prefix compatible with your text editor. The %s is
+replaced by the name of the file, the first %d is replaced by the line number and
+the second %d is replaced by the column. You can also enable this behaviour in other
+following the steps in the link below:
+
+  http://josevalim.blogspot.com/2008/06/textmate-protocol-behavior-on-any.html
+
+By default, footnotes are appended at the end of the page with default stylesheet. If you want
+to change their position, you can define a div with id "footnotes_holder" or define your own stylesheet
+by turning footnotes stylesheet off:
+
+  Footnotes::Filter.no_style = true
+
+Another option is to allow multiple notes to be opened at the same time:
+
+  Footnotes::Filter.multiple_notes = true
+
+Finally, you can control which notes you want to show. The default are:
+
+  Footnotes::Filter.notes = [:session, :cookies, :params, :filters, :routes, :env, :queries, :log, :general]
+
+
+Early versions
+--------------
+
+If you are running on Rails 2.1.x, you should use Footnotes v3.2.2:
+
+    cd myapp
+    git clone git://github.com/josevalim/rails-footnotes.git
+    cd vendor/plugins/rails-footnotes
+    git checkout v3.2.2
+    rm -rf ./.git
+
+If you are using earlier than 2.1, please upgrade your app. =)
+
+
+Creating your own notes
+-----------------------
+
+Create your notes to integrate with Footnotes is easy.
+
+1. Create a Footnotes::Notes::YourExampleNote class
+
+2. Implement the necessary methods (check abstract_note.rb file in lib/notes)
+
+3. Append your example note in Footnotes::Filter.notes array (usually at the end of your environment file or in an initializer):
+
+For example, to create a note that shows info about the user logged in your application you just have to do:
+
+  module Footnotes
+    module Notes
+      class CurrentUserNote < AbstractNote
+        # This method always receives a controller
+        #
+        def initialize(controller)
+          @current_user = controller.instance_variable_get("@current_user")
+        end
+
+        # The name that will appear as legend in fieldsets
+        #
+        def legend
+          "Current user: #{@current_user.name}"
+        end
+
+        # This Note is only valid if we actually found an user
+        # If it's not valid, it won't be displayed
+        #
+        def valid?
+          @current_user
+        end
+
+        # The fieldset content
+        #
+        def content
+          escape(@current_user.inspect)
+        end
+      end
+    end
+  end
+
+Then put in your environment:
+
+  Footnotes::Filter.notes += [:current_user]
+
+
+Who?
+----
+
+Until version 2.0, this plugin was created and maintained by:
+
+Duane Johnson (duane.johnson@gmail.com)
+http://blog.inquirylabs.com/

data/Rakefile

@@ -0,0 +1,18 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Test Footnotes plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for Footnotes plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'SimpleLocalization'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/init.rb

@@ -0,0 +1,14 @@
+# Footnotes is divided in three main files:
+#
+#  * loader.rb: Initialize the plugin and apply the footnotes as an after_filter;
+#
+#  * footnotes.rb: Is the core and adds the debug options at the bottom of each page;
+#
+#  * backtracer.rb: Append links to your favorite editor in backtraces.
+#
+if RAILS_ENV == 'development'
+  dir = File.dirname(__FILE__)
+  require File.join(dir,'lib','footnotes')
+  require File.join(dir,'lib','loader')
+  require File.join(dir,'lib','backtracer')
+end

data/lib/backtracer.rb

@@ -0,0 +1,34 @@
+module Footnotes
+  module Extensions
+    module Exception
+      def self.included(base)
+        base.class_eval do
+          alias_method_chain :clean_backtrace, :links
+        end
+      end
+
+      def add_links_to_backtrace(lines)
+        lines.collect do |line|
+          expanded = line.gsub('#{RAILS_ROOT}', RAILS_ROOT)
+          if match = expanded.match(/^(.+):(\d+):in/) || match = expanded.match(/^(.+):(\d+)\s*$/)
+            file = File.expand_path(match[1])
+            line_number = match[2]
+            html = %[<a href="#{Footnotes::Filter.prefix(file, line_number, 1)}">#{line}</a>]
+          else
+            line
+          end
+        end
+      end
+
+      def clean_backtrace_with_links
+        unless ::Footnotes::Filter.prefix.blank?
+          add_links_to_backtrace(clean_backtrace_without_links)
+        else
+          clean_backtrace_without_links
+        end
+      end
+    end
+  end
+end
+
+Exception.send :include, Footnotes::Extensions::Exception

data/lib/footnotes.rb

@@ -0,0 +1,310 @@
+module Footnotes
+  class Filter
+    @@no_style = false
+    @@multiple_notes = false
+    @@klasses = []
+
+    # Default link prefix is textmate
+    @@prefix = 'txmt://open?url=file://%s&line=%d&column=%d'
+
+    # Edit notes
+    @@notes = [ :controller, :view, :layout, :stylesheets, :javascripts ]
+    # Show notes
+    @@notes += [ :session, :cookies, :params, :filters, :routes, :env, :queries, :log, :general ]
+
+    # :no_style       => If you don't want the style to be appended to your pages
+    # :notes          => Class variable that holds the notes to be processed
+    # :prefix         => Prefix appended to FootnotesLinks
+    # :multiple_notes => Set to true if you want to open several notes at the same time
+    cattr_accessor :no_style, :notes, :prefix, :multiple_notes
+
+    class << self
+      # Method called to start the notes
+      # It's a before filter prepend in the controller
+      #
+      def before(controller)
+        Footnotes::Filter.start!(controller)
+      end
+
+      # Method that calls Footnotes to attach its contents
+      #
+      def after(controller)
+        filter = Footnotes::Filter.new(controller)
+        filter.add_footnotes!
+        filter.close!(controller)
+      end
+
+      # Calls the class method start! in each note
+      # Sometimes notes need to set variables or clean the environment to work properly
+      # This method allows this kind of setup
+      #
+      def start!(controller)
+        @@klasses = []
+
+        each_with_rescue(@@notes.flatten) do |note|
+          klass = "Footnotes::Notes::#{note.to_s.camelize}Note".constantize
+          klass.start!(controller) if klass.respond_to?(:start!)
+          @@klasses << klass
+        end
+      end
+
+      # Process notes, discarding only the note if any problem occurs
+      #
+      def each_with_rescue(notes)
+        delete_me = []
+
+        notes.each do |note|
+          begin
+            yield note
+          rescue Exception => e
+            # Discard note if it has a problem
+            log_error("Footnotes #{note.to_s.camelize}Note Exception", e)
+            delete_me << note
+            next
+          end
+        end
+
+        delete_me.each{ |note| notes.delete(note) }
+        return notes
+      end
+
+      # Logs the error using specified title and format
+      #
+      def log_error(title, exception)
+        RAILS_DEFAULT_LOGGER.error "#{title}: #{exception}\n#{exception.backtrace.join("\n")}"
+      end
+
+      # If none argument is sent, simply return the prefix.
+      # Otherwise, replace the args in the prefix.
+      #
+      def prefix(*args)
+        if args.empty?
+          @@prefix
+        else
+          format(@@prefix, *args)
+        end
+      end
+
+    end
+
+    def initialize(controller)
+      @controller = controller
+      @template = controller.instance_variable_get(:@template)
+      @body = controller.response.body
+      @notes = []
+    end
+
+    def add_footnotes!
+      add_footnotes_without_validation! if valid?
+    rescue Exception => e
+      # Discard footnotes if there are any problems
+      self.class.log_error("Footnotes Exception", e)
+    end
+
+    # Calls the class method close! in each note
+    # Sometimes notes need to finish their work even after being read
+    # This method allows this kind of work
+    #
+    def close!(controller)
+      each_with_rescue(@@klasses) do |klass|
+        klass.close!(controller)
+      end
+    end
+
+    protected
+      def valid?
+        performed_render? && first_render? && valid_format? && valid_content_type? && @body.is_a?(String) && !component_request? && !xhr?
+      end
+
+      def add_footnotes_without_validation!
+        initialize_notes!
+        insert_styles unless @@no_style
+        insert_footnotes
+      end
+
+      def initialize_notes!
+        each_with_rescue(@@klasses) do |klass|
+          note = klass.new(@controller)
+          @notes << note if note.respond_to?(:valid?) && note.valid?
+        end
+      end
+
+      def performed_render?
+        @controller.instance_variable_get(:@performed_render)
+      end
+
+      def first_render?
+        @template.instance_variable_get(:@_first_render)
+      end
+
+      def valid_format?
+        [:html,:rhtml,:xhtml,:rxhtml].include?(@template.template_format.to_sym)
+      end
+
+      def valid_content_type?
+        c = @controller.response.headers['Content-Type'].to_s
+        (c.empty? || c =~ /html/)
+      end
+
+      def component_request?
+        @controller.instance_variable_get(:@parent_controller)
+      end
+
+      def xhr?
+        @controller.request.xhr?
+      end
+
+      #
+      # Insertion methods
+      #
+
+      def insert_styles
+        insert_text :before, /<\/head>/i, <<-HTML
+        <!-- Footnotes Style -->
+        <style type="text/css">
+          #footnotes_debug {margin: 2em 0 1em 0; text-align: center; color: #444; line-height: 16px;}
+          #footnotes_debug a {text-decoration: none; color: #444; line-height: 18px;}
+          #footnotes_debug table {text-align: center;}
+          #footnotes_debug table td {padding: 0 5px;}
+          #footnotes_debug tbody {text-align: left;}
+          #footnotes_debug legend {background-color: #FFF;}
+          #footnotes_debug fieldset {text-align: left; border: 1px dashed #aaa; padding: 0.5em 1em 1em 1em; margin: 1em 2em; color: #444; background-color: #FFF;}
+          /* Aditional Stylesheets */
+          #{@notes.map(&:stylesheet).compact.join("\n")}
+        </style>
+        <!-- End Footnotes Style -->
+        HTML
+      end
+
+      def insert_footnotes
+        # Fieldsets method should be called first
+        content = fieldsets
+
+        footnotes_html = <<-HTML
+        <!-- Footnotes -->
+        <div style="clear:both"></div>
+        <div id="footnotes_debug">
+          #{links}
+          #{content}
+          <script type="text/javascript">
+            function footnotes_close(){
+              #{close unless @@multiple_notes}
+            }
+            function footnotes_toogle(id){
+              s = document.getElementById(id).style;
+              before = s.display;
+              footnotes_close();
+              s.display = (before != 'block') ? 'block' : 'none'
+              location.href = '#footnotes_debug';
+            }
+            /* Additional Javascript */
+            #{@notes.map(&:javascript).compact.join("\n")}
+          </script>
+        </div>
+        <!-- End Footnotes -->
+        HTML
+
+        if @body =~ %r{<div[^>]+id=['"]footnotes_holder['"][^>]*>}
+          # Insert inside the "footnotes_holder" div if it exists
+          insert_text :after, %r{<div[^>]+id=['"]footnotes_holder['"][^>]*>}, footnotes_html
+        else
+          # Otherwise, try to insert as the last part of the html body
+          insert_text :before, /<\/body>/i, footnotes_html
+        end
+      end
+
+      # Process notes to gets their links in their equivalent row
+      #
+      def links
+        links = Hash.new([])
+        order = []
+        each_with_rescue(@notes) do |note|
+          order << note.row
+          links[note.row] += [link_helper(note)]
+        end
+
+        html = ''
+        order.uniq!
+        order.each do |row|
+          html << "#{row.is_a?(String) ? row : row.to_s.camelize}: #{links[row].join(" | \n")}<br />"
+        end
+        html
+      end
+
+      # Process notes to get their content
+      #
+      def fieldsets
+        content = ''
+        each_with_rescue(@notes) do |note|
+          next unless note.has_fieldset?
+          content << <<-HTML
+            <fieldset id="#{note.to_sym}_debug_info" style="display: none">
+              <legend>#{note.legend}</legend>
+              <div>#{note.content}</div>
+            </fieldset>
+          HTML
+        end
+        content
+      end
+
+      # Process notes to get javascript code to close them.
+      # This method is only used when multiple_notes is false.
+      #
+      def close
+        javascript = ''
+        each_with_rescue(@notes) do |note|
+          next unless note.has_fieldset?
+          javascript << close_helper(note)
+        end
+        javascript
+      end
+
+      #
+      # Helpers
+      #
+
+      # Helper that creates the javascript code to close the note
+      #
+      def close_helper(note)
+        "document.getElementById('#{note.to_sym}_debug_info').style.display = 'none'\n"
+      end
+
+      # Helper that creates the link and javascript code when note is clicked
+      #
+      def link_helper(note)
+        onclick = note.onclick
+        unless href = note.link
+          href = '#'
+          onclick ||= "footnotes_toogle('#{note.to_sym}_debug_info');return false;" if note.has_fieldset?
+        end
+
+        "<a href=\"#{href}\" onclick=\"#{onclick}\">#{note.title}</a>"
+      end
+
+      # Inserts text in to the body of the document
+      # +pattern+ is a Regular expression which, when matched, will cause +new_text+
+      # to be inserted before or after the match.  If no match is found, +new_text+ is appended
+      # to the body instead. +position+ may be either :before or :after
+      #
+      def insert_text(position, pattern, new_text)
+        index = case pattern
+          when Regexp
+            if match = @body.match(pattern)
+              match.offset(0)[position == :before ? 0 : 1]
+            else
+              @body.size
+            end
+          else
+            pattern
+          end
+        @body.insert index, new_text
+      end
+
+      # Instance each_with_rescue method
+      # 
+      def each_with_rescue(*args, &block)
+        self.class.each_with_rescue(*args, &block)
+      end
+
+  end
+end