locomotive_plugins 1.0.0.beta2

data/CHANGELOG

@@ -0,0 +1,26 @@
+## 1.0.0
+
+* Added liquid filters
+* Added liquid tags
+* Removed content type scoping (use liquid tags instead)
+
+## v0.2.1
+
+* Added custom initialization for plugins
+
+## v0.2.0
+
+* Added DBModel functionality
+
+## v0.1.1
+
+* Fixed bug with non-string filepaths, such as Rails Pathname object
+
+## v0.1.0
+
+* Plugins can supply a config UI in HTML or HAML
+* Added config variable for plugins
+* Added before_filters for plugins
+* Setup plugin registration
+* Added plugin liquid drops
+* Added content_type_scope

data/README.md

@@ -0,0 +1,229 @@
+
+# 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/).
+
+
+## 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:
+
+    gem 'locomotive_plugins'
+
+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.
+
+
+## Usage
+
+To create a plugin, create a class which includes the `Locomotive::Plugin`
+module and register it as a plugin:
+
+    class BasicAuth
+      include Locomotive::Plugin
+    end
+
+    LocomotivePlugins.register_plugin(BasicAuth)
+
+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:
+
+    LocomotivePlugins::register_plugin(BasicAuth, 'auth')
+
+### Initialization
+
+To initialize a plugin object, do not override the `initialize` method because
+this method is defined by the `Locomotive::Plugin` module and used by
+Locomotive. Instead, override the `initialize_plugin` method.
+
+    class MyPlugin
+      include Locomotive::Plugin
+
+      def initialize_plugin
+        # Custom initialization code
+      end
+    end
+
+### Before filters
+
+A plugin may add a before filter which is run before every page load on the
+website being hosted in Locomotive CMS. The before filter has access to the
+controller which is being invoked, and a config variable which is set within
+the Locomotive UI.
+
+    class BasicAuth
+      include Locomotive::Plugin
+
+      before_filter :authenticate
+
+      def authenticate
+        if self.config[:use_basic_auth]
+          self.controller.authenticate_or_request_with_http_basic do |username, password|
+            username = USER_ID && password == PASSWORD
+          end
+        end
+      end
+    end
+
+### Liquid
+
+#### Drops
+
+A plugin can add a liquid drop which can be accessed from page templates in
+LocomotiveCMS. To do so, override the `to_liquid` method.
+
+Plugin code:
+
+    class BasicAuth
+      include Locomotive::Plugin
+
+      def to_liquid
+        { :userid => self.get_authenticated_user_id }
+      end
+    end
+
+Liquid code:
+
+    <p>Your User ID is: {{ plugins.basic_auth.userid }}</p>
+
+This liquid code assumes that the plugin has been registered under the default
+ID as described above.
+
+#### Filters
+
+A plugin can add liquid filters:
+
+    module Filters
+
+      def add_http(input)
+        if input.start_with?('http://')
+          input
+        else
+          "http://#{input}"
+        end
+      end
+
+    end
+
+    class MyPlugin
+      include Locomotive::Plugin
+
+      def self.liquid_filters
+        Filters
+      end
+    end
+
+Locomotive will automatically prefix the filter with the plugin ID in the
+liquid code:
+
+    <a href="{{ page.link | my_plugin_add_http }}">Click here!</a>
+
+#### Tags
+
+A plugin may also supply custom liquid tags. The custom tag class may override
+the `render_disabled` method to specify what should be rendered if the plugin
+is not enabled. By default, this will be the empty string. For example:
+
+    # Note that Liquid::Block is a subclass of Liquid::Tag
+    class Paragraph < Liquid::Block
+      def render(context)
+        "<p>#{render_all(@nodelist, context)}</p>"
+      end
+
+      def render_disabled(context)
+        render_all(@nodelist, context)
+      end
+    end
+
+    class Newline < Liquid::Tag
+      def render(context)
+        "<br />"
+      end
+    end
+
+    class MyPlugin
+      include Locomotive::Plugin
+
+      def self.liquid_tags
+        {
+          :paragraph => Paragraph,
+          :newline => Newline
+        }
+      end
+    end
+
+Locomotive will automatically prefix the tag with the plugin ID in the liquid
+code. Consider the following liquid code:
+
+    {% my_plugin_paragraph %}Some Text{% endmy_plugin_paragraph %}
+    Some Text{% my_plugin_newline %}
+
+When `MyPlugin` is enabled, the code will be rendered to:
+
+    <p>Some Text</p>
+    Some Text<br />
+
+When `MyPlugin` is disabled, the code will be rendered to:
+
+    Some Text
+    Some Text
+
+### Config UI
+
+Plugins can provide a UI for setting configuration attributes. The UI should be
+written as a [Handlebars.js](http://handlebarsjs.com/) template. When the
+template is rendered, it is supplied with the array of content types in the
+CMS. This can be used, for example, to create a select box for selecting a
+content type to be acted upon by the plugin.
+
+A config UI can be specified by a plugin in a few ways. The preferred method is
+to override the  `config_template_file` method on the plugin class. This method
+must return a path to an HTML or HAML file. For more fine-grained control over
+how the string is generated, the `config_template_string` can be overridden to
+directly supply the HTML string to be rendered.
+
+Here's an example of an HTML config file:
+
+    <li>
+      <label name="my_plugin_config">My Plugin Config</label>
+      <input type="text" name="my_plugin_config">
+      <p class="inline-hints">My Hint</p>
+    </li>
+    <li>
+      <label name="content_type_slugs">Content Types</label>
+      <select name="content_type_slugs" multiple="multiple">
+        {{#each content_types}}
+        <option value="{{ this.slug }}"> {{ this.name }}</option>
+        {{/each}}
+      </select>
+    </li>
+
+### 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:
+
+    class VisitCount < Locomotive::Plugin::DBModel
+      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
+      end
+    end

data/Rakefile

@@ -0,0 +1,13 @@
+require 'rubygems'
+require 'rake'
+
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+require 'version'
+
+require 'bundler/gem_tasks'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/locomotive/plugin.rb

@@ -0,0 +1,162 @@
+
+Dir.glob(File.join(File.dirname(__FILE__), 'plugin', '**', '*.rb')) do |f|
+  require f
+end
+
+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
+  module Plugin
+
+    include ConfigUI
+    include DBModels
+    include Liquid
+
+    # @private
+    def self.included(base)
+      self.add_db_model_class_methods(base)
+      self.add_liquid_tag_methods(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      # Add a before filter to be called by the underlying controller
+      #
+      # @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 ||= []
+      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})
+      #
+      # @example
+      #   class MyPlugin
+      #     def self.liquid_filters
+      #       [ MyFilters, MoreFilters ]
+      #     end
+      #   end
+      def liquid_filters
+        nil
+      end
+
+      # Override this method to specify the liquid tags supplied by this
+      # 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})
+      #
+      # @example
+      #   class MyPlugin
+      #     def self.liquid_tags
+      #       { :my_tag => MyTag, :other_tag => OtherTag }
+      #     end
+      #   end
+      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
+    attr_accessor :controller
+
+    # This variable is set by LocomotiveCMS. It contains the current
+    # 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
+    def initialize(config)
+      self.config = config
+      self.load_or_create_db_model_container!
+      self.save_db_model_container
+      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>
+    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
+    def to_liquid
+      nil
+    end
+
+    # Override this method to supply a path to the config UI template file.
+    # This file should be an HTML or HAML file using the Handlebars.js
+    # templating language.
+    def config_template_file
+      nil
+    end
+
+    # This method may be overridden to supply the raw HTML string to be used
+    # 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)
+    def config_template_string
+      self.default_config_template_string
+    end
+
+  end
+
+end

data/lib/locomotive/plugin/config_ui.rb

@@ -0,0 +1,26 @@
+
+module Locomotive
+  module Plugin
+    # @private
+    module ConfigUI
+
+      protected
+
+      def default_config_template_string
+        filepath = self.config_template_file
+
+        if filepath
+          filepath = filepath.to_s
+          if filepath.end_with?('haml')
+            Haml::Engine.new(IO.read(filepath)).render
+          else
+            IO.read(filepath)
+          end
+        else
+          nil
+        end
+      end
+
+    end
+  end
+end