tiny_mce_helper 0.0.1

data/CHANGELOG

@@ -0,0 +1,13 @@
+*SVN*
+
+*0.0.1* (August 20th, 2007)
+
+* Add README documentation
+
+* Add tiny_mce:uninstall and tiny_mce:update rake tasks
+
+* Add working unit tests
+
+* Add installation and uninstallation scripts
+
+* Add rake tasks tiny_mce:install and tiny_mce:update_options

data/README

@@ -0,0 +1,178 @@
+= tiny_mce_helper
+
+tiny_mce_helper adds helper methods for creating the TinyMCE initialization
+script.
+
+== Resources
+
+API
+
+* http://api.pluginaweek.org/tiny_mce_helper
+
+Wiki
+
+* http://wiki.pluginaweek.org/Tiny_mce_helper
+
+Announcement
+
+* http://www.pluginaweek.org/
+
+Source
+
+* http://svn.pluginaweek.org/trunk/plugins/action_pack/tiny_mce_helper
+
+Development
+
+* http://dev.pluginaweek.org/browser/trunk/plugins/action_pack/tiny_mce_helper
+
+== Requirements
+
+Currently, you must be running a version of Linux in order to run the rake
+tasks.
+
+== Description
+
+TinyMCE is a rich text editor written in Javascript.  This helper plugin helps
+make it easier to validate your code and include the TinyMCE initialization
+script.  It also provides various tasks for installing/updating TinyMCE.
+
+=== Installing TinyMCE
+
+To install TinyMCE, you can use the tiny_mce:install task.  This will download
+the latest version (or one specified by you) from Sourceforge and extract it
+into your application's public/javascripts folder.
+
+For example, to install the latest version:
+
+  $ rake tiny_mce:install
+  (in /my/project)
+  Downloading TinyMCE source...
+  Extracting...
+  Done!
+
+To install a custom version:
+
+  $ rake tiny_mce:install VERSION=2.0.8
+  (in /my/project)
+  Downloading TinyMCE source...
+  Extracting...
+  Done!
+
+If tinymce already exists in your application's public/javascript folder, the
+rake task will prompt you as to whether or not it should be overwritten:
+
+  $ rake tiny_mce:install
+  (in /my/project)
+  TinyMCE already be installed in /my/project/config/../public/javascripts/tinymce. Overwrite? (y/n): y
+  Downloading TinyMCE source...
+  Extracting...
+  Done!
+
+=== Updating TinyMCE
+
+If you have already installed TinyMCE and wish to update to the latest version,
+you can run the tiny_mce:update task.  This will overwrite the current TinyMCE
+installation and WILL NOT prompt you if the folder already exists.  For example,
+
+  $ rake tiny_mce:update
+  (in /my/project)
+  Downloading TinyMCE source...
+  Extracting...
+  Done!
+
+Like tiny_mce:install, you can also specify a custom version:
+
+  $ rake tiny_mce:update VERSION=2.0.9
+  (in /my/project)
+  Downloading TinyMCE source...
+  Extracting...
+  Done!
+
+=== Updating configuration options
+
+In addition to installing the Javascript source, tiny_mce_helper is also able to
+validate the options that are passed in to initialize TinyMCE.  Since these
+options can change over time, a configuration file is generated based on
+information from the TinyMCE wiki.  This configuration file contains a list of
+all of the current possible options that can be specified.
+
+For example, to create a new configuration file:
+
+  $ rake tiny_mce:update VERSION=2.0.9
+  (in /my/project)
+  Downloading configuration options from TinyMCE Wiki...
+  Done!
+
+This will create config/tiny_mce_options.yml.  The content of the configuration
+should look similar to:
+
+  --- 
+  - accessibility_focus
+  - accessibility_warnings
+  - add_form_submit_trigger
+  - add_unload_trigger
+  - apply_source_formatting
+  - ask
+  - auto_focus
+  - auto_reset_designmode
+  - auto_resize
+  - browsers
+  - button_tile_map
+  - cleanup
+  - cleanup_callback
+  - cleanup_on_startup
+  - cleanup_serializer
+  ...
+
+=== Uninstalling TinyMCE
+
+Uninstalling TinyMCE will remove the javascript source and the configuration
+options.  To invoke the installation, run the rake task tiny_mce:uninstall.
+
+  $ rake tiny_mce:uninstall
+  (in /my/project)
+
+=== Creating TinyMCE script
+
+To create the TinyMCE initialization script:
+
+application.rhtml:
+  <%=
+    tiny_mce_init_script(
+      :theme => 'advanced',
+      :editor_selector => 'rich_text',
+      :content_css => '/stylesheets/tiny_mce_content.css',
+      :editor_css => '/stylesheets/tiny_mce_editor.css',
+      :auto_reset_designmode => true
+    )
+  %>
+
+will generate the following javascript:
+
+  tinyMCE.init({
+    'mode' : 'textareas',
+    'theme' : 'advanced',
+    'editor_selected' : 'rich_text',
+    'content_css' : '/stylesheets/tiny_mce_content.css'
+  });
+
+To see additional initialization helpers, see the API for PluginAWeek::Helpers::TinyMCEHelper
+
+== Testing
+
+Since the rake tasks for installing TinyMCE and updating the configuration
+options are part of the unit tests, already-downloaded files are included with
+the plugin.  If you want to perform a "live" test which actually downloads the
+files off the Internet (rather than using the local versions), you must set
+the LIVE environment variable to true.  For example,
+
+  rake test LIVE=true
+
+== References
+
+This plugin provides for the installation and utilization of TinyMCE in Ruby on
+Rails applications. TinyMCE is a WYSIWYG HTML editing component  released under
+the GNU Public License (GPL) by Moxiecode Systems (http://tinymce.moxiecode.com/).
+
+This plugin was originally created by by Blake Watters <blake@near-time.com> and
+later modified by Aaron Pfeifer & Neil Abraham.

data/Rakefile

@@ -0,0 +1,80 @@
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/contrib/sshpublisher'
+
+PKG_NAME           = 'tiny_mce_helper'
+PKG_VERSION        = '0.0.1'
+PKG_FILE_NAME      = "#{PKG_NAME}-#{PKG_VERSION}"
+RUBY_FORGE_PROJECT = 'pluginaweek'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the tiny_mce_helper plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the tiny_mce_helper plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'TinyMCEHelper'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+spec = Gem::Specification.new do |s|
+  s.name            = PKG_NAME
+  s.version         = PKG_VERSION
+  s.platform        = Gem::Platform::RUBY
+  s.summary         = 'Adds helper methods for creating the TinyMCE initialization script.'
+  
+  s.files           = FileList['{lib,tasks,test}/**/*'].to_a + %w(CHANGELOG init.rb install.rb Rakefile README uninstall.rb)
+  s.require_path    = 'lib'
+  s.autorequire     = 'tiny_mce_helper'
+  s.has_rdoc        = true
+  s.test_files      = Dir['test/**/*_test.rb']
+  s.add_dependency  'actionpack', '>= 1.13.1'
+  
+  s.author          = 'Aaron Pfeifer, Neil Abraham'
+  s.email           = 'info@pluginaweek.org'
+  s.homepage        = 'http://www.pluginaweek.org'
+end
+  
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+desc 'Publish the beta gem'
+task :pgem => [:package] do
+  Rake::SshFilePublisher.new('pluginaweek@pluginaweek.org', '/home/pluginaweek/gems.pluginaweek.org/gems', 'pkg', "#{PKG_FILE_NAME}.gem").upload
+end
+
+desc 'Publish the API documentation'
+task :pdoc => [:rdoc] do
+  Rake::SshDirPublisher.new('pluginaweek@pluginaweek.org', "/home/pluginaweek/api.pluginaweek.org/#{PKG_NAME}", 'rdoc').upload
+end
+
+desc 'Publish the API docs and gem'
+task :publish => [:pdoc, :release]
+
+desc 'Publish the release files to RubyForge.'
+task :release => [:gem, :package] do
+  require 'rubyforge'
+  
+  ruby_forge = RubyForge.new
+  ruby_forge.login
+  
+  %w( gem tgz zip ).each do |ext|
+    file = "pkg/#{PKG_FILE_NAME}.#{ext}"
+    puts "Releasing #{File.basename(file)}..."
+    
+    ruby_forge.add_release(RUBY_FORGE_PROJECT, PKG_NAME, PKG_VERSION, file)
+  end
+end

data/init.rb

@@ -0,0 +1 @@
+require 'tiny_mce_helper'

data/install.rb

@@ -0,0 +1,7 @@
+# Install TinyMCE
+puts 'Installing TinyMCE...'
+PluginAWeek::Helpers::TinyMCEHelper.install(:version => ENV['VERSION'], :target => ENV['TARGET'])
+
+# Update the configuration options
+puts 'Updating TinyMCE configuration options...'
+PluginAWeek::Helpers::TinyMCEHelper.update_options

data/lib/tiny_mce_helper.rb

@@ -0,0 +1,244 @@
+module PluginAWeek #:nodoc:
+  module Helpers #:nodoc:
+    # Adds helper methods for generating the TinyMCE initialization script
+    # within your Rails views
+    module TinyMCEHelper
+      # The path to the file which contains all valid options that can be used
+      # to configure TinyMCE
+      OPTIONS_FILE_PATH = "#{RAILS_ROOT}/config/tiny_mce_options.yml"
+      
+      # A regular expression matching options that are dynamic (i.e. they can
+      # vary on an integer or string basis)
+      DYNAMIC_OPTIONS = /theme_advanced_buttons|theme_advanced_container/
+      
+      # Whether or not to use verbose output
+      mattr_accessor :verbose
+      @@verbose = true
+      
+      # A list of all valid options that can be used to configure TinyMCE
+      mattr_accessor :valid_options
+      @@valid_options = File.exists?(OPTIONS_FILE_PATH) ? File.open(OPTIONS_FILE_PATH) {|f| YAML.load(f.read)} : []
+      
+      class << self
+        # Installs TinyMCE by downloading it and adding it to your application's
+        # javascripts folder.
+        # 
+        # == Versions
+        # 
+        # By default, this will install the latest version of TinyMCE.  You can
+        # install a specific version of TinyMCE (if you are using an old API) by
+        # passing in the version number.
+        # 
+        # For example,
+        #   PluginAWeek::Helpers::TinyMCEHelper.install           #=> Installs the latest version
+        #   PluginAWeek::Helpers::TinyMCEHelper.install('2.0.8')  #=> Installs version 2.0.8
+        # 
+        # An exception will be raised if the specified version cannot be found.
+        # 
+        # == Target path
+        # 
+        # By default, this will install TinyMCE into RAILS_ROOT/public/javascripts/tinymce.
+        # If you want to install it to a different directory, you can pass in
+        # a parameter with the relative path from RAILS_ROOT.
+        # 
+        # For example,
+        #   PluginAWeek::Helpers::TinyMCEHelper.install(nil, 'public/javascripts/richtext')
+        def install(options = {})
+          options.assert_valid_keys(:version, :target, :force)
+          options.reverse_merge!(:force => false)
+          
+          version = options[:version]
+          base_target = options[:target] || 'public/javascripts/tinymce'
+          source_path = 'tinymce'
+          target_path = File.expand_path(File.join(RAILS_ROOT, base_target))
+          
+          # If TinyMCE is already installed, make sure the user wants to continue
+          if !options[:force] && File.exists?(target_path)
+            print "TinyMCE already be installed in #{target_path}. Overwrite? (y/n): "
+            while !%w(y n).include?(option = STDIN.gets.chop)
+              print "Invalid option. Overwrite #{target_path}? (y/n): "
+            end
+            return if option == 'n'
+          end
+          
+          require 'hpricot'
+          require 'open-uri'
+          
+          # Get the url of the TinyMCE version
+          doc = Hpricot(open('http://sourceforge.net/project/showfiles.php?group_id=103281&package_id=111430'))
+          if version
+            version.gsub!('.', '_')
+            file_element = (doc/'tr[@id*="rel0_"] a').detect {|file| file.innerHTML =~ /#{version}.tgz$/}
+            raise ArgumentError, "Could not find TinyMCE version #{version}" if !file_element
+          else
+            file_element = (doc/'tr[@id^="pkg0_1rel0_"] a').detect {|file| file.innerHTML.to_s =~ /\d\.tgz$/}
+            raise ArgumentError, 'Could not find latest TinyMCE version' if !file_element
+          end
+          
+          filename = file_element.innerHTML
+          file_url = file_element['href']
+          
+          # Download and install it
+          Dir.chdir('/tmp/') do
+            begin
+              puts 'Downloading TinyMCE source...' if verbose
+              system("wget '#{file_url}' &> wget.log")
+              puts 'Extracting...' if verbose
+              system("tar xf #{filename} &> tar.log")
+              File.delete(filename)
+              FileUtils.mkdir_p(target_path)
+              FileUtils.cp_r("#{source_path}/.", target_path)
+              FileUtils.rmtree(source_path)
+              puts 'Done!' if verbose
+            rescue Object => e
+              puts "Error: #{e.inspect}"
+              puts 'Also see the last modified log file (wget.log or tar.log) in /tmp/.'
+            end
+          end
+        end
+        
+        # Uninstalls the TinyMCE installation and optional configuration file
+        def uninstall
+          # Remove the TinyMCE configuration file
+          File.delete(OPTIONS_FILE_PATH)
+          
+          # Remove the TinyMCE installation
+          FileUtils.rm_rf("#{RAILS_ROOT}/public/javascripts/tinymce")
+        end
+        
+        # Updates the list of possible configuration options that can be used
+        # when initializing the TinyMCE script.  These are always installed to
+        # the application folder, config/tiny_mce_options.yml.  If this file
+        # does not exist, then the TinyMCE helper will not be able to verify
+        # that all of the initialization options are valid.
+        def update_options
+          require 'hpricot'
+          require 'open-uri'
+          require 'yaml'
+          
+          puts 'Downloading configuration options from TinyMCE Wiki...' if verbose
+          doc = Hpricot(open('http://wiki.moxiecode.com/index.php/TinyMCE:Configuration'))
+          options = (doc/'a[@title*="Configuration/"]/').collect {|option| option.to_s}.sort
+          options.reject! {|option| option =~ DYNAMIC_OPTIONS}
+          
+          File.open("#{RAILS_ROOT}/config/tiny_mce_options.yml", 'w') do |out|
+            YAML.dump(options, out)
+          end
+          puts 'Done!' if verbose
+        end
+      end
+      
+      # Are we using TinyMCE?
+      def using_tiny_mce?
+        @uses_tiny_mce
+      end
+      
+      # Create the TinyMCE initialization scripts.  The default configuration
+      # is for a simple theme that replaces all textareas on the page.  For
+      # example, the default initialization script will generate the following:
+      # 
+      #  tinyMCE.init({
+      #    'mode' : 'textareas',
+      #    'theme' : 'simple'
+      #  });
+      # 
+      # == Customizing initialization options
+      # 
+      # To customize the options to be included in the initialization script,
+      # you can pass in a hash to #tiny_mce_init_script.  For example,
+      # 
+      #   tiny_mce_init_script(
+      #     :theme => 'advanced',
+      #     :editor_selector => 'rich_text',
+      #     :content_css => '/stylesheets/tiny_mce_content.css',
+      #     :editor_css => '/stylesheets/tiny_mce_editor.css',
+      #     :auto_reset_designmode => true
+      #   )
+      # 
+      # will generate:
+      # 
+      #  tinyMCE.init({
+      #    'mode' : 'textareas',
+      #    'theme' : 'advanced',
+      #    'editor_selected' : 'rich_text',
+      #    'content_css' : '/stylesheets/tiny_mce_content.css'
+      #  });
+      # 
+      # == Validating options
+      # 
+      # If additional options are passed in to initialize TinyMCE, they will be
+      # validated against the list of valid options in PluginAWeek::Helpers::TinyMCEHelper#valid_options.
+      # These options are configured in the file config/tiny_mce_options.yml.
+      # You can generate this file by invoke the rake task tiny_mce:update_options.
+      def tiny_mce_init_script(options = @tiny_mce_options)
+        options ||= {}
+        options.stringify_keys!.reverse_merge!(
+          'mode' => 'textareas',
+          'theme' => 'simple'
+        )
+        
+        # Check validity
+        plugins = options['plugins']
+        options_to_validate = options.reject {|option, value| plugins && plugins.include?(option.split('_')[0]) || option =~ DYNAMIC_OPTIONS}
+        options_to_validate.assert_valid_keys(@@valid_options) if @@valid_options && @@valid_options.any?
+        
+        init_script = 'tinyMCE.init({'
+        
+        options.sort.each do |key, value|
+          init_script += "\n#{key} : "
+          
+          case value
+            when String, Symbol, Fixnum
+              init_script << "'#{value}'"
+            when Array
+              init_script << "'#{value.join(',')}'"
+            when TrueClass
+              init_script << 'true'
+            when FalseClass
+              init_script << 'false'
+            else
+              raise ArgumentError, "Cannot parse value of type #{value.class} passed for TinyMCE option #{key}"
+          end
+          
+          init_script << ','
+        end
+        
+        init_script.chop << "\n});"
+      end
+      
+      # Generate the TinyMCE 
+      def tiny_mce(*args)
+        javascript_tag tiny_mce_init_script(*args)
+      end
+      
+      # The name of the TinyMCE javascript file to use.  In development, this
+      # will use the source (uncompressed) file in order to help with debugging
+      # issues that occur within TinyMCE.  In production, the compressed version
+      # of TinyMCE will be used in order to increased download speed.
+      def tiny_mce_file_name
+        RAILS_ENV == 'development' ? 'tinymce/tiny_mce_src' : 'tinymce/tiny_mce'
+      end
+      
+      # Generates the javascript include for TinyMCE.  For example,
+      # 
+      #   javascript_include_tiny_mce
+      # 
+      # will generate:
+      # 
+      #   <script type="text/javascript" src="/javascripts/tinymce/tiny_mce.js"></script>
+      def javascript_include_tiny_mce
+        javascript_include_tag tiny_mce_file_name
+      end
+      
+      # Conditionally includes the TinyMCE javascript file if the variable
+      # @uses_tiny_mce has been set to true.
+      def javascript_include_tiny_mce_if_used
+        javascript_include_tiny_mce if using_tiny_mce?
+      end
+    end
+  end
+end
+
+ActionController::Base.class_eval do
+  helper PluginAWeek::Helpers::TinyMCEHelper
+end