locomotive_plugins 1.0.0.beta6 → 1.0.0.beta7

data/CHANGELOG

@@ -5,6 +5,7 @@
 * Removed content type scoping (use liquid tags instead)
 * Removed DBModels (just use Mongoid and LocomotiveCMS will isolate the models)
 * Added class tracking (used by Locomotive)
+* Added ability to supply a rack app for handling requests
 
 ## v0.2.1
 

data/README.md

@@ -279,3 +279,14 @@ comes in to site A which causes a Mongoid Document to be saved to the database,
 this document will not be accessible to the plugin when a request comes in to
 site B. Thus plugin database models should be developed in the context of a
 single site, since each site will have its own database.
+
+### Rack App
+
+Plugins can supply a Rack Application to be used for request handling. Do so by
+overriding the `rack_app` class method on the plugin class. The plugin object
+can also build URLs and paths for that Rack App without knowledge of where it
+is mounted. This is important because Locomotive will mount the rack
+application on a path based on the plugin's `plugin_id`. Given a string `path`
+which is a path relative to the root of the rack app,
+`plugin_object.full_path(path)` will give the full absolute path and
+`plugin_object.full_url(path)` will give the full URL.

data/lib/locomotive/plugin.rb

@@ -13,6 +13,7 @@ module Locomotive
     include ClassTracker
     include ConfigUI
     include Liquid
+    include RackAppHelpers
 
     # @private
     #
@@ -21,7 +22,8 @@ module Locomotive
     #
     # @param base the plugin class
     def self.included(base)
-      self.add_liquid_tag_methods(base)
+      self.add_liquid_class_methods(base)
+      self.add_rack_app_helper_methods(base)
 
       base.class_eval do
         extend ActiveModel::Callbacks
@@ -74,6 +76,14 @@ module Locomotive
       def liquid_tags
         {}
       end
+
+      # Override this method to supply a rack app to be used for handling
+      # requests. Locomotive CMS will mount this app on a path dependent on the
+      # `plugin_id`. See `RackAppHelpers` for some helper methods.
+      def rack_app
+        nil
+      end
+
     end
 
     # This variable is set by LocomotiveCMS. It contains the controller which

data/lib/locomotive/plugin/exceptions.rb

@@ -0,0 +1,9 @@
+
+module Locomotive
+  module Plugin
+
+    # General Locomotive::Plugin exception
+    class Error < StandardError; end
+
+  end
+end

data/lib/locomotive/plugin/liquid.rb

@@ -18,7 +18,7 @@ module Locomotive
         # Adds methods from LiquidClassMethods module.
         #
         # @param base the plugin class to extend LiquidClassMethods
-        def add_liquid_tag_methods(base)
+        def add_liquid_class_methods(base)
           base.extend(LiquidClassMethods)
         end
       end

data/lib/locomotive/plugin/rack_app_helpers.rb

@@ -0,0 +1,92 @@
+
+module Locomotive
+  module Plugin
+    # This module adds helpers for handling the Rack app supplied by the
+    # `rack_app` method.
+    module RackAppHelpers
+
+      # @private
+      #
+      # Add class methods.
+      #
+      # @param base the class which includes this module
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # @api internal
+      module ClassMethods
+        # Adds methods from RackAppHelpersClassMethods module.
+        #
+        # @param base the plugin class to extend LiquidClassMethods
+        def add_rack_app_helper_methods(base)
+          base.extend(RackAppHelpersClassMethods)
+        end
+      end
+
+      # This module adds class methods for managing the mount point for the
+      # Rack App. The mount point must be set in order to properly generate
+      # paths and URLs.
+      module RackAppHelpersClassMethods
+        # Set the full URL mountpoint for the Rack app. This will be set by
+        # Locomotive CMS. The URL must be an HTTP or HTTPS url with no query
+        # parameters or hash fragments.
+        #
+        # @param url [String] the full URL that the Rack app is mounted on
+        def set_mountpoint(url)
+          error = lambda do |msg|
+            raise Error, "Invalid mountpoint: #{msg}"
+          end
+
+          uri = URI(url)
+          unless uri.scheme =~ /^https?$/
+            error.call('only http or https allowed')
+          end
+          if uri.fragment
+            error.call('no hash fragment allowed')
+          end
+          if uri.query
+            error.call('no query string allowed')
+          end
+
+          @mountpoint = uri
+        end
+
+        # Get the mountpoint for this plugin class's Rack app.
+        #
+        # @return the mountpoint
+        def mountpoint
+          @mountpoint
+        end
+      end
+
+      # Generate the full absolute path for the given path based on the
+      # mountpoint of this plugin's rack app.
+      #
+      # @param path [String]  the path relative to the mountpoint of the rack
+      #                       app
+      # @return the absolute path
+      def full_path(path)
+        [ mountpoint.path.sub(%r{/+$}, ''), path.sub(%r{^/+}, '') ].join('/')
+      end
+
+      # Generate the full URL for the given path based on the mountpoint of
+      # this plugin's rack app.
+      #
+      # @param path [String]  the path relative to the mountpoint of the rack
+      #                       app
+      # @return the URL
+      def full_url(path)
+        [ mountpoint.to_s.sub(%r{/+$}, ''), path.sub(%r{^/+}, '') ].join('/')
+      end
+
+      # Get the mountpoint for this plugin's Rack app.
+      #
+      # @return the mountpoint
+      def mountpoint
+        self.class.mountpoint
+      end
+
+    end
+  end
+end

data/lib/version.rb

@@ -1,3 +1,3 @@
 module LocomotivePlugins
-  VERSION = '1.0.0.beta6'
+  VERSION = '1.0.0.beta7'
 end

data/spec/lib/locomotive/plugin/rack_app_helpers_spec.rb

@@ -0,0 +1,66 @@
+
+require 'spec_helper'
+
+module Locomotive
+  module Plugin
+    describe RackAppHelpers do
+
+      before(:all) do
+        PluginWithRackApp.set_mountpoint('http://www.example.com/my/path')
+      end
+
+      before(:each) do
+        @config = {}
+        @plugin = PluginWithRackApp.new(@config)
+      end
+
+      it 'should supply an absolute path based on where it is mounted' do
+        @plugin.full_path('/plugin/path').should == '/my/path/plugin/path'
+        @plugin.full_path('another//path').should == '/my/path/another//path'
+      end
+
+      it 'should supply a full URL based on where it is mounted' do
+        @plugin.full_url('/plugin/path').should ==
+          'http://www.example.com/my/path/plugin/path'
+        @plugin.full_url('another//path').should ==
+          'http://www.example.com/my/path/another//path'
+      end
+
+      it 'should only allow URLs with proper format' do
+        old_mountpoint = PluginWithRackApp.mountpoint
+
+        bad_mountpoints = [
+          'my/path',
+          'my.server.com/my/path',
+          'ftp://my.server.com',
+          'http://my.server.com/my/path?q=value',
+          'http://my.server.com/my/path#fragment',
+          'https://my.server.com/my/path?q=value',
+          'https://my.server.com/my/path#fragment'
+        ]
+
+        good_mountpoints = [
+          'http://my.server.com/my/path',
+          'http://my.server.com:3000/my/path',
+          'https://my.server.com/my/path',
+          'https://my.server.com:3000/my/path'
+        ]
+
+        bad_mountpoints.each do |mountpoint|
+          lambda do
+            PluginWithRackApp.set_mountpoint(mountpoint)
+          end.should raise_exception(Locomotive::Plugin::Error)
+          PluginWithRackApp.mountpoint.should == old_mountpoint
+        end
+
+        good_mountpoints.each do |mountpoint|
+          lambda do
+            PluginWithRackApp.set_mountpoint(mountpoint)
+          end.should_not raise_exception
+          PluginWithRackApp.mountpoint.to_s.should == mountpoint
+        end
+      end
+
+    end
+  end
+end

data/spec/lib/locomotive/plugin_spec.rb

@@ -47,5 +47,10 @@ module Locomotive
       }
     end
 
+    it 'should optionally supply a Rack application' do
+      UselessPlugin.rack_app.should be_nil
+      PluginWithRackApp.rack_app.should_not be_nil
+    end
+
   end
 end

data/spec/support/plugins/plugin_with_rack_app.rb

@@ -0,0 +1,10 @@
+
+class PluginWithRackApp
+  include Locomotive::Plugin
+
+  def self.rack_app
+    Proc.new do
+      [200, {'Content-Type' => 'text/html'}, []]
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: locomotive_plugins
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta6
+  version: 1.0.0.beta7
   prerelease: 6
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-17 00:00:00.000000000 Z
+date: 2013-01-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: locomotive_liquid
@@ -117,10 +117,12 @@ files:
 - Rakefile
 - lib/locomotive/plugin/liquid.rb
 - lib/locomotive/plugin/class_tracker.rb
+- lib/locomotive/plugin/exceptions.rb
 - lib/locomotive/plugin/liquid/prefixed_filter_module.rb
 - lib/locomotive/plugin/liquid/drop_extension.rb
 - lib/locomotive/plugin/liquid/tag_subclass_methods.rb
 - lib/locomotive/plugin/liquid/context_helpers.rb
+- lib/locomotive/plugin/rack_app_helpers.rb
 - lib/locomotive/plugin/config_ui.rb
 - lib/locomotive/plugin.rb
 - lib/version.rb
@@ -133,10 +135,12 @@ files:
 - spec/support/plugins/plugin_with_filter.rb
 - spec/support/plugins/plugin_with_many_filter_modules.rb
 - spec/support/plugins/my_plugin.rb
+- spec/support/plugins/plugin_with_rack_app.rb
 - spec/support/factories.rb
 - spec/fixtures/config_template.haml
 - spec/fixtures/config_template.html
 - spec/lib/locomotive/plugin/class_tracker_spec.rb
+- spec/lib/locomotive/plugin/rack_app_helpers_spec.rb
 - spec/lib/locomotive/plugin/liquid/context_helpers_spec.rb
 - spec/lib/locomotive/plugin/liquid_spec.rb
 - spec/lib/locomotive/plugin/config_ui_spec.rb