mobility 0.0.1 → 0.1.0

data/lib/mobility/active_record/model_translation.rb

@@ -0,0 +1,14 @@
+module Mobility
+  module ActiveRecord
+=begin
+
+Subclassed dynamically to generate translation class in
+{Backend::ActiveRecord::Table} backend.
+
+=end
+    class ModelTranslation < ::ActiveRecord::Base
+      self.abstract_class = true
+      validates :locale, presence: true
+    end
+  end
+end

data/lib/mobility/active_record/string_translation.rb

@@ -0,0 +1,7 @@
+module Mobility
+  module ActiveRecord
+    class StringTranslation < Translation
+      self.table_name = "mobility_string_translations"
+    end
+  end
+end

data/lib/mobility/active_record/text_translation.rb

@@ -0,0 +1,7 @@
+module Mobility
+  module ActiveRecord
+    class TextTranslation < Translation
+      self.table_name = "mobility_text_translations"
+    end
+  end
+end

data/lib/mobility/active_record/translation.rb

@@ -0,0 +1,14 @@
+module Mobility
+  module ActiveRecord
+    # @abstract Subclass and set +table_name+ to implement for a particular column type.
+    class Translation < ::ActiveRecord::Base
+      self.abstract_class = true
+
+      belongs_to :translatable, polymorphic: true
+
+      validates :key, presence: true, uniqueness: { scope: [:translatable_id, :translatable_type, :locale] }
+      validates :translatable, presence: true
+      validates :locale, presence: true
+    end
+  end
+end

data/lib/mobility/attributes.rb

@@ -0,0 +1,210 @@
+module Mobility
+=begin
+
+Defines accessor methods to include on model class. Inspired by Traco's
++Traco::Attributes+ class.
+
+Normally this class will be created through class methods defined using
+{Mobility::Translates} accessor methods, and need not be created directly.
+However, the class is central to how Mobility hooks into models to add
+accessors and other methods, and should be useful as a reference when
+understanding and designing backends.
+
+==Including Attributes in a Class
+
+Since {Attributes} is a subclass of +Module+, including an instance of it is
+like including a module. Creating an instance like this:
+
+  Attributes.new(:accessor, ["title"], backend: :my_backend, locale_accessors: [:en, :ja], cache: true, fallbacks: true)
+
+will generate an anonymous module looking something like this:
+
+  Module.new do
+    def title_backend
+      # Create a subclass of Mobility::Backend::MyBackend and include in it:
+      # - Mobility::Cache (from the cache: true option)
+      # - Mobility::Fallbacks (from the fallbacks: true option)
+      # Then instantiate the backend, memoize it, and return it.
+    end
+
+    def title(**options)
+      title_backend.read(Mobility.locale, **options).presence
+    end
+
+    def title?(**options)
+      title_backend.read(Mobility.locale, **options).present?
+    end
+
+    def title=(value)
+      title_backend.write(Mobility.locale, value.presence)
+    end
+
+    # Start Locale Accessors
+    #
+    def title_en(**options)
+      title_backend.read(:en, **options).presence
+    end
+
+    def title_en?(**options)
+      title_backend.read(:en, **options).present?
+    end
+
+    def title_en=(value)
+      title_backend.write(:en, value.presence)
+    end
+
+    def title_ja(**options)
+      title_backend.read(:ja, **options).presence
+    end
+
+    def title_ja?(**options)
+      title_backend.read(:ja, **options).present?
+    end
+
+    def title_ja=(value)
+      title_backend.write(:ja, value.presence)
+    end
+    # End Locale Accessors
+  end
+
+Including this module into a model class will then add the backend method, the
+reader, writer and presence methods, and the locale accessor so the model
+class.
+
+==Setting up the Model Class
+
+Accessor methods alone are of limited use without a hook to actually modify the
+model class. This hook is provided by the {Backend::Setup#setup_model} method,
+which is added to every backend class when it includes the {Backend} module.
+
+Assuming the backend has defined a setup block by calling +setup+, this block
+will be called when {Attributes} is {#included} in the model class, passed
+attributes and options defined when the backend was defined on the model class.
+This allows a backend to do things like (for example) define associations on a
+model class required by the backend, as happens in the {Backend::KeyValue} and
+{Backend::Table} backends.
+
+The +setup+ block is also used to extend the +i18n+ scope/dataset with
+backend-specific query method support.
+
+Since setup blocks are evaluated on the model class, it is possible that
+backends can conflict (for example, overwriting previously defined methods).
+Care should be taken to avoid defining methods on the model class, or where
+necessary, ensure that names are defined in such a way as to avoid conflicts
+with other backends.
+
+=end
+  class Attributes < Module
+    # Attributes for which accessors will be defined
+    # @return [Array<String>] Array of attributes
+    attr_reader :attributes
+
+    # Backend options
+    # @return [Hash] Backend options
+    attr_reader :options
+
+    # Backend class
+    # @return [Class] Backend class
+    attr_reader :backend_class
+
+    # Name of backend
+    # @return [Symbol,Class] Name of backend, or backend class
+    attr_reader :backend_name
+
+    # @param [Symbol] method One of: [reader, writer, accessor]
+    # @param [Array<String>] _attributes Attributes to define backend for
+    # @param [Hash] _options Backend options hash
+    # @option _options [Class] model_class Class of model
+    # @option _options [Boolean, Array<Symbol>] locale_accessors Enable locale
+    #   accessors or specify locales for which accessors should be defined on
+    #   this model backend. Will default to +true+ if +dirty+ option is +true+.
+    # @option _options [Boolean] cache (true) Enable cache for this model backend
+    # @option _options [Boolean, Hash] fallbacks Enable fallbacks or specify fallbacks for this model backend
+    # @option _options [Boolean] dirty Enable dirty tracking for this model backend
+    # @raise [ArgumentError] if method is not reader, writer or accessor
+    def initialize(method, *_attributes, **_options)
+      raise ArgumentError, "method must be one of: reader, writer, accessor" unless %i[reader writer accessor].include?(method)
+      @options = _options
+      @attributes = _attributes.map &:to_s
+      model_class = options[:model_class]
+      @backend_name = options.delete(:backend) || Mobility.config.default_backend
+      @backend_class = Class.new(get_backend_class(backend:     @backend_name,
+                                                   model_class: model_class))
+
+      options[:locale_accessors] ||= true if options[:dirty]
+
+      @backend_class.configure!(options) if @backend_class.respond_to?(:configure!)
+
+      @backend_class.include Backend::Cache unless options[:cache] == false
+      @backend_class.include Backend::Dirty.for(model_class) if options[:dirty]
+      @backend_class.include Backend::Fallbacks if options[:fallbacks]
+      @accessor_locales = options[:locale_accessors]
+      @accessor_locales = Mobility.config.default_accessor_locales if options[:locale_accessors] == true
+
+      attributes.each do |attribute|
+        define_backend(attribute)
+
+        if %i[accessor reader].include?(method)
+          define_method attribute do |**options|
+            mobility_get(attribute, options)
+          end
+
+          define_method "#{attribute}?" do |**options|
+            mobility_present?(attribute, options)
+          end
+        end
+
+        define_method "#{attribute}=" do |value|
+          mobility_set(attribute, value)
+        end if %i[accessor writer].include?(method)
+
+        define_locale_accessors(attribute, @accessor_locales) if @accessor_locales
+      end
+    end
+
+    # Add this attributes module to shared {Mobility::Wrapper} and setup model
+    # with backend setup block (see {Mobility::Backend::Setup#setup_model}).
+    # @param model_class [Class] Class of model
+    def included(model_class)
+      model_class.mobility << self
+      backend_class.setup_model(model_class, attributes, options)
+    end
+
+    # Yield each attribute to block
+    # @yield [String] Attribute
+    def each &block
+      attributes.each &block
+    end
+
+    private
+
+    def define_backend(attribute)
+      _backend_class, _options = backend_class, options
+      define_method Backend.method_name(attribute) do
+        @mobility_backends ||= {}
+        @mobility_backends[attribute] ||= _backend_class.new(self, attribute, _options)
+      end
+    end
+
+    def define_locale_accessors(attribute, locales)
+      locales.each do |locale|
+        normalized_locale = Mobility.normalize_locale(locale)
+        define_method "#{attribute}_#{normalized_locale}" do |**options|
+          mobility_get(attribute, options.merge(locale: locale))
+        end
+        define_method "#{attribute}_#{normalized_locale}?" do |**options|
+          mobility_present?(attribute, options.merge(locale: locale))
+        end
+        define_method "#{attribute}_#{normalized_locale}=" do |value, **options|
+          mobility_set(attribute, value, locale: locale)
+        end
+      end
+    end
+
+    def get_backend_class(backend: nil, model_class: nil)
+      raise Mobility::BackendRequired, "Backend option required if Mobility.config.default_backend is not set." if backend.nil?
+      klass = Module === backend ? backend : Mobility::Backend.const_get(backend.to_s.camelize.gsub(/\s+/, ''))
+      model_class.nil? ? klass : klass.for(model_class)
+    end
+  end
+end

data/lib/mobility/backend.rb

@@ -0,0 +1,152 @@
+module Mobility
+=begin
+
+Defines a minimum set of shared components included in any backend. These are:
+
+- a reader returning the +model+ on which the backend is defined ({#model})
+- a reader returning the +attribute+ for which the backend is defined
+  ({#attribute})
+- a reader returning +options+ configuring the backend ({#options})
+- a constructor setting these three elements (+model+, +attribute+, +options+),
+  and extracting fallbacks from the options hash ({#initialize})
+- a +setup+ method adding any configuration code to the model class
+  ({Setup#setup})
+
+On top of this, a backend will normally:
+
+- implement a +read+ instance method to read from the backend
+- implement a +write+ instance method to write to the backend
+- implement a +configure!+ class method to apply any normalization to the
+  options hash
+- call the +setup+ method yielding attributes and options to configure the
+  model class
+
+@example Defining a Backend
+  class MyBackend
+    include Backend
+
+    def read(locale, **options)
+      # ...
+    end
+
+    def write(locale, value, **options)
+      # ...
+    end
+
+    def self.configure!(options)
+      # ...
+    end
+
+    setup do |attributes, options|
+      # Do something with attributes and options in context of model class.
+    end
+  end
+
+@see Mobility::Attributes
+
+=end
+
+  module Backend
+    autoload :ActiveModel,  'mobility/backend/active_model'
+    autoload :ActiveRecord, 'mobility/backend/active_record'
+    autoload :Cache,        'mobility/backend/cache'
+    autoload :Column,       'mobility/backend/column'
+    autoload :Dirty,        'mobility/backend/dirty'
+    autoload :Fallbacks,    'mobility/backend/fallbacks'
+    autoload :Hstore,       'mobility/backend/hstore'
+    autoload :Jsonb,        'mobility/backend/jsonb'
+    autoload :KeyValue,     'mobility/backend/key_value'
+    autoload :Null,         'mobility/backend/null'
+    autoload :OrmDelegator, 'mobility/backend/orm_delegator'
+    autoload :Sequel,       'mobility/backend/sequel'
+    autoload :Serialized,   'mobility/backend/serialized'
+    autoload :Table,        'mobility/backend/table'
+
+    # @return [String] Backend attribute
+    attr_reader :attribute
+
+    # @return [Object] Model on which backend is defined
+    attr_reader :model
+
+    # @return [Hash] Backend options
+    attr_reader :options
+
+    # @!macro [new] backend_constructor
+    #   @param model Model on which backend is defined
+    #   @param [String] attribute Backend attribute
+    #   @option options [Hash] fallbacks Fallbacks hash
+    def initialize(model, attribute, **options)
+      @model = model
+      @attribute = attribute
+      @options = options
+      fallbacks = options[:fallbacks]
+      @fallbacks = I18n::Locale::Fallbacks.new(fallbacks) if fallbacks.is_a?(Hash)
+    end
+
+    # @!macro [new] backend_reader
+    #   @param [Symbol] locale Locale to read
+    #   @param [Hash] options
+    #   @return [Object] Value of translation
+    #
+    # @!macro [new] backend_writer
+    #   @param [Symbol] locale Locale to write
+    #   @param [Object] value Value to write
+    #   @param [Hash] options
+    #   @return [Object] Updated value
+
+    # Extend included class with +setup+ method
+    def self.included(base)
+      base.extend(Setup)
+    end
+
+    # @param [String] attribute
+    # @return [String] name of backend reader method
+    def self.method_name(attribute)
+      "#{attribute}_backend"
+    end
+
+    # Defines setup hooks for backend to customize model class.
+    module Setup
+      # Assign block to be called on model class.
+      # @yield [attributes, options]
+      # @note When called multiple times, setup blocks will be appended
+      #   so that they are run together consecutively on class.
+      def setup &block
+        if @setup_block
+          setup_block = @setup_block
+          @setup_block = lambda do |*args|
+            class_exec(*args, &setup_block)
+            class_exec(*args, &block)
+          end
+        else
+          @setup_block = block
+        end
+      end
+
+      def inherited(subclass)
+        subclass.instance_variable_set(:@setup_block, @setup_block)
+      end
+
+      # Call setup block on a class with attributes and options.
+      # @param model_class Class to be setup-ed
+      # @param [Array<String>] attributes
+      # @param [Hash] options
+      def setup_model(model_class, attributes, **options)
+        return unless setup_block = @setup_block
+        model_class.class_exec(attributes, options, &setup_block)
+      end
+
+      # {Attributes} uses this method to get a backend class specific to the
+      # model using the backend. Backend classes can override this method to
+      # return a class specific to the model class using the backend (e.g.
+      # either an ActiveRecord or Sequel backend class depending on whether the
+      # model is an ActiveRecord model or a Sequel model.)
+      # @see OrmDelegator
+      # @see Attributes
+      # @return [self] returns itself
+      def for(_)
+        self
+      end
+    end
+  end
+end

data/lib/mobility/backend/active_model.rb

@@ -0,0 +1,7 @@
+module Mobility
+  module Backend
+    module ActiveModel
+      autoload :Dirty, 'mobility/backend/active_model/dirty'
+    end
+  end
+end

data/lib/mobility/backend/active_model/dirty.rb

@@ -0,0 +1,84 @@
+module Mobility
+  module Backend
+=begin
+
+Dirty tracking for models which include the +ActiveModel::Dirty+ module.
+
+Assuming we have an attribute +title+, this module will add support for the
+following methods:
+- +title_changed?+
+- +title_change+
+- +title_was+
+- +title_will_change!+
+- +title_previously_changed?+
+- +title_previous_change+
+- +restore_title!+
+
+In addition, the private method +restore_attribute!+ will also restore the
+value of the translated attribute if passed to it.
+
+@see http://api.rubyonrails.org/classes/ActiveModel/Dirty.html Rails documentation for Active Model Dirty module
+
+=end
+    module ActiveModel::Dirty
+      # @!group Backend Accessors
+      # @!macro backend_writer
+      def write(locale, value, **options)
+        locale_accessor = "#{attribute}_#{locale}"
+        if model.changed_attributes.has_key?(locale_accessor) && model.changed_attributes[locale_accessor] == value
+          model.attributes_changed_by_setter.except!(locale_accessor)
+        else
+          model.send(:attribute_will_change!, "#{attribute}_#{locale}")
+        end
+        super
+      end
+      # @!endgroup
+
+      # @param [Class] backend_class Class of backend
+      def self.included(backend_class)
+        backend_class.extend(ClassMethods)
+      end
+
+      # Adds hook after {Backend::Setup#setup_model} to add dirty-tracking
+      # methods for translated attributes onto model class.
+      module ClassMethods
+        # (see Mobility::Backend::Setup#setup_model)
+        def setup_model(model_class, attributes, **options)
+          super
+          model_class.class_eval do
+            %w[changed? change was will_change! previously_changed? previous_change].each do |suffix|
+              attributes.each do |attribute|
+                class_eval <<-EOM, __FILE__, __LINE__ + 1
+                  def #{attribute}_#{suffix}
+                    attribute_#{suffix}("#{attribute}_#\{Mobility.locale\}")
+                  end
+                EOM
+              end
+            end
+          end
+
+          restore_methods = Module.new do
+            attributes.each do |attribute|
+              locale_accessor = "#{attribute}_#{Mobility.locale}"
+              define_method "restore_#{attribute}!" do
+                if attribute_changed?(locale_accessor)
+                  __send__("#{attribute}=", changed_attributes[locale_accessor])
+                end
+              end
+            end
+
+            define_method :restore_attribute! do |attr|
+              if attributes.include?(attr.to_s)
+                send("restore_#{attr}!")
+              else
+                super(attr)
+              end
+            end
+            private :restore_attribute!
+          end
+          model_class.include restore_methods
+        end
+      end
+    end
+  end
+end