caterpillar 1.0.7 → 1.2.5

data/ChangeLog

@@ -1,3 +1,31 @@
+= 1.2.5
+	- Ruby 1.9 compatibility fix
+	- define utf8 encoding (thanks to Hendie Dijkman for mentioning about it)
+
+= 1.2.4
+	- use standalone Rails defaults in the installed config file
+	- updated xUnit tests in the portlet test bench
+
+= 1.2.3
+	- include rails-portlet 0.9.2
+	- parse session key and secret into the XML
+	- provide Caterpillar::Security actions for Rails controllers
+
+= 1.1.2
+	- allow to defining the deploy_dir in config/portlets.rb
+		(requested by Túlio Ornelas dos Santos, who sent the original patch)
+
+= 1.1.1
+	- regression fix
+
+= 1.1.0
+	- include rails-portlet 0.8.1
+	- improved test bench appearance, updated available tests
+	- added JUnit test controller for automatic testing
+	- moved db:migrate and db:rollback to lportal
+	- gem loading is now handled by a static class
+	- fixed gem loading with Rails 2.3.5'
+
 = 1.0.7
 	- include rails-portlet 0.7.2
 

data/README.rdoc

@@ -0,0 +1,91 @@
+Caterpillar is a developer tool to help building and deploying Rails applications for Liferay portlets.
+The aim is to minimize the needed additions to the Rails framework and interfere with the developer workflow.
+
+Main features:
+
+* installs the portlet JAR to Liferay's [+CLASSPATH+]
+* dynamic portlet XML creation based on named routes
+* deploys the generated XML to Liferay, requires Liferay restart
+* implements session security by shared key authentication
+
+For developers:
+
+* portlet test bench
+* a Rails view helper which lists portlets during development
+
+
+== Quickstart
+NOTE: *Rubygems does not seem to get the most uptodate version.* The release should be >= 1.2.3.
+Please download the latest release from Rubyforge.
+
+  $ gem install caterpillar-1.2.3.gem
+
+Start up a new Rails project:
+
+  $ rails example
+  $ cd example
+  $ caterpillar pluginize
+
+Activate Caterpillar routes by updating <tt>RAILS_ROOT/config/routes.rb</tt> to read as follows:
+
+  ActionController::Routing::Routes.draw do |map|
+    map.caterpillar # add this line
+    # ... other routes ...
+
+This route mapping is also needed to use portlet security features to prevent UID faking. Update <tt>ApplicationController</tt>:
+  class ApplicationController < ActionController::Base
+    include Caterpillar::Security
+    secure_portlet_sessions
+
+If you are connecting to the Liferay database, add lportal[http://lportal.rubyforge.org/] in the Rails startup:
+  $ echo "require 'lportal'" > config/initializers/lportal.rb
+And set up the database connection.
+
+Now run <tt>caterpillar portlets</tt> to check if the installation is working.
+The output should include these lines:
+
+  * Portlet configuration ***********************
+  Caterpillar
+    Rails-portlet test bench      "portlet_test_bench"  []
+
+Then you can start up the server (<tt>./script/server</tt>) and navigate to http://localhost:3000/caterpillar/test_bench
+
+
+== Good to know
+The command-line tool <tt>caterpillar</tt> should be executed in the Rails project root directory.
+You can install and upgrade the <tt>rails-portlet</tt> JAR and generate dynamic portlet XML and also
+deploy them. See the task description below - and you can also run <tt>caterpillar --describe</tt>.
+
+The optional Caterpillar Rails plugin offers specialized helpers and views for better Liferay integration
+and to ease the development. Not to mention the portlet test bench application.
+
+Developers should know that this is required to successfully run the <tt>rails-portlet</tt> test suite,
+where JUnit tests do actual requests to the Rails app.
+
+You can take plugins into use by running
+  $ caterpillar pluginize
+in the Rails directory, but you need to remember that with each subsequent upgrade of Caterpillar, you would need to
+  rm vendor/plugins/caterpillar && caterpillar pluginize
+each time. Rails is quite picky where it will load the views - security issue.
+
+Maybe caterpillar could have an upgrade task to handle this?
+
+
+== Useful tasks 
+Here are the most useful tasks; see the rdoc documentation and caterpillar --describe for the full feature list.
+
+<tt>xml</tt>::  processes the portlet XML configuration in accordance with the named routes
+
+<tt>xml:deploy</tt>::  deploys the created XML to the J2EE portlet container 
+
+<tt>jar:install</tt>:: installs the Rails-portlet JAR into Liferay's classpath
+
+<tt>deploy</tt>:: warbles the application, updates the XML configuration and copies these to Liferay
+
+<tt>pluginize</tt>:: copies caterpillar to vendor/plugins
+
+<tt>fixtures</tt>:: imports live data from the production database for testing
+
+
+Join the bugs mailing list (http://rubyforge.org/mailman/listinfo/rails-portlet-bugs) to request help.
+

data/Rakefile

@@ -5,19 +5,12 @@ require 'rake/rdoctask'
 desc 'Default: create API doc.'
 task :default => :rdoc
 
-desc 'Test the example plugin.'
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib'
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = true
-end
-
 desc 'Generate documentation for the example plugin.'
 Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title    = 'Caterpillar'
-  rdoc.main = 'README'
-  rdoc.rdoc_files.include('README')
+  rdoc.main = 'README.rdoc'
+  rdoc.rdoc_files.include('README.rdoc')
   rdoc.rdoc_files.include('lib/**/*.rb')
   rdoc.rdoc_files.include('generators/**/*.rb')
   rdoc.options << '--line-numbers' << '--inline-source' << '-U'

data/bin/caterpillar

@@ -2,6 +2,7 @@
 #
 #--
 # (c) Copyright 2008 Mikael Lammentausta, Cel'Amanzi Ltd
+#               2010 Mikael Lammentausta, Youleaf Ltd
 #
 # Constructed heavily upon Warbler's structure.
 # Thanks to Nick Sieger!

data/generators/caterpillar/caterpillar_generator.rb

@@ -1,3 +1,6 @@
+# encoding: utf-8
+
+
 # This generator installs the required files into the main Rails application.
 # This generator should always be run after upgrading the plugin.
 class CaterpillarGenerator < Rails::Generator::Base

data/generators/caterpillar/templates/config/portlets.rb

@@ -1,3 +1,6 @@
+# encoding: utf-8
+
+
 Caterpillar::Config.new do |portlet|
 
   # JRUBY_HOME can be set here, unless the environment variable can be used.
@@ -7,7 +10,7 @@ Caterpillar::Config.new do |portlet|
   # By default only portlet.xml is created.
   # Currently only Liferay is supported. You may optionally define the version.
   portlet.container = Liferay
-  # portlet.container.version = '5.1.1'
+  # portlet.container.version = '5.2.3'
 
   # If you want to install the Rails-portlet JAR into the container, the container
   # WEB-INF will be used.
@@ -30,19 +33,23 @@ Caterpillar::Config.new do |portlet|
   # By default the first entry in the directory is chosen.
   # portlet.container.server_dir = 'default'
 
+  # Allow to defining the deploy_dir - both the WAR file and the XML files
+  # are deployed under this directory.
+  # portlet.container.deploy_dir = '/opt/myDeployDir'
+
   # The hostname and port.
   # By default the values are taken from the request.
-  # portlet.host
-
+  portlet.host = 'http://0.0.0.0:3000'
+ 
   # If the Rails is running inside a servlet container such as Tomcat,
   # you can define the servlet here.
   # By default the servlet is the name of the Rails app.
-  # Remember to update this if you override Warbler's default.
-  # portlet.servlet
-
+  # Without Warbler this should be an empty string.
+  portlet.servlet = ''
+ 
   # Portlet category. This is only available for Liferay.
   # By default this is the same as the servlet.
-  # portlet.category = 'Zcore'
+  # portlet.category = 'Example Rails app'
 
   # Portlet instances.
   #

data/init.rb

@@ -1,3 +1,6 @@
+# encoding: utf-8
+
+
 #--
 # (c) Copyright 2008,2009 Mikael Lammentausta
 #

data/install.rb

@@ -1,3 +1,6 @@
+# encoding: utf-8
+
+
 # This will install required files into the main Rails application.
 system('./script/generate caterpillar')
 

data/lib/caterpillar.rb

@@ -1,12 +1,15 @@
+# encoding: utf-8
+
+
 #--
-# (c) Copyright 2008,2009 Mikael Lammentausta
+# (c) Copyright 2008-2010 Mikael Lammentausta
 #
 # See the file MIT-LICENSE included with the distribution for
 # software license details.
 #++
 
 module Caterpillar
-  VERSION='1.0.7'
+  VERSION='1.2.5'
 end
 
 this_file = File.symlink?(__FILE__) ? File.readlink(__FILE__) : __FILE__
@@ -20,7 +23,13 @@ require 'find'
 require 'rake'
 require 'rake/tasklib'
 
-require File.join(this_dir,'load_rails')
+# NOTE: During normal startup (not while building the gem),
+# ActiveRecord should be loaded at this point, before loading any of the models.
+# However, this may conflict later when Rails' rake task activates the boot process.
+# The correct versions should be loaded at this point.
+# Maybe this is too heavy, as some tasks do not need any Rails modules.
+require File.join(this_dir,'rails_gem_chooser')
+RailsGemChooser.__load # detects the Rails config file from RAILS_ROOT
 
 # include all ruby files
 Find.find(this_dir) do |file|

data/lib/caterpillar/config.rb

@@ -1,3 +1,6 @@
+# encoding: utf-8
+
+
 #--
 # (c) Copyright 2008 Mikael Lammentausta
 # See the file LICENSES.txt included with the distribution for
@@ -37,8 +40,8 @@ module Caterpillar
     def initialize
       # RAILS_ROOT is at least defined in Caterpillar initialization
       @rails_root  = File.expand_path(RAILS_ROOT)
-      @servlet = File.basename(@rails_root)
-      @category = @servlet
+      @servlet = nil
+      @category = nil
       @instances = []
       @javascripts = []
       @include_all_named_routes = true
@@ -46,11 +49,15 @@ module Caterpillar
       rails_conf = File.join(@rails_root,'config','environment.rb')
       unless File.exists?(rails_conf)
         STDERR.puts 'Rails configuration file could not be found'
-      end
-
-      @warbler_conf = File.join(@rails_root,'config','warble.rb')
-      unless File.exists?(@warbler_conf)
-        #STDERR.puts 'Warbler configuration file could not be found'
+        @rails_root = nil
+      else
+        @servlet = File.basename(@rails_root)
+        @category = @servlet
+
+        @warbler_conf = File.join(@rails_root,'config','warble.rb')
+        unless File.exists?(@warbler_conf)
+          #STDERR.puts 'Warbler configuration file could not be found'
+        end
       end
 
       #@logger  = (defined?(RAILS_DEFAULT_LOGGER) ? RAILS_DEFAULT_LOGGER : Logger.new)

data/lib/caterpillar/helpers/liferay.rb

@@ -1,3 +1,6 @@
+# encoding: utf-8
+
+
 require 'rubygems'
 require 'action_controller'
 

data/lib/caterpillar/liferay.rb

@@ -1,3 +1,6 @@
+# encoding: utf-8
+
+
 #--
 # (c) Copyright 2008,2009 Mikael Lammentausta
 #
@@ -51,13 +54,18 @@ module Caterpillar # :nodoc:
 
     # the name of the JBoss server directory
     attr_accessor :server_dir
+    
+    # For setting @deploy dir from the config file.
+    # The "get" method is deploy_dir().
+    attr_writer   :deploy_dir
 
     # Liferay version is given as a String, eg. '5.2.2'.
     # Defaults to +Lportal::Schema.version+.
     def initialize(version=nil)
-      @version = version
-      @root    = '/usr/local/liferay'
-      @server  = 'Tomcat'
+      @version    = version
+      @root       = '/usr/local/liferay'
+      @server     = 'Tomcat'
+      @deploy_dir = nil
     end
 
     # The name of the portal. Used in STDOUT messages.
@@ -65,26 +73,34 @@ module Caterpillar # :nodoc:
       'Liferay'
     end
 
+    # The directory where to deploy.
+    # By default, it is based on the servlet container name and
+    # the confured location of its root.
+    # It can also be defined from the configuration file:
+    # 	portlet.container.deploy_dir = '/opt/myDeployDir'
     def deploy_dir
+      return @deploy_dir unless @deploy_dir.nil?
+
       raise 'Configure container root folder' unless self.root
       case @server
 
       when 'Tomcat'
         root_dir = 'ROOT'
-        File.join(self.root,'webapps')
+        @deploy_dir = File.join(self.root,'webapps')
 
       when 'JBoss/Tomcat'
         # detect server name if not configured
         @server_dir ||= Dir.new(
             File.join(self.root,'server')).entries.first
-        path = File.join(self.root,'server',@server_dir,'deploy')
+        @deploy_dir = File.join(self.root,'server',@server_dir,'deploy')
 
-        unless File.exists?(path)
-          raise 'Portal deployment directory does not exist: %s' % path
-        end
+      end
 
-        return path
+      unless File.exists?(@deploy_dir)
+        raise 'Portal deployment directory does not exist: %s' % @deploy_dir
       end
+
+      return @deploy_dir
     end
 
     # The location of Liferay's WEB-INF folder for XML analyzation.
@@ -95,7 +111,7 @@ module Caterpillar # :nodoc:
 
       when 'Tomcat'
         root_dir = 'ROOT'
-        File.join(self.deploy_dir,root_dir,'WEB-INF')
+        return web_inf_dir(root_dir)
 
       when 'JBoss/Tomcat'
         # detect lportal dir (ROOT.war or lportal.war)
@@ -110,11 +126,20 @@ module Caterpillar # :nodoc:
           STDERR.puts 'Please file a bug on Caterpillar.'
           raise 'Portal root directory not found at %s' % self.deploy_dir
         end
-
-        File.join(self.deploy_dir,root_dir,'WEB-INF')
+                
+        return web_inf_dir(root_dir)
 
       end
     end
+    
+    # The rule by which the WEB-INF is constructed regardless of the server.
+    def web_inf_dir(root_dir)
+      # The @deploy_dir variable does not need checking,
+      # as the method deploy_dir() does that.
+      #if deploy_dir_defined?
+
+      return File.join(self.deploy_dir(),root_dir,'WEB-INF')
+    end
 
     # Reads Liferay portlet descriptor XML files and parses them with Hpricot.
     def analyze(type=:native)

data/lib/caterpillar/navigation.rb

@@ -1,4 +1,13 @@
-module Caterpillar
+# encoding: utf-8
+
+
+#--
+# (c) Copyright 2008,2009 Mikael Lammentausta
+# See the file LICENSES.txt included with the distribution for
+# software license details.
+#++
+
+module Caterpillar # :nodoc:
   # Portlet navigation on Rails.
   #
   # Caterpillar installs a partial 'caterpillar/navigation' into your views,

data/lib/caterpillar/parser.rb

@@ -1,3 +1,6 @@
+# encoding: utf-8
+
+
 #--
 # (c) Copyright 2008 Mikael Lammentausta
 # See the file LICENSES.txt included with the distribution for

data/lib/caterpillar/portlet.rb

@@ -1,5 +1,8 @@
+# encoding: utf-8
+
+
 #--
-# (c) Copyright 2008 Mikael Lammentausta
+# (c) Copyright 2008, 2010 Mikael Lammentausta
 # See the file LICENSES.txt included with the distribution for
 # software license details.
 #++
@@ -11,9 +14,18 @@ module Caterpillar
 
     # Creates portlet XML
     def xml(portlets)
+    	session = 
+        begin
+          {
+            :key    => Caterpillar::Security.get_session_key(),
+            :secret => Caterpillar::Security.get_secret()
+          }
+        rescue nil
+        end
+        
       xml = self.header
       portlets.each do |p|
-        xml << self.template(p)
+        xml << self.template(p,session)
       end
       xml << self.footer
       return xml
@@ -35,8 +47,6 @@ module Caterpillar
       'com.celamanzi.liferay.portlets.rails286.Rails286PortletRenderFilter'
     end
 
-    protected
-
     # JSR 286 portlet XML header. Opens portlet-app.
     def header
       xml =  '<?xml version="1.0" encoding="UTF-8"?>' +"\n"
@@ -54,7 +64,8 @@ module Caterpillar
     end
 
     # portlet.xml template.
-    def template(portlet)
+    # session is a hash containing session key and secret from Rails.
+    def template(portlet,session=nil)
       # add roles
       # TODO: move into portlet hash
       # administrator, power-user, user
@@ -78,6 +89,20 @@ module Caterpillar
       xml << "    <portlet-info>\n"
       xml << "      <title>%s</title>\n" % portlet[:title]
       xml << "    </portlet-info>\n"
+      # insert session key
+      unless session.nil?
+        xml << "    <init-param>\n"+\
+               "      <name>session_key</name>\n"+\
+               "      <value>#{session[:key]}</value>\n"+\
+               "    </init-param>\n"
+      end
+      # insert secret
+      unless session.nil?
+        xml << "    <init-param>\n"+\
+               "      <name>secret</name>\n"+\
+               "      <value>#{session[:secret]}</value>\n"+\
+               "    </init-param>\n"
+      end
       roles.each do |role|
         xml << "    <security-role-ref>\n"
         xml << "      <role-name>#{role}</role-name>\n"
@@ -115,4 +140,4 @@ module Caterpillar
 
   end # static methods
   end
-end
+end