caterpillar 1.2.5 → 1.3.1

data/ChangeLog

@@ -1,7 +1,17 @@
+= 1.3.1
+	- rename xml task to makexml, and call it with deploy:xml
+	- many small fixes to various tasks
+	- XML is validated with Liferay DTD and portlet-app XSD
+	- silence deprecation warnings from Rails gem chooser
+
+= 1.3.0
+	- New helpers to generate resource urls (download) and get_liferay_preferences, to get the preferences
+	- edit_mode and instanceable working on portlet configuration
+	- Modifications on portlet-ext.xml (new filter and RESOURCE_PHASE)
+
 = 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

data/README.rdoc

@@ -14,11 +14,23 @@ For developers:
 * 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.
+= Quickstart
+== The new path
+You'll need at least the version 1.3.0.
 
-  $ gem install caterpillar-1.2.3.gem
+  $ gem install caterpillar-1.3.0.gem
+
+Start up a new Rails project:
+
+  $ caterpillar rails example
+
+It's all you need =].
+
+
+== The old way
+Rubygems is fixed, but the most recent stable release is 1.2.5.
+
+  $ gem install caterpillar
 
 Start up a new Rails project:
 
@@ -88,4 +100,116 @@ Here are the most useful tasks; see the rdoc documentation and caterpillar --des
 
 
 Join the bugs mailing list (http://rubyforge.org/mailman/listinfo/rails-portlet-bugs) to request help.
+
+= How to implement 
+
+== File Download
+
+In order to use download links in your webpages, you need to use the method:
+  send_file(file_path, :filename=>"filename")
+
+For example, on DownloadController, 'start' method allows the download of 'image.jpg' file.     
+  def start
+    send_file('../images/image.jpg', :filename => "image.jpg")
+  end
+
+In your webpage, you should use the following method which will manage your urls:
+  liferay_resource_url(:controller=> :controllerName, :action=> :methodName)  
+           
+It should look like: 
+  <%= link_to "Download", liferay_resource_url(:controller => :download , :action => :start) %>
+
+To access the +liferay_resource_url+ method you will need to include the Liferay module in your application_helper
+  include Caterpillar::Helpers::Liferay
+
+This method will generate a valid url for +serveResource+ method in liferay
+
+== Portlet Preferences
+
+To enable portlet preferences we need to set <b>:edit_mode</b> as true on <em>portlet.rb</em> file. 
+We have two kinds of portlets, the instanceable ones and not instaceables ones. Each instaceable portlet holds it's own preferences otherwise not instanceable has just one definition, keeping the same data into all portlets of the kind.
+  portlet.instances << {
+    :name => 'test',
+    :edit_mode => true,
+    :instanceable => false
+  }
+
+Each mapped portlet requires a <b>preferences</b> method which will handle the edit mode features. 
+For example:
+  def preferences
+    if request.post?
+      flash[:notice] = 'Success!'
+    end
+  end
+
+Rails-portlet will provide us a hash with all saved preferences, to access this method we need to include the Caterpillar::PortletSupport module, like:
+  include Caterpillar::PortletSupport
+
+This module will provide <b>get_liferay_preferences</b> method which returns the preferences hash. A good approach is to include this module on <i>ApplicationController</i>, like:
+  class ApplicationController < ActionController::Base
+    include Caterpillar::PortletSupport
+
+    helper :all # include all helpers, all the time
+    protect_from_forgery # See ActionController::RequestForgeryProtection for details
+
+    before_filter :get_preferences
+
+    protected
+    def get_preferences
+      preferences = get_liferay_preferences
+      @preferences = preferences ? preferences : {}
+    end
+
+  end
+
+In your erb file you will have a form like this, where each attribute (that has to be saved) needs to have prefix <b>_preference</b> on its name. For example:
+  <% form_tag :controller => :test , :action => :preferences do %>
+    <p>
+      Cor de fundo: <%= text_field_tag :background_color_preference, @preferences[:background_color_preference] %>
+    </p>
+    <p>
+      Tamanho fonte: <%= text_field_tag :font_size_preference, @preferences[:font_size_preference] %>
+    </p>
+    <p>
+      Cor da fonte:  <%= text_field_tag :font_color_preference, @preferences[:font_color_preference] %>
+    </p>
+    <%= submit_tag "Salve" %>
+  <% end %>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 

data/Rakefile

@@ -1,6 +1,8 @@
 require 'rake'
 require 'rake/testtask'
 require 'rake/rdoctask'
+require 'rake/gempackagetask'
+load 'caterpillar.gemspec'
 
 desc 'Default: create API doc.'
 task :default => :rdoc
@@ -15,5 +17,3 @@ Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.rdoc_files.include('generators/**/*.rb')
   rdoc.options << '--line-numbers' << '--inline-source' << '-U'
 end
-
-

data/bin/caterpillar

@@ -33,7 +33,7 @@ application.standard_exception_handling do
 
   # Load the main tasks - choose the namespace
   Caterpillar::Task.new(ARGV[0] ? ARGV[0].gsub(/:.*/,'') : :usage)
-
+  
   task :default => :usage
 
   application.top_level

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

@@ -1,6 +1,4 @@
 # encoding: utf-8
-
-
 Caterpillar::Config.new do |portlet|
 
   # JRUBY_HOME can be set here, unless the environment variable can be used.
@@ -20,7 +18,7 @@ Caterpillar::Config.new do |portlet|
   #
   # No changes are made to any of the files in this directory while making XML,
   # only the deploy and install tasks make any changes.
-  # portlet.container.root = '/usr/local/liferay/'
+  # portlet.container.root = '/usr/local/liferay/tomcat/'
 
   # The server that the container is running on.
   # Possible values:
@@ -33,8 +31,8 @@ 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.
+  # Allow to defining the deploy_dir - just the WAR file will be deployed under this directory.
+  # Since version 1.3.0
   # portlet.container.deploy_dir = '/opt/myDeployDir'
 
   # The hostname and port.
@@ -61,14 +59,18 @@ Caterpillar::Config.new do |portlet|
   # Most likely you will want to let ActionController::Routing to set the route.
   #
   # Available keys are:
-  #  - :name        -- named route
-  #  - :category    -- portlet category (Liferay only)
-  #  - :title       -- the title in portlet container's category (Liferay only)
-  #  - :javascripts -- portlet-specific javascripts that are included at
-  #                    the head of master HTML, such as body onload functions (Liferay only)
-  #  - :host        -- hostname:port of the deployment server
-  #  - :servlet     -- by default, the name of the Rails app (= name of the WAR package)
-  #  - :path        -- unless you're using named routes, you can define the path here
+  #  - :name         -- named route
+  #  - :category     -- portlet category (Liferay only)
+  #  - :title        -- the title in portlet container's category (Liferay only)
+  #  - :edit_mode    -- enables edit mode for the portlet, adds <portlet-mode>edit</portlet-mode> to portlet-ext.xml
+  #                     Default value is false
+  #  - :instanceable -- enables instanceable for the portlet, add <instanceable>true</instanceable> to
+  #                     liferay-portlet-ext.xml. Default value is false
+  #  - :javascripts  -- portlet-specific javascripts that are included at
+  #                     the head of master HTML, such as body onload functions (Liferay only)
+  #  - :host         -- hostname:port of the deployment server
+  #  - :servlet      -- by default, the name of the Rails app (= name of the WAR package)
+  #  - :path         -- unless you're using named routes, you can define the path here
 
   # Rails-portlet testing application.
   # NOTE: this needs to be activated by 'map.caterpillar' in RAILS_ROOT/config/routes.rb

data/lib/caterpillar.rb

@@ -1,15 +1,14 @@
 # encoding: utf-8
-
-
 #--
 # (c) Copyright 2008-2010 Mikael Lammentausta
+#                    2010 Túlio Ornelas
 #
 # See the file MIT-LICENSE included with the distribution for
 # software license details.
 #++
 
 module Caterpillar
-  VERSION='1.2.5'
+  VERSION='1.3.1'
 end
 
 this_file = File.symlink?(__FILE__) ? File.readlink(__FILE__) : __FILE__

data/lib/caterpillar/config.rb

@@ -18,6 +18,10 @@ module Caterpillar
 
     attr_accessor :category
 
+    attr_accessor :edit_mode
+    
+    attr_accessor :instanceable
+
     attr_accessor :host
 
     attr_accessor :servlet

data/lib/caterpillar/helpers/liferay.rb

@@ -6,6 +6,7 @@ require 'action_controller'
 
 module Caterpillar
 module Helpers
+  
   # This module contains Rails helpers that provide methods to deal with various aspects
   # of portlet functionality in Liferay.
   #
@@ -18,6 +19,28 @@ module Helpers
     include ActionView::Helpers::UrlHelper
     include ActionView::Helpers::TagHelper
 
+    def liferay_resource_url(params, resource_url = cookies[:Liferay_resourceUrl])
+      if resource_url.nil? then return raise "resource_url is needed!" end
+      
+      controller = params.delete :controller
+      action = params.delete :action
+      
+      if controller.nil? then return resource_url end
+      if action.nil? then action = :index end
+      
+      url = "#{resource_url}&railsRoute=/#{controller}/#{action}"
+      
+      unless params.empty?
+        url += '?'
+        params.keys.each do |key|
+          url += "#{key}=#{params[key]}&"
+        end
+        url.gsub!(/&$/, '')
+      end
+      
+      url
+    end
+
     # Link that the rails-portlet will leave unparsed.
     def link_to_exit_portlet(name, options = {}, html_options = {})
       link_to(name, url_to_exit_portlet(options), html_options)

data/lib/caterpillar/liferay.rb

@@ -63,7 +63,7 @@ module Caterpillar # :nodoc:
     # Defaults to +Lportal::Schema.version+.
     def initialize(version=nil)
       @version    = version
-      @root       = '/usr/local/liferay'
+      @root       = '/usr/local/liferay-portal-5.2.3/tomcat-6.0.18' # as described in setup guide, when unpacked to /usr/local
       @server     = 'Tomcat'
       @deploy_dir = nil
     end
@@ -137,8 +137,10 @@ module Caterpillar # :nodoc:
       # 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')
+                                  
+      #self.deploy_dir(),    
+      # Xml files need to be in WEB-INF and not, for example, /opt/liferay/deploy
+      return File.join(File.join(self.root,'webapps'), root_dir,'WEB-INF')
     end
 
     # Reads Liferay portlet descriptor XML files and parses them with Hpricot.
@@ -278,26 +280,12 @@ module Caterpillar # :nodoc:
       '</%s>' % doctype
     end
 
-    # TODO: DTD version detection based on self.version
+    # DTD version detection based on self.version
     def dtd_version(type)
-      case type
-      when 'liferay-portlet-app'
-        if @version[/5.1/]
-          '5.1.0'
-        elsif @version[/5.2/]
-          '5.2.0'
-        else
-          @version
-        end
-      when 'display'
-        if @version[/5.1/]
-          '5.1.0'
-        elsif @version[/5.2/]
-          '5.2.0'
-        else
-          @version
-        end
-      end
+      #case type
+      #when 'liferay-portlet-app'
+      #when 'display'
+      self.version[/.../] + '.0'
     end
 
     # liferay-portlet-ext definition
@@ -330,7 +318,7 @@ module Caterpillar # :nodoc:
       xml << "    <use-default-template>true</use-default-template>\n"
 
       # can there be several portlet instances on the same page?
-      xml << "    <instanceable>false</instanceable>\n"
+      xml << "    <instanceable>#{portlet[:instanceable]}</instanceable>\n"
 
       # The default value of ajaxable is true. If set to false, then this portlet can never be displayed via Ajax.
       xml << "    <ajaxable>true</ajaxable>\n"

data/lib/caterpillar/parser.rb

@@ -112,6 +112,9 @@ module Caterpillar
         title = _title.gsub(/ä/,'a').gsub(/ö/,'o').gsub(/Ä/,'A').gsub(/Ö/,'O')
         portlet.update( :title => title )
 
+        portlet[:edit_mode] ||= nil
+        portlet[:instanceable] ||= false
+
         ### unless defined, use default javascripts
         portlet[:javascripts] ||= @config.javascripts
 

data/lib/caterpillar/portlet.rb

@@ -1,6 +1,4 @@
 # encoding: utf-8
-
-
 #--
 # (c) Copyright 2008, 2010 Mikael Lammentausta
 # See the file LICENSES.txt included with the distribution for
@@ -42,9 +40,9 @@ module Caterpillar
       'com.celamanzi.liferay.portlets.rails286.Rails286Portlet'
     end
 
-    # Rails-portlet Java class
+    # Rails-portlet Java class for 0.10.0+
     def portlet_filter_class
-      'com.celamanzi.liferay.portlets.rails286.Rails286PortletRenderFilter'
+      'com.celamanzi.liferay.portlets.rails286.Rails286PortletFilter'
     end
 
     # JSR 286 portlet XML header. Opens portlet-app.
@@ -80,8 +78,7 @@ module Caterpillar
       xml << "    <supports>\n"
       xml << "      <mime-type>text/html</mime-type>\n"
       xml << "      <portlet-mode>view</portlet-mode>\n"
-      # edit mode is not used. this is for development.
-      if portlet[:edit]==true
+      if portlet[:edit_mode] == true
         xml << "      <portlet-mode>edit</portlet-mode>\n"
       end
       xml << "    </supports>\n"
@@ -89,6 +86,8 @@ module Caterpillar
       xml << "    <portlet-info>\n"
       xml << "      <title>%s</title>\n" % portlet[:title]
       xml << "    </portlet-info>\n"
+      ### init parameters, XXX: fails xsd test
+#=begin
       # insert session key
       unless session.nil?
         xml << "    <init-param>\n"+\
@@ -103,6 +102,7 @@ module Caterpillar
                "      <value>#{session[:secret]}</value>\n"+\
                "    </init-param>\n"
       end
+#=end
       roles.each do |role|
         xml << "    <security-role-ref>\n"
         xml << "      <role-name>#{role}</role-name>\n"
@@ -116,6 +116,8 @@ module Caterpillar
       xml << "    <filter-name>%s_filter</filter-name>\n" % portlet[:name]
       xml << "    <filter-class>%s</filter-class>\n" % self.portlet_filter_class
       xml << "    <lifecycle>RENDER_PHASE</lifecycle>\n"
+      xml << "    <lifecycle>RESOURCE_PHASE</lifecycle>\n"
+
       # define host, servlet and route (path to be more precise)
       xml << "    <init-param>\n"
       xml << "      <name>host</name>\n"
@@ -129,6 +131,7 @@ module Caterpillar
       xml << "      <name>route</name>\n"
       xml << "      <value>%s</value>\n" % portlet[:path].gsub(/&/,"&amp;")
       xml << "    </init-param>\n"
+
       xml << "  </filter>\n\n"
 
       xml << "  <filter-mapping>\n"

data/lib/caterpillar/portlet_support.rb

@@ -0,0 +1,29 @@
+# encoding: utf-8
+
+module Caterpillar
+  
+  # Add some portlet support
+  #
+  module PortletSupport
+  
+    # Gets portlet preferences from a cookie (Liferay_preferences) and generates
+    # a hash with it. Returns nil if cookie do not exists or the value is nil.
+    #
+    def get_liferay_preferences(value = cookies[:Liferay_preferences])
+      preferences = {}
+      if value and (not value.empty?)
+        value.split(";").each do |pair|
+          if pair.nil? or pair.empty? then next end
+      
+          result = pair.split("=")
+          preferences[result[0].intern] = result[1]
+        
+        end
+        return preferences
+      end
+  
+      nil
+    end
+
+  end
+end