parlement 0.10 → 0.11

data/vendor/plugins/engines/lib/engines/rails_extensions/public_asset_helpers.rb

@@ -0,0 +1,116 @@
+# The engines plugin makes it trivial to share public assets using plugins. 
+# To do this, include an <tt>assets</tt> directory within your plugin, and put
+# your javascripts, stylesheets and images in subdirectories of that folder:
+#
+#   my_plugin
+#     |- init.rb
+#     |- lib/
+#     |- assets/
+#          |- javascripts/
+#          |    |- my_functions.js
+#          |
+#          |- stylesheets/
+#          |    |- my_styles.css
+#          |
+#          |- images/
+#               |- my_face.jpg
+#
+# Files within the <tt>asset</tt> structure are automatically mirrored into
+# a publicly-accessible folder each time your application starts (see
+# Plugin#mirror_public_assets).
+#
+#
+# == Using plugin assets in views
+#
+# It's also simple to use Rails' helpers in your views to use plugin assets.
+# The default helper methods have been enhanced by the engines plugin to accept
+# a <tt>:plugin</tt> option, indicating the plugin containing the desired asset.
+#
+# For example, it's easy to use plugin assets in your layouts:
+#
+#   <%= stylesheet_link_tag "my_styles", :plugin => "my_plugin", :media => "screen" %>
+#   <%= javascript_include_tag "my_functions", :plugin => "my_plugin" %>
+# 
+# ... and similarly in views and partials, it's easy to use plugin images:
+#
+#   <%= image_tag "my_face", :plugin => "my_plugin" %>
+#   <!-- or -->
+#   <%= image_path "my_face", :plugin => "my_plugin" %>
+#
+# Where the default helpers allow the specification of more than one file (i.e. the
+# javascript and stylesheet helpers), you can do similarly for multiple assets from 
+# within a single plugin.
+#
+# ---
+#
+# This module enhances four of the methods from ActionView::Helpers::AssetTagHelper:
+#
+#  * stylesheet_link_tag
+#  * javascript_include_tag
+#  * image_path
+#  * image_tag
+#
+# Each one of these methods now accepts the key/value pair <tt>:plugin => "plugin_name"</tt>,
+# which can be used to specify the originating plugin for any assets.
+#
+module Engines::RailsExtensions::PublicAssetHelpers
+  def self.included(base) #:nodoc:
+    base.class_eval do
+      [:stylesheet_link_tag, :javascript_include_tag, :image_path, :image_tag].each do |m|
+        alias_method_chain m, :engine_additions
+      end
+    end
+  end
+  
+  # Adds plugin functionality to Rails' default stylesheet_link_tag method.
+  def stylesheet_link_tag_with_engine_additions(*sources)
+    stylesheet_link_tag_without_engine_additions(*Engines::RailsExtensions::PublicAssetHelpers.pluginify_sources("stylesheets", *sources))
+  end
+
+  # Adds plugin functionality to Rails' default javascript_include_tag method.  
+  def javascript_include_tag_with_engine_additions(*sources)
+    javascript_include_tag_without_engine_additions(*Engines::RailsExtensions::PublicAssetHelpers.pluginify_sources("javascripts", *sources))
+  end
+  
+  #--
+  # Our modified image_path now takes a 'plugin' option, though it doesn't require it
+  #++
+  
+  # Adds plugin functionality to Rails' default image_path method.
+  def image_path_with_engine_additions(source, options={})
+    options.stringify_keys!
+    source = Engines::RailsExtensions::PublicAssetHelpers.plugin_asset_path(options["plugin"], "images", source) if options["plugin"]
+    image_path_without_engine_additions(source)
+  end
+  
+  # Adds plugin functionality to Rails' default image_tag method.
+  def image_tag_with_engine_additions(source, options={})
+    options.stringify_keys!
+    if options["plugin"]
+      source = Engines::RailsExtensions::PublicAssetHelpers.plugin_asset_path(options["plugin"], "images", source)
+      options.delete("plugin")
+    end
+    image_tag_without_engine_additions(source, options)
+  end
+  
+  #--
+  # The following are methods on this module directly because of the weird-freaky way
+  # Rails creates the helper instance that views actually get
+  #++
+  
+  # Convert sources to the paths for the given plugin, if any plugin option is given
+  def self.pluginify_sources(type, *sources)
+    options = sources.last.is_a?(Hash) ? sources.pop.stringify_keys : { }
+    sources.map! { |s| plugin_asset_path(options["plugin"], type, s) } if options["plugin"]
+    options.delete("plugin") # we don't want it appearing in the HTML
+    sources << options # re-add options      
+  end  
+
+  # Returns the publicly-addressable relative URI for the given asset, type and plugin
+  def self.plugin_asset_path(plugin_name, type, asset)
+    raise "No plugin called '#{plugin_name}' - please use the full name of a loaded plugin." if Rails.plugins[plugin_name].nil?
+    "/#{Rails.plugins[plugin_name].public_asset_directory}/#{type}/#{asset}"
+  end
+end
+
+::ActionView::Helpers::AssetTagHelper.send(:include, Engines::RailsExtensions::PublicAssetHelpers)

data/vendor/plugins/engines/lib/engines/rails_extensions/rails.rb

@@ -0,0 +1,20 @@
+# In order to give a richer infrastructure for dealing with plugins, the engines
+# plugin adds two new attributes to the Rails module:
+#
+# [+plugins+]       A PluginList instance which holds the currently loaded plugins
+# [+configuration+] The current Rails::Configuration instance, so that we can
+#                   query any parameters that might be set *after* Rails has
+#                   loaded, as well as during plugin initialization
+#
+#--
+# Here we just re-open the Rails module and add our custom accessors; it
+# may be cleaner to seperate them into a module, but in this case that seems
+# like overkill.
+#++
+module Rails
+  # The set of all loaded plugins
+  mattr_accessor :plugins
+  
+  # The Rails::Initializer::Configuration object
+  mattr_accessor :configuration
+end

data/vendor/plugins/engines/lib/engines/rails_extensions/rails_initializer.rb

@@ -0,0 +1,86 @@
+# Enhances the Rails::Initializer class to be a bit smarter about
+# plugins. See Engines::RailsExtensions::RailsInitializer for more
+# details.
+
+require "engines/rails_extensions/rails"
+require 'engines/plugin_list'
+
+# The engines plugin changes the way that Rails actually loads other plugins.
+# It creates instances of the Plugin class to represent each plugin, stored
+# in the <tt>Rails.plugins</tt> PluginList.
+#
+# ---
+#
+# Three methods from the original Rails::Initializer module are overridden
+# by Engines::RailsExtensions::RailsInitializer:
+#
+# [+load_plugin+] which now creates Plugin instances and calls Plugin#load
+# [+after_initialize+] which now performs Engines.after_initialize in addition
+#                      to the given config block
+# [<tt>plugin_enabled?</tt>]  which now respects the result of 
+#                             Engines.load_all_plugins?
+#
+module Engines::RailsExtensions::RailsInitializer
+  def self.included(base) #:nodoc:
+    base.class_eval do
+      alias_method_chain :load_plugin, :engine_additions
+      alias_method_chain :after_initialize, :engine_additions
+      alias_method_chain :plugin_enabled?, :engine_additions    
+    end
+  end
+  
+  # Loads all plugins in configuration.plugin_paths, regardless of the contents
+  # of configuration.plugins
+  def load_all_plugins
+    # a nil value implies we don't care about plugins; load 'em all in a reliable order
+    find_plugins(configuration.plugin_paths).sort.each { |path| load_plugin path }
+  end
+  
+  # Loads a plugin, performing the extra load path/public file magic of
+  # engines by calling Plugin#load.
+  def load_plugin_with_engine_additions(directory)
+    name = plugin_name(directory)
+    return false if loaded_plugins.include?(name)
+    
+    logger.debug "loading plugin from #{directory} with engine additions"
+    
+    # add the Plugin object
+    plugin = Plugin.new(plugin_name(directory), directory)
+    Rails.plugins << plugin
+          
+    # do the other stuff that load_plugin used to do. This includes
+    # allowing the plugin's init.rb to set configuration options on
+    # it's instance, which can then be used in it's initialization
+    load_plugin_without_engine_additions(directory)
+
+    # perform additional loading tasks like mirroring public assets
+    # and adding app directories to the appropriate load paths
+    plugin.load
+          
+    true
+  end
+  
+  # Allow the engines plugin to do whatever it needs to do after Rails has
+  # loaded, and then call the actual after_initialize block. Currently, this
+  # is call Engines.after_initialize.
+  def after_initialize_with_engine_additions
+    Engines.after_initialize
+    after_initialize_without_engine_additions
+  end
+  
+  protected
+  
+    # Returns true if the plugin at the given path should be loaded; false
+    # otherwise. If Engines.load_all_plugins? is true, this method will return
+    # true regardless of the path given.
+    def plugin_enabled_with_engine_additions?(path)
+      Engines.load_all_plugins? || plugin_enabled_without_engine_additions?(path)
+    end
+        
+    # Returns the name of the plugin at the given path.
+    def plugin_name(path)
+      File.basename(path)
+    end    
+end
+
+::Rails::Initializer.send(:include, Engines::RailsExtensions::RailsInitializer)

data/vendor/plugins/engines/lib/engines/rails_extensions/routing.rb

@@ -0,0 +1,77 @@
+# Effective use of Rails' routes can help create a tidy and elegant set of URLs,
+# and is a significant part of creating an external API for your web application.
+# 
+# When developing plugins which contain controllers, it seems obvious that including
+# the corresponding routes would be extremely useful. This is particularly true
+# when exposing RESTful resources using the new REST-ian features of Rails 1.2.
+#
+# == Including routes in your plugin
+#
+# The engines plugin makes it possible to include a set of routes within your plugin
+# very simply, as it turns out. In your plugin, you simply include a <tt>routes.rb</tt> 
+# file like the one below at the root of your plugin:
+# 
+#   connect "/login", :controller => "my_plugin/account", :action => "login"
+#
+#   # add a named route
+#   logout "/logout", :controller => "my_plugin/account", :action => "logout"
+#
+#   # some restful stuff
+#   resources :things do |t|
+#     t.resources :other_things
+#   end
+# 
+# Everywhere in a normal <tt>RAILS_ROOT/config/routes.rb</tt> file 
+# where you might have <tt>map.connect</tt>, you just use <tt>connect</tt> in your 
+# plugin's <tt>routes.rb</tt>.
+# 
+# === Hooking it up in your application
+#
+# While it would be possible to have each plugin's routes automagically included into
+# the application's route set, to do so would actually be a stunningly bad idea. Route
+# priority is the key issue here. You, the application developer, needs to be in complete
+# control when it comes to specifying the priority of routes in your application, since 
+# the ordering of your routes directly affects how Rails will interpret incoming requests.
+# 
+# To add plugin routes into your application's <tt>routes.rb</tt> file, you need to explicitly 
+# map them in using the Engines::RailsExtensions::Routing#from_plugin method:
+# 
+#   ApplicationController::Routing::Routes.draw do |map|
+#
+#     map.connect "/app_stuff", :controller => "application_thing" # etc...
+#
+#     # This line includes the routes from the given plugin at this point, giving you
+#     # control over the priority of your application routes 
+#     map.from_plugin :your_plugin
+#
+#     map.connect ":controller/:action/:id"
+#   end
+# 
+# By including routes in plugins which have controllers, you can now share in a simple way 
+# a compact and elegant URL scheme which corresponds to those controllers.
+#
+# ---
+#
+# The Engines::RailsExtensions::Routing module defines extensions to Rails' 
+# routing (ActionController::Routing) mechanism such that routes can be loaded 
+# from a given plugin.
+#
+# The key method is Engines::RailsExtensions::Routing#from_plugin, which can be called 
+# within your application's <tt>config/routes.rb</tt> file to load plugin routes at that point.
+#
+module Engines::RailsExtensions::Routing
+  # Loads the set of routes from within a plugin and evaluates them at this
+  # point within an application's main <tt>routes.rb</tt> file.
+  #
+  # Plugin routes are loaded from <tt><plugin_root>/routes.rb</tt>.
+  def from_plugin(name)
+    # At the point in which routing is loaded, we cannot guarantee that all
+    # plugins are in Rails.plugins, so instead we need to use find_plugin_path
+    path = Engines.find_plugin_path(name)
+    routes_path = File.join(path, name.to_s, "routes.rb")
+    logger.debug "loading routes from #{routes_path}"
+    eval(IO.read(routes_path), binding, routes_path) if File.file?(routes_path)
+  end
+end
+
+::ActionController::Routing::RouteSet::Mapper.send(:include, Engines::RailsExtensions::Routing)

data/vendor/plugins/engines/lib/engines/rails_extensions/templates.rb

@@ -0,0 +1,140 @@
+# As well as providing code overloading for controllers and helpers 
+# (see Engines::RailsExtensions::Dependencies), the engines plugin also allows
+# developers to selectively override views and partials within their application.
+#
+# == An example
+#
+# This is achieved in much the same way as controller overriding. Our plugin contains
+# a view to be rendered at the URL <tt>/test/hello</tt>, in 
+# <tt>our_plugin/app/views/test/hello.rhtml</tt>:
+#
+#    <div class="greeting">Hi, <%= @dude.name %>, what's up?</div>
+#
+# If in a particular application we're not happy with this message, we can override
+# it by replacing the partial in our own application - 
+# <tt>RAILS_ROOT/app/views/test/hello.rhtml</tt>:
+#
+#     <div class="greeting custom_class">Wassup <%= @dude.name %>. 
+#                                        Waaaaassaaaaaaaaup</div>
+#
+# This view will then be rendered in favour of that in the plugin.
+#
+module Engines::RailsExtensions::Templates
+  
+  # Override the finding of partials and views. This is achieved by wrapping
+  # the (private) method #full_template_path_with_engine_additions, that checks
+  # for the given template within plugins as well as the application.
+  module ActionView
+    def self.included(base) #:nodoc:
+      base.class_eval { alias_method_chain :full_template_path, :engine_additions }
+    end
+
+    private
+      def full_template_path_with_engine_additions(template_path, extension)
+        path_in_app_directory = full_template_path_from_application(template_path, extension)
+      
+        # First check for this template in the application. If it exists, the user has
+        # overridden anything from the plugin, so use it (unless we're testing plugins;
+        # see full_template_path_from_application())
+        return path_in_app_directory if path_in_app_directory && File.exist?(path_in_app_directory)
+      
+        # Otherwise, check in the plugins to see if the template can be found there.
+        # Load this in order so that more recently started plugins will take priority.
+        Rails.plugins.by_precedence do |plugin|
+          plugin_specific_path = File.join(plugin.root, 'app', 'views',  
+                                         template_path.to_s + '.' + extension.to_s)
+          return plugin_specific_path if File.exist?(plugin_specific_path)
+        end
+
+        # If it cannot be found anywhere, return the default path.
+        return full_template_path_without_engine_additions(template_path, extension)
+      end 
+  
+      # Return a path to this template within our default app/views directory.
+      # In some circumstances, we may wish to prevent users from overloading views,
+      # such as when we are testing plugins with views. In this case, return "".
+      def full_template_path_from_application(template_path, extension)
+        if Engines.disable_application_view_loading
+          nil
+        else
+          full_template_path_without_engine_additions(template_path, extension)
+        end    
+      end
+  end
+
+
+  # The Layout module overrides a single (private) method in ActionController::Layout::ClassMethods,
+  # called #layout_list. This method now returns an array of layouts, including those in plugins.
+  module Layout
+    def self.included(base) #:nodoc:
+      base.class_eval { alias_method_chain :layout_list, :engine_additions }
+    end
+
+    private
+      # Return the list of layouts, including any in the <tt>app/views/layouts</tt>
+      # directories of loaded plugins.
+      def layout_list_with_engine_additions
+        plugin_layouts = Rails.plugins.by_precedence.map do |p| 
+          File.join(p.root, "app", "views", "layouts")
+        end
+        layout_list_without_engine_additions + Dir["{#{plugin_layouts.join(",")}}/**/*"]
+      end
+  end
+  
+  
+  # The way ActionMailer is coded in terms of finding templates is very restrictive, to the point
+  # where all templates for rendering must exist under the single base path. This is difficult to
+  # work around without re-coding significant parts of the action mailer code.
+  #
+  # ---
+  #
+  # The MailTemplates module overrides two (private) methods from ActionMailer to enable mail 
+  # templates within plugins:
+  #
+  # [+template_path+]  which now produces the contents of #template_paths
+  # [+render+]         which now find the first matching template and creates an ActionVew::Base
+  #                    instance with the correct @base_path for that template
+  module MailTemplates
+    def self.included(base) #:nodoc:
+      base.class_eval do
+        alias_method_chain :template_path, :engine_additions
+        alias_method_chain :render, :engine_additions
+      end
+    end
+
+    private    
+      # Returns all possible template paths for the current mailer, including those
+      # within the loaded plugins.
+      def template_paths
+        paths = Rails.plugins.by_precedence.map { |p| "#{p.root}/app/views/#{mailer_name}" }
+        paths.unshift(template_path_without_engine_additions) unless Engines.disable_application_view_loading
+        paths
+      end
+      
+      # Return something that Dir[] can glob against. This method is called in 
+      # ActionMailer::Base#create! and used as part of an argument to Dir. We can
+      # take advantage of this by using some of the features of Dir.glob to search
+      # multiple paths for matching files.
+      def template_path_with_engine_additions
+        "{#{template_paths.join(",")}}"
+      end
+      
+      # We've broken this up so that we can dynamically alter the base_path that ActionView
+      # is rendering from so that templates can be located from plugins.
+      def render_with_engine_additions(opts)
+        template_path_for_method = Dir["#{template_path}/#{opts[:file]}*"].first
+        body = opts.delete(:body)
+        i = initialize_template_class(body)
+        i.base_path = File.dirname(template_path_for_method)
+        i.render(opts)
+      end
+  end
+end
+
+
+::ActionView::Base.send(:include, Engines::RailsExtensions::Templates::ActionView)
+::ActionController::Layout::ClassMethods.send(:include, Engines::RailsExtensions::Templates::Layout)
+
+if Object.const_defined?(:ActionMailer) # We don't need to do this if ActionMailer hasn't been loaded.
+  ::ActionMailer::Base.send(:include, Engines::RailsExtensions::Templates::MailTemplates)
+end

data/vendor/plugins/engines/lib/engines/rails_extensions.rb

@@ -0,0 +1,6 @@
+# This module contains all the extensions that the engines plugin makes to
+# Rails core. Explanations of how each extension works are included as RDoc
+# documentation for each of the modules listed.
+module Engines::RailsExtensions
+  # let's not rely *entirely* on Rails' magic modules. Not just yet.
+end

data/vendor/plugins/engines/lib/engines/testing.rb

@@ -0,0 +1,88 @@
+# Contains the enhancements to assist in testing plugins. See Engines::Testing
+# for more details.
+
+require 'test/unit'
+require 'test_help'
+
+require 'tmpdir'
+require 'fileutils'
+
+# In most cases, Rails' own plugin testing mechanisms are sufficient. However, there
+# are cases where plugins can be given a helping hand in the testing arena. This module 
+# contains some methods to assist when testing plugins that contain fixtures.
+# 
+# == Fixtures and plugins
+#
+# Since Rails' own fixtures method is fairly strict about where files can be loaded from,
+# the simplest approach when running plugin tests with fixtures is to simply copy all
+# fixtures into a single temporary location and inform the standard Rails mechanism to
+# use this directory, rather than RAILS_ROOT/test/fixtures.
+#
+# The Engines::Testing#setup_plugin_fixtures method does this, copying all plugin fixtures
+# into the temporary location before and tests are performed. This behaviour is invoked
+# the the rake tasks provided by the Engines plugin, in the "test:plugins" namespace. If
+# necessary, you can invoke the task manually.
+#
+# If you wish to take advantage of this, add a call to the Engines::Testing.set_fixture_path
+# method somewhere before your tests (in a test_helper file, or above the TestCase itself).
+#
+# = Testing plugins
+#
+# Normally testing a plugin will require that Rails is loaded, unless you are including
+# a skeleton Rails environment or set of mocks within your plugin tests. If you require
+# the Rails environment to be started, you must ensure that this actually happens; while
+# it's not obvious, your tests do not automatically run with Rails loaded.
+#
+# The simplest way to setup plugin tests is to include a test helper with the following
+# contents:
+#
+#   # Load the normal Rails helper. This ensures the environment is loaded
+#   require File.expand_path(File.dirname(__FILE__) + '/../../../../test/test_helper')
+#   # Ensure that we are using the temporary fixture path
+#   Engines::Testing.set_fixture_path
+#
+# Then run tests using the provided tasks (<tt>test:plugins</tt>, or the tasks that the engines
+# plugin provides - <tt>test:plugins:units</tt>, etc.).
+#
+# Alternatively, you can explicitly load the environment by adpating the contents of the
+# default <tt>test_helper</tt>:
+#
+#   ENV["RAILS_ENV"] = "test"
+#   # Note that we are requiring config/environment from the root of the enclosing application.
+#   require File.expand_path(File.dirname(__FILE__) + "/../../../../config/environment")
+#   require 'test_help'
+#
+module Engines::Testing
+  mattr_accessor :temporary_fixtures_directory
+  self.temporary_fixtures_directory = FileUtils.mkdir_p(File.join(Dir.tmpdir, "rails_fixtures"))
+  
+  # Copies fixtures from plugins and the application into a temporary directory 
+  # (Engines::Testing.temporary_fixtures_directory). 
+  # 
+  # If a set of plugins is not given, fixtures are copied from all plugins in order 
+  # of precedence, meaning that plugins can 'overwrite' the fixtures of others if they are 
+  # loaded later; the application's fixtures are copied last, allowing any custom fixtures
+  # to override those in the plugins. If no argument is given, plugins are loaded via
+  # PluginList#by_precedence.
+  #
+  # This method is called by the engines-supplied plugin testing rake tasks
+  def self.setup_plugin_fixtures(plugins=Rails.plugins.by_precedence)
+    
+    # Copy all plugin fixtures, and then the application fixtures, into this directory
+    plugins.each do |plugin| 
+      plugin_fixtures_directory =  File.join(plugin.root, "test", "fixtures")
+      if File.directory?(plugin_fixtures_directory)
+        Engines.mirror_files_from(plugin_fixtures_directory, self.temporary_fixtures_directory)
+      end
+    end
+    Engines.mirror_files_from(File.join(RAILS_ROOT, "test", "fixtures"),
+                              self.temporary_fixtures_directory)
+  end
+  
+  # Sets the fixture path used by Test::Unit::TestCase to the temporary
+  # directory which contains all plugin fixtures.
+  def self.set_fixture_path
+    Test::Unit::TestCase.fixture_path = self.temporary_fixtures_directory
+    $LOAD_PATH.unshift self.temporary_fixtures_directory
+  end
+end