Introduction to Mobility v1.0

This page documents changes (mostly in configuration) between the latest 0.8 release and 1.0.

TL;DR

If you just want to update to 1.0 from an earlier version, update your Mobility.configure code to look like the one in the new initializer template.

Previously, inside the Mobility.configure block, you would call various configuration methods on the config. Instead, you now call config.plugins and in a block explicitly declare each plugin you want to use, along with any default (this replaces the default_options hash).

So suppose you had a configuration like this (in 0.8.x):

Mobility.configure do |config|
  config.default_backend = :key_value
  config.accessor_method = :translates
  config.query_method = :i18n
  config.default_options[:fallbacks] = true
  config.default_options[:type] = :text
end

It's important to realize here that default_options mixes plugin defaults and backend defaults. In 1.0, these are now separated, so you must pass any options related to the backend to the backend option in your declared plugins.

Also, Mobility previously quietly enabled the cache and presence plugins even if you did not explicitly ask for them. To get the same behaviour, you will need to specify them explicitly now.

Finally, accessor_method is no longer supported (and you probably never used it, so safe to ignore).

So with that in mind, this configuration would be rewritten as follows:

Mobility.configure do |config|
  config.plugins do
    backend :key_value, type: :text    # default_options[:type] is a backend option, so it must be passed to the `backend` plugin
    active_record                      # You must now explicitly ask for ActiveRecord (or Sequel)
    query                              # i18n is the default scope
    fallbacks
    cache                              # previously implicit
    presence                           # previously implicit
  end
end

Details of what changed

Configuration

Previously, Mobility had a Mobility::Configuration class with settings such as default_backend, accessor_method and query_method. These were global settings which could be accessed from any backend or plugin.

Similarly, while plugins existed, they were mostly implicitly included (fallbacks, dirty tracking, etc) and could only be "disabled" by passing a falsey value to translates, e.g. dirty: false. While this disabled them, the plugin was still present.

With 1.0, everything is centralized around plugins, none of which are included unless you ask for them. (This means that specs can also test conditions in complete isolation.)

So while the syntax looks similar, when you now call:

Mobility.configure do |config|
  # ...

the config here is not a "Configuration" but an instance of Mobility::Translations (previously Mobility::Attributes), with some methods to declare and customize plugins. You call config.plugins to declare plugins, with optional default settings.

Here is how we would set the default backend to :key_value and enable fallbacks and dirty tracking:

Mobility.configure do |config|
  config.plugins do
    backend :key_value
    fallbacks
    dirty
  end
end

Plugins can have dependencies and those dependencies will be resolved inside the plugins block.

ORM plugin must be explicitly enabled

In the same spirit of making things more explicit, Mobility no longer inspects constants to figure out which ORM you're using; instead, you just declare the active_record or sequel plugin:

Mobility.configure do |config|
  config.plugins do
    backend :key_value
    active_record # or sequel
    # ...
  end
end