locomotive_plugins 1.0.0.beta4 → 1.0.0.beta5

data/CHANGELOG

@@ -1,8 +1,10 @@
-## 1.0.0
+## v1.0.0
 
 * Added liquid filters
 * Added liquid tags
 * 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)
 
 ## v0.2.1
 

data/README.md

@@ -1,14 +1,15 @@
 
 # Locomotive Plugins [![Build Status](https://secure.travis-ci.org/colibri-software/locomotive_plugins.png)](https://secure.travis-ci.org/colibri-software/locomotive_plugins.png)
 
-Create plugins for [Locomotive CMS](http://locomotivecms.com/).
+This gem is used to develop plugins for [Locomotive
+CMS](http://locomotivecms.com/). Plugins can be enabled or disabled on each
+site individually.
 
 
 ## Installation
 
 To create a Locomotive Plugin, create a ruby gem and then install this gem:
 
-
     gem install locomotive_plugins
 
 Alternatively if you're using Bundler, add the following line to your Gemfile:
@@ -19,27 +20,37 @@ and run `bundle install`.
 
 To install the plugin in LocomotiveCMS, simply [create a LocomotiveCMS
 app](http://doc.locomotivecms.com/installation/getting_started) and add your
-plugin gem to the app's Gemfile.
+plugin gem to the app's Gemfile in the `locomotive_plugins` group:
+
+    group(:locomotive_plugins) do
+      gem 'my_plugin'
+      gem 'another_plugin'
+    end
 
 
 ## Usage
 
 To create a plugin, create a class which includes the `Locomotive::Plugin`
-module and register it as a plugin:
+module:
 
     class BasicAuth
       include Locomotive::Plugin
     end
 
-    LocomotivePlugins.register_plugin(BasicAuth)
+The plugin class will automatically be registered under an ID which is its
+underscored name, in this case, `basic_auth`. To register it under a different
+ID, simply override the class level method `default_plugin_id`:
 
-The plugin will automatically be registered under an ID which is its
-underscored name, in this case, `basic_auth`. To register it under a
-different ID, simply supply the ID in the `register_plugin` call:
+    class BasicAuth
+      include Locomotive::Plugin
 
-    LocomotivePlugins::register_plugin(BasicAuth, 'auth')
+      def self.default_plugin_id
+        'auth'
+      end
+    end
 
-See the sections below for usage examples. Also, see the
+See the sections below for usage examples of the various features. Also, see
+the
 [documentation](http://rubydoc.info/github/colibri-software/locomotive_plugins/).
 
 ### Initialization
@@ -236,21 +247,35 @@ checked, the config hash will be as follows:
 
 ### Database Models
 
-Plugins can persist data in the database through the use of DBModels. A DBModel
-has all the functionality of a Mongoid document. For example:
+Plugins can persist data in Locomotive's database through the use of Database
+Models. A Database Model is simply a Mongoid document which is managed by
+Locomotive CMS. For example:
 
-    class VisitCount < Locomotive::Plugin::DBModel
+    class VisitCount
+      include Mongoid::Document
       field :count, default: 0
     end
 
     class VisitCounter
       include Locomotive::Plugin
 
-      has_one :visit_count, VisitCount
       before_filter :increment_count
 
       def increment_count
-        build_visit_count unless visit_count
         visit_count.count += 1
+        visit_count.save!
+      end
+
+      protected
+
+      def visit_count
+        @visit_count ||= (VisitCount.first || VisitCount.new)
       end
     end
+
+Note that the plugin databases are isolated between Locomotive site instances.
+In other words, if a plugin is enabled on two sites, A and B, and a request
+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.

data/lib/locomotive/plugin.rb

@@ -7,43 +7,47 @@ module Locomotive
 
   # Include this module in a class which should be registered as a Locomotive
   # plugin. See the documentation for the various methods which can be called
-  # or overridden to describe the plugin
+  # or overridden to describe the plugin.
   module Plugin
 
+    include ClassTracker
     include ConfigUI
-    include DBModels
     include Liquid
 
     # @private
+    #
+    # Set up the plugin class with some class methods, callbacks, and plugin
+    # class tracking.
+    #
+    # @param base the plugin class
     def self.included(base)
-      self.add_db_model_class_methods(base)
       self.add_liquid_tag_methods(base)
+
+      base.class_eval do
+        extend ActiveModel::Callbacks
+        define_model_callbacks :filter
+      end
+
       base.extend ClassMethods
+
+      self.track_plugin_class(base)
     end
 
     module ClassMethods
-      # Add a before filter to be called by the underlying controller
+      # Override this method to specify the default plugin_id to use when
+      # Locomotive registers the plugin. This plugin_id may be overridden by
+      # Locomotive CMS.
       #
-      # @param meth[Symbol] the method to call
-      #
-      # @example
-      #   before_filter :my_method
-      def before_filter(meth)
-        @before_filters ||= []
-        @before_filters << meth
-      end
-
-      # Get list of before filters
-      #
-      # @return [Array<Symbol>] an array of the method symbols
-      def before_filters
-        @before_filters ||= []
+      # @return by default, the underscored plugin class name (without the
+      #         namespace)
+      def default_plugin_id
+        to_s.split('::').last.underscore
       end
 
       # Override this method to provide a module or array of modules to include
       # as liquid filters in the site. All public methods in the module will be
       # included as filters after being prefixed with the plugin id
-      # (#\\{plugin_id}_#\\{method_name})
+      # (#\\{plugin_id}_#\\{method_name}).
       #
       # @example
       #   class MyPlugin
@@ -59,7 +63,7 @@ module Locomotive
       # plugin. The return value must be a hash whose keys are the tag names
       # and values are the tag classes. The tag names will be included in
       # Locomotive's liquid renderer after being prefixed with the plugin id
-      # (#\\{plugin_id}_#\\{tag_name})
+      # (#\\{plugin_id}_#\\{tag_name}).
       #
       # @example
       #   class MyPlugin
@@ -70,76 +74,33 @@ module Locomotive
       def liquid_tags
         {}
       end
-
-      # Create a +has_many+ mongoid relationship to objects of the given class.
-      # The given class should be derived from Locomotive::Plugin::DBModel.
-      # This will add the following methods to the plugin object:
-      #
-      # [#\\{name}]   Returns a list of persisted objects
-      #
-      # [#\\{name}=]  Setter for the list of persisted objects
-      #
-      # @param name[String] the name of the relationship
-      #
-      # @param klass[Class] the class of the objects to be stored
-      def has_many(name, klass)
-        self.create_has_many_relationship(name, klass)
-      end
-
-      # Create a +has_one+ mongoid relationship to an object of the given
-      # class.  The given class should be derived from
-      # Locomotive::Plugin::DBModel. This will add the following methods to the
-      # plugin object:
-      #
-      # [#\\{name}]         Returns the related object
-      #
-      # [#\\{name}=]        Setter for the related object
-      #
-      # [build_#\\{name}]   Builds the related object
-      #
-      # [create_#\\{name}]  Builds and saves the related object
-      #
-      # @param name[String] the name of the relationship
-      #
-      # @param klass[Class] the class of the object to be stored
-      def has_one(name, klass)
-        self.create_has_one_relationship(name, klass)
-      end
     end
 
     # This variable is set by LocomotiveCMS. It contains the controller which
-    # is handling the current request
+    # is handling the current request.
     attr_accessor :controller
 
     # This variable is set by LocomotiveCMS. It contains the current
-    # configuration hash for the plugin
+    # configuration hash for the plugin.
     attr_accessor :config
 
     # Initialize by supplying the current config parameters. Note that this
     # method should not be overridden for custom initialization of plugin
-    # objects. Instead, override the initialize_plugin method. If given a
-    # block, the block will be called with `self` as an argument before the
-    # `initialize_plugin` method is called. This is used by LocomotiveCMS to
-    # perform some custom initialization before the plugin's initialization is
-    # called.
+    # objects. Instead, override the initialize_plugin method.
+    #
+    # @param config the configuration hash
     def initialize(config)
       self.config = config
-      yield self if block_given?
       self.initialize_plugin
     end
 
     # Override this method to supply custom initialization code for the plugin
-    # object. <b>Do not override the normal +initialize+ method</b>
+    # object. <b>Do not override the normal +initialize+ method</b>.
     def initialize_plugin
     end
 
-    # Get all before filters which have been added to the controller
-    def before_filters
-      self.class.before_filters
-    end
-
     # Override this method to provide a liquid drop which should be available
-    # in the CMS
+    # in the CMS.
     def to_liquid
       nil
     end
@@ -155,9 +116,12 @@ module Locomotive
     # for the config UI. The HTML string may be a Handlebars.js template. By
     # default, this method will use the file supplied by the
     # +config_template_file+ method to construct the string (see
-    # #config_template_file)
+    # #config_template_file).
+    #
+    # @return by default, the contents of +config_template_file+, parsed by
+    #         HAML if needed
     def config_template_string
-      self.default_config_template_string
+      self.default_config_template_string(self.config_template_file)
     end
 
   end

data/lib/locomotive/plugin/class_tracker.rb

@@ -0,0 +1,54 @@
+
+module Locomotive
+  module Plugin
+    # Tracks classes which include the Locomotive::Plugin module. Also allows
+    # external classes to provide a tracker. A tracker is a block which will be
+    # called when a class includes Locomotive::Plugin. The class object will be
+    # handed into the block as a parameter.
+    module ClassTracker
+
+      # Set up class tracking on the module which has included this module.
+      # This will set up the following methods:
+      #
+      # [plugin_classes]  Returns the set of plugin classes which have
+      #                   included Locomotive::Plugin
+      #
+      # [track_plugin_class]  Keeps track of the plugin class which has been
+      #                       added. Also calls all plugin trackers
+      #
+      # [add_plugin_class_tracker]  Add a block which is called when a plugin
+      #                             class is tracked. The block will be given
+      #                             the class to be tracked
+      #
+      # @param mod the module to add the tracking to
+      def self.included(mod)
+        mod.instance_eval do
+          @plugin_classes = Set.new
+          @trackers = []
+
+          class << self
+            attr_reader :plugin_classes
+          end
+
+          def track_plugin_class(klass)
+            @plugin_classes << klass
+            _call_trackers(klass)
+          end
+
+          def add_plugin_class_tracker(&block)
+            @trackers << block
+          end
+
+          private
+
+          def _call_trackers(klass)
+            @trackers.each do |tracker|
+              tracker.call(klass)
+            end
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/locomotive/plugin/config_ui.rb

@@ -1,14 +1,21 @@
 
 module Locomotive
   module Plugin
-    # @private
+    # @api internal
+    #
+    # Helpers for setting up configuration UI.
     module ConfigUI
 
       protected
 
-      def default_config_template_string
-        filepath = self.config_template_file
-
+      # By default, fetch the contents of the file given by
+      # +config_template_file+. If it is HAML, convert it to HTML. Then return
+      # the contents.
+      #
+      # @param filepath [String] the file path to read from
+      # @return the contents of the file at +filepath+, parsed by HAML if
+      #         needed
+      def default_config_template_string(filepath)
         if filepath
           filepath = filepath.to_s
           if filepath.end_with?('haml')

data/lib/locomotive/plugin/liquid.rb

@@ -1,27 +1,78 @@
 
 module Locomotive
   module Plugin
+    # This module adds liquid handling methods to the plugin class.
     module Liquid
 
       # @private
+      #
+      # Add class methods.
+      #
+      # @param base the class which includes this module
       def self.included(base)
         base.extend(ClassMethods)
       end
 
-      # @private
+      # @api internal
       module ClassMethods
+        # Adds methods from LiquidClassMethods module.
+        #
+        # @param base the plugin class to extend LiquidClassMethods
         def add_liquid_tag_methods(base)
-          base.extend(LiquidTagMethods)
+          base.extend(LiquidClassMethods)
         end
       end
 
-      module LiquidTagMethods
+      # This module adds class methods to the plugin class in order to generate
+      # the prefixed liquid filter module and generate and register the
+      # prefixed liquid tag classes.
+      module LiquidClassMethods
+
+        # Gets the module to include as a filter in liquid. It prefixes the
+        # filter methods with the given string followed by an underscore.
+        #
+        # @param prefix [String] the prefix to use
+        # @return the module to use as a filter module
+        def prefixed_liquid_filter_module(prefix)
+          # Create the module to be returned
+          @prefixed_liquid_filter_module = Module.new do
+            include ::Locomotive::Plugin::Liquid::PrefixedFilterModule
+          end
+
+          # Add the prefixed methods to the module
+          raw_filter_modules = [self.liquid_filters].flatten.compact
+          raw_filter_modules.each do |mod|
+            mod.public_instance_methods.each do |meth|
+              @prefixed_liquid_filter_module.module_eval do
+                define_method(:"#{prefix}_#{meth}") do |input|
+                  self._passthrough_filter_call(prefix, meth, input)
+                end
+              end
+            end
+          end
+
+          # Add a method which returns the modules to include for this prefix
+          @prefixed_liquid_filter_module.module_eval do
+            protected
+
+            define_method(:"_modules_for_#{prefix}") do
+              raw_filter_modules
+            end
+          end
+
+          @prefixed_liquid_filter_module
+        end
 
         # Returns a hash of tag names and tag classes to be registered in the
-        # liquid environment. The tag names are prefixed by the given prefix,
-        # and the tag classes are modified so that they check the liquid
-        # context to determine whether they are enabled and should render
-        # normally
+        # liquid environment. The tag names are prefixed by the given prefix
+        # followed by an underscore, and the tag classes are modified so that
+        # they check the liquid context to determine whether they are enabled
+        # and should render normally. This check is done by determining whether
+        # the tag class is in the +:enabled_plugin_tags+ register in the liquid
+        # context object (see +setup_liquid_context+).
+        #
+        # @param prefix [String] the prefix to use
+        # @return a hash of tag names to tag classes
         def prefixed_liquid_tags(prefix)
           self.liquid_tags.inject({}) do |hash, (tag_name, tag_class)|
             hash["#{prefix}_#{tag_name}"] = tag_subclass(prefix, tag_class)
@@ -29,9 +80,23 @@ module Locomotive
           end
         end
 
+        # Registers the tags given by +prefixed_liquid_tags+ in the liquid
+        # template system.
+        #
+        # @param prefix [String] the prefix to give to +prefixed_liquid_tags+
+        def register_tags(prefix)
+          prefixed_liquid_tags(prefix).each do |tag_name, tag_class|
+            ::Liquid::Template.register_tag(tag_name, tag_class)
+          end
+        end
+
         protected
 
-        # Creates a nested subclass to handle rendering this tag
+        # Creates a nested subclass to handle rendering the given tag.
+        #
+        # @param prefix [String] the prefix for the tag class
+        # @param tag_class the liquid tag class to subclass
+        # @return the appropriate tag subclass
         def tag_subclass(prefix, tag_class)
           tag_class.class_eval <<-CODE
             class TagSubclass < #{tag_class.to_s}
@@ -47,36 +112,30 @@ module Locomotive
 
       end
 
-      # Gets the module to include as a filter in liquid. It prefixes the
-      # filter methods with the given string
-      def prefixed_liquid_filter_module(prefix)
-        # Create the module to be returned
-        @prefixed_liquid_filter_module = Module.new do
-          include ::Locomotive::Plugin::Liquid::PrefixedFilterModule
-        end
-
-        # Add the prefixed methods to the module
-        raw_filter_modules = [self.class.liquid_filters].flatten.compact
-        raw_filter_modules.each do |mod|
-          mod.public_instance_methods.each do |meth|
-            @prefixed_liquid_filter_module.module_eval do
-              define_method(:"#{prefix}_#{meth}") do |input|
-                self._passthrough_filter_call(prefix, meth, input)
-              end
-            end
-          end
+      # Setup the liquid context object for rendering plugin liquid code. It
+      # will add to the context:
+      #
+      # * the prefixed tags. These will go into the +:enabled_plugin_tags+
+      #   register.
+      # * the drop to the hash in the +"plugins"+ liquid variable
+      # * the prefixed filters.
+      #
+      # @param plugin_id [String] the plugin id to use
+      # @param context [Liquid::Context] the liquid context object
+      def setup_liquid_context(plugin_id, context)
+        # Add tags
+        (context.registers[:enabled_plugin_tags] ||= Set.new).tap do |set|
+          set.merge(self.class.prefixed_liquid_tags(plugin_id).values)
         end
 
-        # Add a method which returns the modules to include for this prefix
-        @prefixed_liquid_filter_module.module_eval do
-          protected
-
-          define_method(:"_modules_for_#{prefix}") do
-            raw_filter_modules
-          end
-        end
+        # Add drop with extension
+        drop = self.to_liquid
+        drop.extend(Locomotive::Plugin::Liquid::DropExtension)
+        drop.set_plugin_id(plugin_id)
+        (context['plugins'] ||= {})[plugin_id] = drop
 
-        @prefixed_liquid_filter_module
+        # Add filters
+        context.add_filters(self.class.prefixed_liquid_filter_module(plugin_id))
       end
 
     end