mobility 0.1.10 → 0.1.11

data/lib/generators/rails/mobility/backend_generators/base.rb

@@ -0,0 +1,69 @@
+# frozen-string-literal: true
+require "rails/generators/active_record/migration/migration_generator"
+
+module Mobility
+  module BackendGenerators
+    class Base < ::Rails::Generators::NamedBase
+      argument :attributes, type: :array, default: []
+      include ::ActiveRecord::Generators::Migration
+
+      def create_migration_file
+        if self.class.migration_exists?(migration_dir, migration_file)
+          ::Kernel.warn "Migration already exists: #{migration_file}"
+        else
+          migration_template "#{template}.rb", "db/migrate/#{migration_file}.rb"
+        end
+      end
+
+      def self.next_migration_number(dirname)
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def backend
+        self.class.name.split('::').last.gsub(/Backend$/,'').underscore
+      end
+
+      protected
+
+      def attributes_with_index
+        attributes.select { |a| !a.reference? && a.has_index? }
+      end
+
+      private
+
+      def check_data_source!
+        unless data_source_exists?
+          raise NoTableDefined, "The table #{table_name} does not exist. Create it first before generating translated columns."
+        end
+      end
+
+      def data_source_exists?
+        connection.data_source_exists?(table_name)
+      end
+
+      delegate :connection, to: ::ActiveRecord::Base
+
+      def truncate_index_name(index_name)
+        if index_name.size < connection.index_name_length
+          index_name
+        else
+          "index_#{Digest::SHA1.hexdigest(index_name)}"[0, connection.index_name_length].freeze
+        end
+      end
+
+      def template
+        "#{backend}_translations".freeze
+      end
+
+      def migration_dir
+        File.expand_path("db/migrate".freeze)
+      end
+
+      def migration_file
+        "create_#{file_name}_#{attributes.map(&:name).join('_and_')}_translations_for_mobility_#{backend}_backend".freeze
+      end
+    end
+
+    class NoTableDefined < StandardError; end
+  end
+end

data/lib/generators/rails/mobility/backend_generators/column_backend.rb

@@ -0,0 +1,15 @@
+# frozen-string-literal: true
+require "rails/generators"
+
+module Mobility
+  module BackendGenerators
+    class ColumnBackend < Mobility::BackendGenerators::Base
+      source_root File.expand_path("../../templates", __FILE__)
+
+      def initialize(*args)
+        super
+        check_data_source!
+      end
+    end
+  end
+end

data/lib/generators/rails/mobility/backend_generators/table_backend.rb

@@ -0,0 +1,42 @@
+# frozen-string-literal: true
+require "rails/generators"
+
+module Mobility
+  module BackendGenerators
+    class TableBackend < Mobility::BackendGenerators::Base
+      source_root File.expand_path("../../templates", __FILE__)
+
+      def create_migration_file
+        if data_source_exists? && !self.class.migration_exists?(migration_dir, migration_file)
+          migration_template "#{backend}_migration.rb", "db/migrate/#{migration_file}.rb"
+        else
+          super
+        end
+      end
+
+      private
+
+      alias_method :model_table_name, :table_name
+      def table_name
+        model_table_name = super
+        "#{model_table_name.singularize}_translations"
+      end
+
+      def foreign_key
+        "#{model_table_name.singularize}_id"
+      end
+
+      def translation_index_name
+        truncate_index_name("index_#{table_name}_on_#{foreign_key}")
+      end
+
+      def translation_locale_index_name
+        truncate_index_name("index_#{table_name}_on_locale")
+      end
+
+      def translation_unique_index_name
+        truncate_index_name("index_#{table_name}_on_#{foreign_key}_and_locale")
+      end
+    end
+  end
+end

data/lib/generators/rails/mobility/generators.rb

@@ -0,0 +1,5 @@
+require "rails/generators"
+
+require_relative "./install_generator"
+require_relative "./translations_generator"
+require_relative "./backend_generators/base"

data/lib/generators/rails/mobility/templates/column_translations.rb

@@ -0,0 +1,17 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+<% attributes.each do |attribute| -%>
+<% I18n.available_locales.each do |locale| -%>
+<% column_name = Mobility.normalize_locale_accessor(attribute.name, locale) -%>
+<% if connection.column_exists?(table_name, column_name) -%>
+<% warn "#{column_name} already exists, skipping." %>
+<% else -%>
+    add_column :<%= table_name %>, :<%= column_name %>, :<%= attribute.type %><%= attribute.inject_options %>
+    <%- if attribute.has_index? -%>
+    add_index  :<%= table_name %>, :<%= column_name %><%= attribute.inject_index_options %>
+    <%- end -%>
+<% end -%>
+<% end -%>
+<% end -%>
+  end
+end

data/lib/generators/rails/mobility/templates/table_migration.rb

@@ -0,0 +1,17 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+<% attributes.each do |attribute| -%>
+  <%- if attribute.reference? -%>
+    add_reference :<%= table_name %>, :<%= attribute.name %><%= attribute.inject_options %>
+  <%- elsif attribute.token? -%>
+    add_column :<%= table_name %>, :<%= attribute.name %>, :string<%= attribute.inject_options %>
+    add_index :<%= table_name %>, :<%= attribute.index_name %><%= attribute.inject_index_options %>, unique: true
+  <%- else -%>
+    add_column :<%= table_name %>, :<%= attribute.name %>, :<%= attribute.type %><%= attribute.inject_options %>
+    <%- if attribute.has_index? -%>
+    add_index :<%= table_name %>, :<%= attribute.index_name %><%= attribute.inject_index_options %>
+    <%- end -%>
+  <%- end -%>
+<% end -%>
+  end
+end

data/lib/generators/rails/mobility/templates/table_translations.rb

@@ -0,0 +1,28 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :<%= table_name %><%= primary_key_type %> do |t|
+
+      # Translated attribute(s)
+<% attributes.each do |attribute| -%>
+<% if attribute.token? -%>
+      t.string :<%= attribute.name %><%= attribute.inject_options %>
+<% else -%>
+      t.<%= attribute.type %> :<%= attribute.name %><%= attribute.inject_options %>
+<% end -%>
+<% end -%>
+
+      t.string  :locale, null: false
+      t.integer :<%= foreign_key %>, null: false
+
+      t.timestamps null: false
+    end
+
+    add_index :<%= table_name %>, :<%= foreign_key %>, name: :<%= translation_index_name %>
+    add_index :<%= table_name %>, :locale, name: :<%= translation_locale_index_name %>
+    add_index :<%= table_name %>, [:<%= foreign_key %>, :locale], name: :<%= translation_unique_index_name %>, unique: true
+
+<%- attributes_with_index.each do |attribute| -%>
+    add_index :<%= table_name %>, :<%= attribute.index_name %><%= attribute.inject_index_options %>
+<%- end -%>
+  end
+end

data/lib/generators/rails/mobility/translations_generator.rb

@@ -0,0 +1,75 @@
+# frozen-string-literal: true
+
+module Mobility
+=begin
+
+Generator to create translation tables or add translation columns to a model
+table, for either Table or Column backends.
+
+==Usage
+
+To add translations for a string attribute +title+ to a model +Post+, call the
+generator with:
+
+  rails generate mobility:translations post title:string
+
+Here, the backend is implicit in the value of +Mobility.default_backend+, but
+it can be explicitly set using the +backend+ option:
+
+  rails generate mobility:translations post title:string --backend=table
+
+For the +table+ backend, the generator will either create a translation table
+(in this case, +post_translations+) or add columns to the table if it already
+exists.
+
+For the +column+ backend, the generator will add columns for all locales in
++I18n.available_locales+. If some columns already exist, they will simply be
+skipped.
+
+Other backends are not supported, for obvious reasons:
+* the +key_value+ backend does not need any model-specific migrations, simply
+  run the install generator.
+* +jsonb+, +hstore+ and +serialized+ backends simply require a single column on
+  a model table, which can be added with the normal Rails migration generator.
+
+=end
+  class TranslationsGenerator < ::Rails::Generators::NamedBase
+    SUPPORTED_BACKENDS = %w[column table]
+    BACKEND_OPTIONS = { type: :string, desc: "Backend to use for translations (defaults to Mobility.default_backend)".freeze }
+    argument :attributes, type: :array, default: [], banner: "field[:type][:index] field[:type][:index]"
+
+    class_option(:backend, BACKEND_OPTIONS)
+    invoke_from_option :backend
+
+    def self.class_options(options = nil)
+      super
+      @class_options[:backend] = Thor::Option.new(:backend, BACKEND_OPTIONS.merge(default: Mobility.default_backend.to_s.freeze))
+      @class_options
+    end
+
+    def self.prepare_for_invocation(name, value)
+      if name == :backend
+        if SUPPORTED_BACKENDS.include?(value)
+          require_relative "./backend_generators/#{value}_backend".freeze
+          Mobility::BackendGenerators.const_get("#{value}_backend".camelcase.freeze)
+        elsif Mobility::Backend.const_get(value.to_s.camelize.gsub(/\s+/, ''.freeze))
+          raise Thor::Error, "The #{value} backend does not have a translations generator."
+        else
+          raise Thor::Error, "#{value} is not a Mobility backend."
+        end
+      else
+        super
+      end
+    end
+
+    protected
+
+    def say_status(status, message, *args)
+      if status == :invoke && SUPPORTED_BACKENDS.include?(message)
+        super(status, "#{message}_backend".freeze, *args)
+      else
+        super
+      end
+    end
+  end
+end

data/lib/mobility.rb

@@ -208,6 +208,15 @@ module Mobility
       "#{attribute}_#{normalize_locale(locale)}".freeze
     end
 
+    # Raises InvalidLocale exception if the locale passed in is present but not available.
+    # @param [String,Symbol] locale
+    # @raise [InvalidLocale] if locale is present but not available
+    def enforce_available_locales!(locale)
+      if I18n.enforce_available_locales
+        raise Mobility::InvalidLocale.new(locale) unless (I18n.locale_available?(locale) || locale.nil?)
+      end
+    end
+
     protected
 
     def read_locale
@@ -216,9 +225,7 @@ module Mobility
 
     def set_locale(locale)
       locale = locale.to_sym if locale
-      if I18n.enforce_available_locales
-        raise Mobility::InvalidLocale.new(locale) unless (I18n.available_locales.include?(locale) || locale.nil?)
-      end
+      enforce_available_locales!(locale)
       storage[:mobility_locale] = locale
     end
   end

data/lib/mobility/attributes.rb

@@ -137,6 +137,7 @@ with other backends.
       if (options[:dirty] && options[:fallthrough_accessors] != false)
         options[:fallthrough_accessors] = true
       end
+      include FallthroughAccessors.new(attributes) if options[:fallthrough_accessors]
 
       @backend_class.configure!(options) if @backend_class.respond_to?(:configure!)
 
@@ -158,8 +159,8 @@ with other backends.
           end
         end
 
-        define_method "#{attribute}=" do |value|
-          mobility_set(attribute, value)
+        define_method "#{attribute}=" do |value, **options|
+          mobility_set(attribute, value, **options)
         end if %i[accessor writer].include?(method)
 
         define_locale_accessors(attribute, @accessor_locales) if @accessor_locales
@@ -187,7 +188,6 @@ with other backends.
       backend_class.include(Backend::Cache)                            unless options[:cache] == false
       backend_class.include(Backend::Dirty.for(options[:model_class])) if options[:dirty]
       backend_class.include(Backend::Fallbacks)                        unless options[:fallbacks] == false
-      backend_class.include(FallthroughAccessors.new(attributes))      if options[:fallthrough_accessors]
     end
 
     def define_backend(attribute)
@@ -215,7 +215,7 @@ with other backends.
 
     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+/, ''))
+      klass = Module === backend ? backend : Mobility::Backend.const_get(backend.to_s.camelize.gsub(/\s+/, ''.freeze).freeze)
       model_class.nil? ? klass : klass.for(model_class)
     end
   end

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

@@ -78,8 +78,6 @@ value of the translated attribute if passed to it.
             private :restore_attribute!
           end
           model_class.include restore_methods
-
-          model_class.include(FallthroughAccessors.new(*attributes))
         end
       end
     end

data/lib/mobility/backend/active_record/column.rb

@@ -4,6 +4,15 @@ module Mobility
 
 Implements the {Mobility::Backend::Column} backend for ActiveRecord models.
 
+You can use the +mobility:translations+ generator to create a migration adding
+translatable columns to the model table with:
+
+  rails generate mobility:translations post title:string
+
+The generated migration will add columns +title_<locale>+ for every locale in
++I18n.available_locales+. (The generator can be run again to add new attributes
+or locales.)
+
 @note This backend disables the +locale_accessors+ option, which would
   otherwise interfere with column methods.
 
@@ -27,11 +36,15 @@ Implements the {Mobility::Backend::Column} backend for ActiveRecord models.
 
       # @!group Backend Accessors
       # @!macro backend_reader
-      # @!method read(locale, **options)
+      def read(locale, **_)
+        model.read_attribute(column(locale))
+      end
 
       # @!group Backend Accessors
       # @!macro backend_writer
-      # @!method write(locale, value, **options)
+      def write(locale, value, **_)
+        model.write_attribute(column(locale), value)
+      end
 
       # @!group Backend Configuration
       def self.configure!(options)

data/lib/mobility/backend/active_record/table.rb

@@ -6,6 +6,15 @@ module Mobility
 
 Implements the {Mobility::Backend::Table} backend for ActiveRecord models.
 
+To generate a translation table for a model +Post+, you can use the included
++mobility:translations+ generator:
+
+  rails generate mobility:translations post title:string content:text
+
+This will create a migration which can be run to create the translation table.
+If the translation table already exists, it will create a migration adding
+columns to that table.
+
 @example Model with table backend
   class Post < ActiveRecord::Base
     translates :title, backend: :table, association_name: :translations

data/lib/mobility/backend/column.rb

@@ -2,10 +2,18 @@ module Mobility
   module Backend
 =begin
 
-Stores translated attribute as a column on the model table.
+Stores translated attribute as a column on the model table. To use this
+backend, ensure that the model table has columns named +<attribute>_<locale>+
+for every locale in +I18n.available_locales+.
 
-To use this backend, ensure that the model table has columns named
-+<attribute>_<locale>+ for every locale in +I18n.available_locales+.
+If you are using Rails, you can use the +mobility:translations+ generator to
+create a migration adding these columns to the model table with:
+
+  rails generate mobility:translations post title:string
+
+The generated migration will add columns +title_<locale>+ for every locale in
++I18n.available_locales+. (The generator can be run again to add new attributes
+or locales.)
 
 ==Backend Options
 
@@ -19,19 +27,6 @@ be ignored if set, since it would cause a conflict with column accessors.
     module Column
       include OrmDelegator
 
-      # @!group Backend Accessors
-      #
-      # @!macro backend_reader
-      def read(locale, **_)
-        model.send(column(locale))
-      end
-
-      # @!macro backend_writer
-      def write(locale, value, **_)
-        model.send("#{column(locale)}=", value)
-      end
-      # @!endgroup
-
       # Returns name of column where translated attribute is stored
       # @param [Symbol] locale
       # @return [String]