pluginaweek-tiny_mce_helper 0.3.0

data/CHANGELOG.rdoc

@@ -0,0 +1,46 @@
+== master
+
+== 0.3.0 / 2009-04-14
+
+* No longer require that the Sourceforge project page be downloaded when determining the location of a custom version
+* Require at least TinyMCE 3.2.2 be installed
+* Update to new TinyMCE file structure
+* Update to new Sourceforge downloads location
+
+== 0.2.0 / 2008-12-14
+
+* Remove the PluginAWeek namespace
+* Update tests to use mocha
+* Update tests to use ActionView::TestCase
+
+== 0.1.1 / 2008-10-19
+
+* Fix TinyMCE temp file getting closed/deleted too soon after being downloaded [Brandon Goodin]
+* Add more descriptive output during installation
+
+== 0.1.0 / 2008-08-30
+
+* Remove references to system wget/unzip calls for cross-platform compatibility
+* Add dependency on RubyZip
+
+== 0.0.4 / 2008-06-22
+
+* Remove log files from gems
+
+== 0.0.3 / 2008-05-05
+
+* Updated documentation
+* Change references from RAILS_ROOT to Rails.root
+* Use zipped version of TinyMCE instead of tar
+
+== 0.0.2 / 2007-09-26
+
+* Remove gem dependency on actionpack
+
+== 0.0.1 / 2007-08-20
+
+* 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.rdoc

@@ -0,0 +1,185 @@
+= tiny_mce_helper
+
++tiny_mce_helper+ adds helper methods for creating the TinyMCE initialization
+script.
+
+== Resources
+
+API
+
+* http://api.pluginaweek.org/tiny_mce_helper
+
+Bugs
+
+* http://pluginaweek.lighthouseapp.com/projects/13291-tiny_mce_helper
+
+Development
+
+* http://github.com/pluginaweek/tiny_mce_helper
+
+Source
+
+* git://github.com/pluginaweek/tiny_mce_helper.git
+
+== 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.
+
+=== Usage
+
+=== 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=3.2.2
+  (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/tiny_mce. 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=3.2.2
+  (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=3.2.2
+  (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 TinyMCEHelper
+
+== Testing
+
+Before you can run any tests, the following gem must be installed:
+* plugin_test_helper[http://github.com/pluginaweek/plugin_test_helper]
+
+To run against a specific version of Rails:
+
+  rake test RAILS_FRAMEWORK_ROOT=/path/to/rails
+
+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
+
+== Dependencies
+
+* Rails 2.0 or later
+* TinyMCE 3.2.2 or later
+* hpricot[http://code.whytheluckystiff.net/hpricot]
+* rubyzip[http://rubyzip.sourceforge.net]
+
+== 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.

data/Rakefile

@@ -0,0 +1,96 @@
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/contrib/sshpublisher'
+
+spec = Gem::Specification.new do |s|
+  s.name              = 'tiny_mce_helper'
+  s.version           = '0.3.0'
+  s.platform          = Gem::Platform::RUBY
+  s.summary           = 'Adds helper methods for creating the TinyMCE initialization script in Rails'
+  s.description       = s.summary
+  
+  s.files             = FileList['{lib,tasks,test}/**/*'] + %w(CHANGELOG.rdoc init.rb install.rb Rakefile README.rdoc uninstall.rb) - FileList['test/app_root/{log,log/*,script,script/*}']
+  s.require_path      = 'lib'
+  s.has_rdoc          = true
+  s.test_files        = Dir['test/**/*_test.rb']
+  
+  s.author            = 'Aaron Pfeifer'
+  s.email             = 'aaron@pluginaweek.org'
+  s.homepage          = 'http://www.pluginaweek.org'
+  s.rubyforge_project = 'pluginaweek'
+end
+  
+desc 'Default: run all tests.'
+task :default => :test
+
+desc "Test the #{spec.name} plugin."
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.test_files = spec.test_files
+  t.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  namespace :test do
+    desc "Test the #{spec.name} plugin with Rcov."
+    Rcov::RcovTask.new(:rcov) do |t|
+      t.libs << 'lib'
+      t.test_files = spec.test_files
+      t.rcov_opts << '--exclude="^(?!lib/)"'
+      t.verbose = true
+    end
+  end
+rescue LoadError
+end
+
+desc "Generate documentation for the #{spec.name} plugin."
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = spec.name
+  rdoc.template = '../rdoc_template.rb'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc', 'CHANGELOG.rdoc', 'lib/**/*.rb')
+end
+
+desc 'Generate a gemspec file.'
+task :gemspec do
+  File.open("#{spec.name}.gemspec", 'w') do |f|
+    f.write spec.to_ruby
+  end
+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('aaron@pluginaweek.org', '/home/aaron/gems.pluginaweek.org/public/gems', 'pkg', "#{spec.name}-#{spec.version}.gem").upload
+end
+
+desc 'Publish the API documentation.'
+task :pdoc => [:rdoc] do
+  Rake::SshDirPublisher.new('aaron@pluginaweek.org', "/home/aaron/api.pluginaweek.org/public/#{spec.name}", 'rdoc').upload
+end
+
+desc 'Publish the API docs and gem'
+task :publish => [:pgem, :pdoc, :release]
+
+desc 'Publish the release files to RubyForge.'
+task :release => [:gem, :package] do
+  require 'rubyforge'
+  
+  ruby_forge = RubyForge.new.configure
+  ruby_forge.login
+  
+  %w(gem tgz zip).each do |ext|
+    file = "pkg/#{spec.name}-#{spec.version}.#{ext}"
+    puts "Releasing #{File.basename(file)}..."
+    
+    ruby_forge.add_release(spec.rubyforge_project, spec.name, spec.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...'
+TinyMCEHelper.install(:version => ENV['VERSION'], :target => ENV['TARGET'])
+
+# Update the configuration options
+puts 'Updating TinyMCE configuration options...'
+TinyMCEHelper.update_options

data/lib/tiny_mce_helper.rb

@@ -0,0 +1,262 @@
+# Adds helper methods for generating the TinyMCE initialization script
+# within your 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.
+    # 
+    # Configuration options:
+    # * <tt>:version</tt> - The version of TinyMCE to install. Default is the
+    #   latest version.
+    # * <tt>:target</tt> - The path to install TinyMCE to, relative to the
+    #   project root. Default is "public/javascripts/tiny_mce"
+    # * <tt>:force</tt> - Whether to install TinyMCE, regardless of whether it
+    #   already exists on the filesystem.
+    # 
+    # == 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,
+    #   TinyMCEHelper.install                      # Installs the latest version
+    #   TinyMCEHelper.install(:version => '3.2.2') # Installs version 3.2.2
+    # 
+    # 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/tiny_mce.
+    # 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,
+    #   TinyMCEHelper.install(:target => 'public/javascripts/richtext')
+    # 
+    # == Conflicting paths
+    # 
+    # If TinyMCE is found to already be installed on the filesystem, a prompt
+    # will be displayed for whether to overwrite the existing directory.  This
+    # prompt can be automatically skipped by passing in the :force option.
+    def install(options = {})
+      options.assert_valid_keys(:version, :target, :force)
+      options.reverse_merge!(:force => false)
+      
+      version = options[:version]
+      base_target = options[:target] || 'public/javascripts/tiny_mce'
+      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 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 'open-uri'
+      
+      # Get the latest TinyMCE version
+      unless version
+        require 'hpricot'
+        
+        puts 'Finding latest version of TinyMCE to download...' if verbose
+        doc = Hpricot(open('http://sourceforge.net/project/showfiles.php?group_id=103281&package_id=111430'))
+        file_element = (doc/'tr[@id^="pkg0_1rel0_"] a').detect {|file| file.innerHTML.to_s =~ /tinymce_([\d_]+).zip$/}
+        raise ArgumentError, 'Could not find latest TinyMCE version' if !file_element
+        
+        version = $1. gsub('_', '.')
+      end
+      
+      file_url = "http://prdownloads.sourceforge.net/tinymce/tinymce_#{version.gsub('.', '_')}.zip?download"
+      
+      # Download the file
+      puts "Downloading TinyMCE-#{version} source from #{file_url}..." if verbose
+      open(file_url) do |file|
+        file_path = file.path
+        
+        # Extract and install
+        puts "Extracting source from #{file_path}..." if verbose
+        
+        require 'zip/zip'
+        require 'zip/zipfilesystem'
+        
+        Zip::ZipFile.open(file_path) do |zipfile|
+          zipfile.entries.each do |entry|
+            if match = /jscripts\/tiny_mce\/(.*)/.match(entry.name)
+              FileUtils.mkdir_p("#{target_path}/#{File.dirname(match[1])}")
+              entry.extract("#{target_path}/#{match[1]}") { true }
+            end
+          end
+        end
+        
+        puts 'Done!' if verbose
+      end
+    end
+    
+    # Uninstalls the TinyMCE installation and optional configuration file
+    # 
+    # Configuration options:
+    # * +target+ - The path that TinyMCE was installed to. Default is "public/javascripts/tiny_mce"
+    def uninstall(options = {})
+      # Remove the TinyMCE configuration file
+      File.delete(OPTIONS_FILE_PATH)
+      
+      # Remove the TinyMCE installation
+      FileUtils.rm_rf(options[:target] || "#{Rails.root}/public/javascripts/tiny_mce")
+    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(OPTIONS_FILE_PATH, 'w') do |out|
+        YAML.dump(options, out)
+      end
+      puts 'Done!' if verbose
+    end
+  end
+  
+  # Is TinyMCE being used?
+  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 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. Any arguments will be passed to tiny_mce_init_script.
+  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' ? 'tiny_mce/tiny_mce_src' : 'tiny_mce/tiny_mce'
+  end
+  
+  # Generates the javascript include for TinyMCE.  For example,
+  # 
+  #   javascript_include_tiny_mce
+  # 
+  # will generate:
+  # 
+  #   <script type="text/javascript" src="/javascripts/tiny_mce/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
+
+ActionController::Base.class_eval do
+  helper TinyMCEHelper
+end