memorable 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d7fb95cbd8bfc993b815802ff41abe3abf913f4f
-  data.tar.gz: 52fe4c06f792b75c26a461057ceb477b206ee30d
+  metadata.gz: f4605915b94644c1cf4eec46d551ea971637c61b
+  data.tar.gz: 1d8e9deda6b5a1cb73dd82cd078d2bc108234a2f
 SHA512:
-  metadata.gz: 746e7e131f7f1cd71c11e53a19ae00bc7e26eeb467af2026a59c400554555129d06c7a1fe765c5249264d2c688299d825eae0226e69ec809d02b52fac878f61e
-  data.tar.gz: 3a728d5a5021dee59581388cbd8493c554e95db98b86ce73c68906d1f222b3dc21b884f7f6d463537c71194f6ac66ffabd84d0e61ca8679487899190e5418267
+  metadata.gz: 017ee728f18ac91a52790617457d9910e6f9025a14ef2d75c34ecff817bc67dcb6ecf4ffca203b18dc85311d540643c65eb27dcc0749fc49197a58ec59b7a860
+  data.tar.gz: 420b4c3b0b1cdc0482dbdbf7768c59911fc3b1f0de0f74d00b2f7dd2d6602ca96327e3db475815161ee01d67a452712968ccbdd8f831124b0865a2801a314142

data/README.md

@@ -0,0 +1,161 @@
+# Memorable
+
+A Rails logging system based on actions instead of model callbacks. Customizable ready-to-run configurations and built-in I18n support.
+
+**Note**
+It's released on [RubyGems](https://rubygems.org/gems/memorable).
+If something doesn't work, feel free to report a bug or start an issue.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'memorable'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install memorable
+
+If you prefer to use the latest code, you can build from source:
+
+```
+gem build memorable.gemspec
+gem install memorable-<VERSION>.gem
+```
+
+## Configuration
+
+### Initializer
+
+Write these lines of code to your configuration file, for example, `memorable.rb`.
+
+```ruby
+Memorable.setup do |config|
+  config.journals_model = Journal
+
+  # Specify template engine, default
+  # config.template_engine = DefaultYAMLEngine
+end
+```
+
+And put it under `config/initiailizers` directory of your Rails project.
+
+Or require this file manually by yourself.
+
+### Migration
+
+Create a migration file as following:
+
+```ruby
+class CreateJournal < ActiveRecord::Migration
+  def up
+    create_table :journals do |t|
+      t.integer :user_id
+      t.integer :resource_id
+      t.string  :resource_type
+      t.text    :meta
+
+      t.timestamps
+    end
+
+    add_index :journals, :user_id
+    add_index :journals, :resource_id
+
+    # If you are not using globalize, https://github.com/globalize/globalize,
+    # comment this line and add a field named content into your journals table.
+    # eg: t.text :content
+    Journal.create_translation_table! :content => :text
+  end
+
+  def down
+    remove_index :journals, :user_id
+    remove_index :journals, :resource_id
+
+    drop_table :journals
+
+    # If you are not using globalize, comment this line
+    Journal.drop_translation_table!
+  end
+end
+```
+
+And then execute:
+
+    $ bundle exec rake db:migrate
+
+This will give you a journals table.
+
+### Model
+
+Create a ActiveRecord Model, and you are all set.
+
+```ruby
+class Journal < ActiveRecord::Base
+  attr_accessible :resource_id, :resource_type, :user_id, :meta, :content
+
+  store :meta, accessors: [:controller, :action, :template_key ]
+
+  # If you are not using globalize, comment this line
+  translates :content, :fallbacks_for_empty_translations => true
+
+  belongs_to :user
+  belongs_to :resource, polymorphic: true, :touch => true
+end
+```
+
+## Usage
+
+Add your own templates using yaml, this gem ships with a default yml template engine.
+
+Put your templates under `app/views/memorable` directory of you project, and name them with something like `en_US.yml`
+
+Here's an example of a typical template file
+
+```
+defaults:
+  create:
+    base: "%{resource_type} created."
+  update:
+    base: "%{resource_type} updated."
+  destroy:
+    base: "%{resource_type} deleted."
+  others:
+    base: "%{action} was executed on %{resource_type}."
+contacts:
+  create:
+    base:  "Added vendor %{name} to Vendor Library."
+  update:
+    base: "Edited information for Vendor %{name}."
+    name: "Change Vendor Name form %{previous_name} to %{name}."
+  destroy:
+    base: "Deleted Vendor %{name}."
+```
+
+As you can see, controller_name and action_name are used as the first two levels of template_keys.
+
+And it support variable interpolation, default attributes, previous_changed attributes, controller_name, action_name, resource_type are included in default local variables.
+
+## Advanced Usage
+
+You can pass addition local variables used in template interpolation, or even specify which template you would like to use.
+
+You can achieve this by define a method named `"memorable_#{action_name}"` in your controller and return a hash with additional local variables and template_key you would like to use.
+
+```ruby
+class ContactsController < ApplicationController
+
+  private
+
+    def memorable_update
+      if @contact.previous_changes.key? [:name]
+        {template_key: 'name', company_email: @contact.company.email}
+      end
+    end
+end
+```

data/lib/memorable/controller.rb

@@ -15,7 +15,7 @@ module Memorable
       locals = extract_memorable_locals
 
       # write to database
-      Configuration.journals_model.create_with_options!(locals)
+      Memorable.config.journals_model.create_with_options!(locals)
 
     rescue Exception => e
       raise e if Rails.env.development? # for debug
@@ -23,8 +23,8 @@ module Memorable
     end
 
     def memorable?
-      Configuration.registered?(controller_name, action_name) &&
-        Configuration.condition_matched?(self) &&
+      Registration.registered?(controller_name, action_name) &&
+        Registration.condition_matched?(self) &&
         response.successful?
     end
 
@@ -44,16 +44,11 @@ module Memorable
         })
       end
 
-      # # Journals Model is free to override the behavior of this method
-      # if journal.respond_to? :set_attributes_for_event
-      #   journal.set_attributes_for_event(controller)
-      # end
-
       custom_method_name = "memorable_#{action_name}"
 
-      if respond_to? custom_method_name
+      if respond_to? custom_method_name, true
         custom_locals = self.send custom_method_name
-        locals.merge!(custom_locals)
+        locals.merge!(custom_locals) if custom_locals.is_a?(Hash)
       end
 
       locals
@@ -64,7 +59,7 @@ module Memorable
     end
 
     def memorable_resource_name
-      Configuration.resource_name(controller_name) || controller_name.singularize
+      Registration.resource_name(controller_name) || controller_name.singularize
     end
 
     module ClassMethods
@@ -100,7 +95,7 @@ module Memorable
       private
 
       def memorize_actions(action_names, options, condition_proc)
-        Configuration.register action_names, controller_name, options, condition_proc
+        Registration.register action_names, controller_name, options, condition_proc
       end
 
       def all_actions

data/lib/memorable/model.rb

@@ -6,9 +6,9 @@ module Memorable
     def write_content(options)
       current_locale = I18n.locale
 
-      TemplateEngine.assemble(options).each do |template|
-        I18n.locale = template[0]
-        content     = template[1]
+      Memorable.config.template_engine.assemble(options).each do |template|
+        I18n.locale  = template[0]
+        self.content = template[1]
       end
 
       I18n.locale = current_locale
@@ -26,6 +26,7 @@ module Memorable
         journal.user_id       = options.delete :user_id
         journal.resource_id   = options.delete :resource_id
         journal.resource_type = options.delete :resource_type
+        journal.meta          = options if journal.respond_to?(:meta)
 
         journal.write_content(options)
         journal

data/lib/memorable/{configuration.rb → registration.rb}

@@ -1,15 +1,9 @@
 module Memorable
-  class Configuration
+  class Registration
     @register_actions = {}
-    @journals_model = nil
 
     class << self
-      attr_reader :register_actions, :journals_model
-
-      def journals_model=(model)
-        model_klass = Object.const_get model.capitalize
-        @journals_model = model_klass
-      end
+      attr_reader :register_actions
 
       def register(action_names, controller_name, options, condition_proc)
         register_actions[controller_name] ||= {}

data/lib/memorable/template_engine.rb

@@ -1,10 +1,25 @@
 require 'singleton'
-require 'yaml'
 
 module Memorable
+
+  # This is an abstract class, do not use it directly. Inherit from this class
+  # and implement custom load!/parse/render medthods.
   class TemplateEngine
     include Singleton
 
+    # Class Methods
+    # --------------------------
+    # Override this method in subclass
+    def self.load!
+    end
+
+    def self.assemble(*args)
+      instance.assemble(*args)
+    end
+
+    # Instance Methods
+    # --------------------------
+    #
     attr_reader :load_path, :templates
 
     def initialize
@@ -12,88 +27,17 @@ module Memorable
       @templates = {}
     end
 
-    def store_templates
-      load_path.each do |filename|
-        locale = File.basename(filename, ".yml")
-        data = load_yml filename
-        templates[locale.to_sym] = data
-      end
-    end
-
-    # Loads a YAML template file. The data must have locales as
-    # toplevel keys.
-    def load_yml(filename)
-      begin
-        YAML.load_file(filename)
-      rescue TypeError, ScriptError, StandardError => e
-        raise InvalidYAMLData.new(filename, e.inspect)
-      end
-    end
-
     def assemble(options)
-      action_templates(options[:controller], options[:action], options[:template_key]).map do |locale, template|
-        content = render_template(template, options)
+      parse(options[:controller], options[:action], options[:template_key]).map do |locale, template|
+        content = render(template, options)
         [locale, content]
       end
     end
 
-    protected
-
-    def render_template(template, locals)
-      if locals
-        I18n.interpolate(template, locals)
-      else
-        template
-      end
-    end
-
-    def action_templates(controller, action, sub_key)
-      sub_key ||= 'base'
-      raw_templates = catch(:template_found) do
-        parse_entry(controller, action, sub_key)
-        parse_entry(controller, 'other', sub_key)
-        parse_entry('defaults', action, sub_key)
-        parse_entry('defaults', 'other', sub_key)
-        nil
-      end
-      raise TemplateNotFound, "Template: #{controller} #{action} #{sub_key} not found" unless raw_templates
-      raw_templates
-    end
-
-    def parse_entry(controller, action, sub_key)
-      raw_templates = templates.map do |locale, template_data|
-        template = template_data[controller][action][sub_key] rescue nil
-        template ? [locale, template] : nil
-      end.compact
-      throw :template_found, raw_templates unless raw_templates.blank?
-    end
-
-    # Class Methods
-    # ----------------------
-    #
-    def self.load!
-      pattern = self.pattern_from I18n.available_locales
-
-      add("templates/#{pattern}.yml")
-      add("app/views/memorable/#{pattern}.yml", Rails.root) if defined?(Rails)
-
-      instance.store_templates
-    end
-
-    def self.assemble(*args)
-      instance.assemble(*args)
-    end
-
-    protected
-
-    def self.add(pattern, base_dir=File.dirname(__FILE__))
-      files = Dir[File.join(base_dir, pattern)]
-      instance.load_path.concat(files)
-    end
-
-    def self.pattern_from(args)
-      array = Array(args || [])
-      array.blank? ? '*' : "{#{array.join ','}}"
+    # Override this method in subclass
+    def parse(controller, action, sub_key)
     end
   end
 end
+
+require 'memorable/template_engines/default'

data/lib/memorable/template_engines/default.rb

@@ -0,0 +1,79 @@
+require 'yaml'
+
+module Memorable
+  class DefaultYAMLEngine < TemplateEngine
+
+    # Class Methods
+    # --------------------------
+    # load yaml templates
+    def self.load!
+      pattern = self.pattern_from I18n.available_locales
+
+      add("memorable/templates/#{pattern}.yml", Memorable.config.default_templates_directory)
+      add("app/views/memorable/#{pattern}.yml", Rails.root) if defined?(Rails)
+
+      instance.store_templates
+    end
+
+    def self.add(pattern, base_dir)
+      files = Dir[File.join(base_dir, pattern)]
+      instance.load_path.concat(files)
+    end
+
+    def self.pattern_from(args)
+      array = Array(args || [])
+      array.blank? ? '*' : "{#{array.join ','}}"
+    end
+
+    # Instance Methods
+    # --------------------------
+    #
+    def store_templates
+      load_path.each do |filename|
+        locale = File.basename(filename, ".yml")
+        data = load_yml filename
+        templates[locale.to_sym] = data
+      end
+    end
+
+    def parse(controller, action, sub_key)
+      sub_key ||= 'base'
+      raw_templates = catch(:template_found) do
+        parse_entry(controller, action, sub_key)
+        parse_entry(controller, 'other', sub_key)
+        parse_entry('defaults', action, sub_key)
+        parse_entry('defaults', 'other', sub_key)
+        nil
+      end
+      raise TemplateNotFound, "Template: #{controller} #{action} #{sub_key} not found" unless raw_templates
+      raw_templates
+    end
+
+    def render(template, locals)
+      if locals
+        I18n.interpolate(template, locals)
+      else
+        template
+      end
+    end
+
+    private
+
+    # Loads a YAML template file.
+    def load_yml(filename)
+      begin
+        YAML.load_file(filename)
+      rescue TypeError, ScriptError, StandardError => e
+        raise InvalidYAMLData.new(filename, e.inspect)
+      end
+    end
+
+    def parse_entry(controller, action, sub_key)
+      raw_templates = templates.map do |locale, template_data|
+        template = template_data[controller][action][sub_key] rescue nil
+        template ? [locale, template] : nil
+      end.compact
+      throw :template_found, raw_templates unless raw_templates.blank?
+    end
+  end
+end

data/lib/memorable/version.rb

@@ -1,3 +1,3 @@
 module Memorable
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/lib/memorable.rb

@@ -2,21 +2,27 @@ require 'active_support'
 
 require 'memorable/version'
 require 'memorable/error'
-require 'memorable/configuration'
+require 'memorable/registration'
 require 'memorable/template_engine'
 require 'memorable/model'
 require 'memorable/controller'
 
 module Memorable
+  @config = ActiveSupport::OrderedOptions.new
 
   class << self
+    attr_reader :config
+
     def setup(&block)
-      Configuration.class_eval(&block) if block_given?
+      yield config if block_given?
+
+      config.journals_model.send  :include, Memorable::Model
+      ActionController::Base.send :include, Memorable::Controller
 
-      Configuration.journals_model.send :include, Memorable::Model
-      ActionController::Base.send       :include, Memorable::Controller
+      config.default_templates_directory ||= File.dirname(__FILE__)
+      config.template_engine             ||= DefaultYAMLEngine
 
-      TemplateEngine.load!
+      config.template_engine.load!
     end
   end
 end

data/memorable.gemspec

@@ -9,9 +9,9 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Cxg"]
   spec.email         = ["xg.chen87@gmail.com"]
   spec.summary       = "A Rails logging system based on actions."
-  spec.description   = %q{A Rails logging system based on actions, not model
-                          callbacks. Customizable ready-to-run configurations
-                          and built-in I18n support.}
+  spec.description   = %q{A Rails logging system based on actions, instead of
+                          model callbacks. Customizable ready-to-run
+                          configurations and built-in I18n support.}
   spec.homepage      = "https://github.com/serco-chen/memorable"
   spec.license       = "MIT"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: memorable
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Cxg
@@ -59,9 +59,9 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '10.0'
 description: |-
-  A Rails logging system based on actions, not model
-                            callbacks. Customizable ready-to-run configurations
-                            and built-in I18n support.
+  A Rails logging system based on actions, instead of
+                            model callbacks. Customizable ready-to-run
+                            configurations and built-in I18n support.
 email:
 - xg.chen87@gmail.com
 executables: []
@@ -70,12 +70,14 @@ extra_rdoc_files: []
 files:
 - Gemfile
 - LICENSE
+- README.md
 - lib/memorable.rb
-- lib/memorable/configuration.rb
 - lib/memorable/controller.rb
 - lib/memorable/error.rb
 - lib/memorable/model.rb
+- lib/memorable/registration.rb
 - lib/memorable/template_engine.rb
+- lib/memorable/template_engines/default.rb
 - lib/memorable/templates/en_US.yml
 - lib/memorable/version.rb
 - memorable.gemspec