Module: Mobility

Defined in:
lib/mobility.rb,
lib/mobility/arel.rb,
lib/mobility/util.rb,
lib/mobility/loaded.rb,
lib/mobility/sequel.rb,
lib/mobility/backend.rb,
lib/mobility/plugins.rb,
lib/mobility/version.rb,
lib/mobility/backends.rb,
lib/mobility/fallbacks.rb,
lib/mobility/arel/nodes.rb,
lib/mobility/attributes.rb,
lib/mobility/sequel/sql.rb,
lib/mobility/translates.rb,
lib/mobility/active_model.rb,
lib/mobility/arel/visitor.rb,
lib/mobility/active_record.rb,
lib/mobility/backends/json.rb,
lib/mobility/backends/null.rb,
lib/mobility/configuration.rb,
lib/mobility/plugins/cache.rb,
lib/mobility/plugins/dirty.rb,
lib/mobility/plugins/query.rb,
lib/mobility/backends/jsonb.rb,
lib/mobility/backends/table.rb,
lib/mobility/plugins/sequel.rb,
lib/mobility/backends/column.rb,
lib/mobility/backends/hstore.rb,
lib/mobility/backends/sequel.rb,
lib/mobility/plugins/default.rb,
lib/mobility/backend_resetter.rb,
lib/mobility/plugins/presence.rb,
lib/mobility/arel/nodes/pg_ops.rb,
lib/mobility/plugins/fallbacks.rb,
lib/mobility/backends/container.rb,
lib/mobility/backends/key_value.rb,
lib/mobility/sequel/translation.rb,
lib/mobility/backends/serialized.rb,
lib/mobility/backends/hash_valued.rb,
lib/mobility/backends/sequel/json.rb,
lib/mobility/plugins/active_model.rb,
lib/mobility/plugins/sequel/dirty.rb,
lib/mobility/plugins/sequel/query.rb,
lib/mobility/backend/orm_delegator.rb,
lib/mobility/backends/sequel/jsonb.rb,
lib/mobility/backends/sequel/table.rb,
lib/mobility/plugins/active_record.rb,
lib/mobility/sequel/column_changes.rb,
lib/mobility/backends/active_record.rb,
lib/mobility/backends/sequel/column.rb,
lib/mobility/backends/sequel/hstore.rb,
lib/mobility/backends/sequel/pg_hash.rb,
lib/mobility/sequel/backend_resetter.rb,
lib/mobility/sequel/hash_initializer.rb,
lib/mobility/sequel/text_translation.rb,
lib/mobility/plugins/locale_accessors.rb,
lib/mobility/sequel/model_translation.rb,
lib/mobility/active_record/translation.rb,
lib/mobility/backends/sequel/container.rb,
lib/mobility/backends/sequel/key_value.rb,
lib/mobility/plugins/attribute_methods.rb,
lib/mobility/sequel/string_translation.rb,
lib/mobility/backends/sequel/serialized.rb,
lib/mobility/plugins/active_model/dirty.rb,
lib/mobility/backends/active_record/json.rb,
lib/mobility/plugins/active_record/dirty.rb,
lib/mobility/plugins/active_record/query.rb,
lib/mobility/backends/active_record/jsonb.rb,
lib/mobility/backends/active_record/table.rb,
lib/mobility/active_model/backend_resetter.rb,
lib/mobility/backends/active_record/column.rb,
lib/mobility/backends/active_record/hstore.rb,
lib/mobility/plugins/fallthrough_accessors.rb,
lib/mobility/active_record/backend_resetter.rb,
lib/mobility/active_record/text_translation.rb,
lib/mobility/backends/active_record/pg_hash.rb,
lib/mobility/active_record/model_translation.rb,
lib/mobility/active_record/string_translation.rb,
lib/mobility/backends/active_record/container.rb,
lib/mobility/backends/active_record/key_value.rb,
lib/mobility/plugins/cache/translation_cacher.rb,
lib/mobility/backends/active_record/serialized.rb,
lib/mobility/active_record/uniqueness_validator.rb,
lib/rails/generators/mobility/install_generator.rb,
lib/mobility/plugins/active_record/attribute_methods.rb,
lib/rails/generators/mobility/translations_generator.rb,
lib/rails/generators/mobility/backend_generators/base.rb,
lib/rails/generators/mobility/backend_generators/table_backend.rb,
lib/rails/generators/mobility/backend_generators/column_backend.rb,
lib/rails/generators/mobility/active_record_migration_compatibility.rb

Overview

Mobility is a gem for storing and retrieving localized data through attributes on a class. The Mobility module includes all necessary methods and modules to support defining backend accessors on a class.

To enable Mobility on a class, simply include or extend the Mobility module, and define any attribute accessors using Translates#mobility_accessor (aliased to the value of Mobility.accessor_method, which defaults to translates).

class MyClass
  extend Mobility
  translates :title, backend: :key_value
end

When defining this module, Mobility attempts to require various gems (for example, active_record and sequel) to evaluate which are loaded. Loaded gems are tracked with dynamic subclasses of the Loaded module and referenced in backends to define gem-dependent behavior.

Defined Under Namespace

Modules: ActiveModel, ActiveRecord, ActiveRecordMigrationCompatibility, Arel, Backend, BackendGenerators, Backends, ClassMethods, InstanceMethods, Loaded, Plugins, Sequel, Translates, Util Classes: Attributes, BackendRequired, BackendResetter, Configuration, Fallbacks, InstallGenerator, InvalidLocale, NotImplementedError, TranslationsGenerator, VersionNotSupportedError

Constant Summary collapse

VERSION =
"0.8.9"

Locale Accessors collapse

Configuration Methods collapse

Class Method Summary collapse

Class Method Details

.accessor_methodSymbol

Alias for mobility_accessor (defaults to translates) (see Mobility::Configuration#query_method)


# File 'lib/mobility.rb', line 153


.available_localesArray<Symbol>

Note:

The special case for Rails is necessary due to the fact that Rails may load the model before setting I18n.available_locales. If we simply default to I18n.available_locales, we may define many more methods (in LocaleAccessors) than is really necessary.

Returns available locales. Defaults to I18n.available_locales, but will use Rails.application.config.i18n.available_locales if Rails is loaded and config is non-nil.


252
253
254
255
256
257
258
# File 'lib/mobility.rb', line 252

def available_locales
  if Loaded::Rails && Rails.application
    Rails.application.config.i18n.available_locales || I18n.available_locales
  else
    I18n.available_locales
  end
end

.configMobility::Configuration


149
150
151
# File 'lib/mobility.rb', line 149

def config
  @configuration ||= Configuration.new
end

.configure {|Mobility::Configuration| ... } ⇒ Object

Configure Mobility

Yields:


191
192
193
# File 'lib/mobility.rb', line 191

def configure
  yield config
end

.default_accessor_localesHash

Default set of options. These will be merged with any backend options when defining translated attributes (with translates). Default options may not include the keys 'backend' or 'model_class'. (see Mobility::Configuration#plugins) (see Mobility::Configuration#default_accessor_locales)


173
174
175
176
177
# File 'lib/mobility.rb', line 173

%w[accessor_method query_method default_backend default_options plugins default_accessor_locales].each do |method_name|
  define_method method_name do
    config.public_send(method_name)
  end
end

.default_backendSymbol, Class

Default backend to use (can be symbol or actual backend class)


# File 'lib/mobility.rb', line 162


.default_fallbacks(*args) ⇒ Object

TODO: Remove in v1.0


180
181
182
# File 'lib/mobility.rb', line 180

def default_fallbacks(*args)
  config.public_send(:default_fallbacks, *args)
end

.default_optionsHash

Default set of options. These will be merged with any backend options when defining translated attributes (with translates). Default options may not include the keys 'backend' or 'model_class'. (see Mobility::Configuration#plugins) (see Mobility::Configuration#default_accessor_locales)


173
174
175
176
177
# File 'lib/mobility.rb', line 173

%w[accessor_method query_method default_backend default_options plugins default_accessor_locales].each do |method_name|
  define_method method_name do
    config.public_send(method_name)
  end
end

.enforce_available_locales!(locale) ⇒ Object

Raises InvalidLocale exception if the locale passed in is present but not available.

Raises:


230
231
232
233
234
235
236
237
238
239
240
241
242
# File 'lib/mobility.rb', line 230

def enforce_available_locales!(locale)
  # TODO: Remove conditional in v1.0
  if I18n.enforce_available_locales
    raise Mobility::InvalidLocale.new(locale) unless (I18n.locale_available?(locale) || locale.nil?)
  else
    warn "WARNING: You called Mobility.enforce_available_locales! in a situation where\nI18n.enforce_available_locales is false. In the past, Mobility would do nothing\nin this case, but as of the next major release Mobility will ignore the I18n\nsetting and enforce available locales whenever this method is called.\n"
  end
end

.extended(model_class) ⇒ Object


85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
# File 'lib/mobility.rb', line 85

def extended(model_class)
  return if model_class.respond_to? :mobility_accessor

  model_class.extend Translates
  model_class.extend ClassMethods
  #TODO: Remove in v1.0
  model_class.include InstanceMethods

  if translates = Mobility.config.accessor_method
    model_class.singleton_class.send(:alias_method, translates, :mobility_accessor)
  end

  if Loaded::ActiveRecord && model_class < ::ActiveRecord::Base
    model_class.include(ActiveRecord)
  end

  if Loaded::Sequel && model_class < ::Sequel::Model
    model_class.include(Sequel)
  end
end

.included(model_class) ⇒ Object

Extends model with this class so that include Mobility is equivalent to extend Mobility (but extend is preferred).


109
110
111
# File 'lib/mobility.rb', line 109

def included(model_class)
  model_class.extend self
end

.localeSymbol


115
116
117
# File 'lib/mobility.rb', line 115

def locale
  read_locale || I18n.locale
end

.locale=(locale) ⇒ Symbol

Sets Mobility locale

Raises:

  • (InvalidLocale)

    if locale is nil or not in Mobility.available_locales (if I18n.enforce_available_locales is true)


124
125
126
# File 'lib/mobility.rb', line 124

def locale=(locale)
  set_locale(locale)
end

.new_fallbacks(*args) ⇒ Object

TODO: Make private in v1.0


# File 'lib/mobility.rb', line 159


.normalize_locale(locale = Mobility.locale) ⇒ String Also known as: normalized_locale

Return normalized locale

Examples:

Mobility.normalize_locale(:ja)
#=> "ja"
Mobility.normalize_locale("pt-BR")
#=> "pt_br"

204
205
206
# File 'lib/mobility.rb', line 204

def normalize_locale(locale = Mobility.locale)
  "#{locale.to_s.downcase.tr("-", "_")}"
end

.normalize_locale_accessor(attribute, locale = Mobility.locale) ⇒ String

Return normalized locale accessor name

Examples:

Mobility.normalize_locale_accessor(:foo, :ja)
#=> "foo_ja"
Mobility.normalize_locale_accessor(:bar, "pt-BR")
#=> "bar_pt_br"

Raises:

  • (ArgumentError)

    if generated accessor has an invalid format


219
220
221
222
223
224
225
# File 'lib/mobility.rb', line 219

def normalize_locale_accessor(attribute, locale = Mobility.locale)
  "#{attribute}_#{normalize_locale(locale)}".tap do |accessor|
    unless CALL_COMPILABLE_REGEXP.match(accessor)
      raise ArgumentError, "#{accessor.inspect} is not a valid accessor"
    end
  end
end

.pluginsHash

Default set of options. These will be merged with any backend options when defining translated attributes (with translates). Default options may not include the keys 'backend' or 'model_class'. (see Mobility::Configuration#plugins) (see Mobility::Configuration#default_accessor_locales)


173
174
175
176
177
# File 'lib/mobility.rb', line 173

%w[accessor_method query_method default_backend default_options plugins default_accessor_locales].each do |method_name|
  define_method method_name do
    config.public_send(method_name)
  end
end

.query_methodSymbol

Alias for mobility_accessor (defaults to translates) (see Mobility::Configuration#query_method)


# File 'lib/mobility.rb', line 153


.storageRequestStore


143
144
145
# File 'lib/mobility.rb', line 143

def storage
  RequestStore.store
end

.with_locale(locale) {|Symbol| ... } ⇒ Object

Sets Mobility locale around block

Yields:

  • (Symbol)

    Locale


131
132
133
134
135
136
137
138
139
# File 'lib/mobility.rb', line 131

def with_locale(locale)
  previous_locale = read_locale
  begin
    set_locale(locale)
    yield(locale)
  ensure
    set_locale(previous_locale)
  end
end