Skip to content

Commit

Permalink
Use explicit default for configuration
Browse files Browse the repository at this point in the history
  • Loading branch information
shioyama committed Nov 30, 2024
1 parent 6398256 commit 49ec9b0
Show file tree
Hide file tree
Showing 3 changed files with 135 additions and 176 deletions.
75 changes: 19 additions & 56 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,19 +80,11 @@ The generator will create an initializer file `config/initializers/mobility.rb`
which looks something like this:

```ruby
Mobility.configure do

# PLUGINS
plugins do
backend :key_value

active_record

reader
writer

# ...
end
Mobility.configure do |config|
config.plugin(:backend, :key_value)
config.plugin(:active_record)
config.plugin(:reader)
config.plugin(:writer)
end
```

Expand All @@ -101,12 +93,8 @@ with an optional default. To use a different default backend, you can
change the default passed to the `backend` plugin, like this:

```diff
Mobility.configure do

# PLUGINS
plugins do
- backend :key_value
+ backend :table
- config.plugin(:backend, :key_value)
+ config.plugin(:backend, :table)
```

See other possible backends in the [backends section](#backends).
Expand All @@ -115,14 +103,8 @@ You can also set defaults for backend-specific options. Below, we set the
default `type` option for the KeyValue backend to `:string`.

```diff
Mobility.configure do

# PLUGINS
plugins do
- backend :key_value
+ backend :key_value, type: :string
end
end
- config.plugin(:backend, :key_value)
+ config.plugin(:backend, :key_value, type: :string)
```

We will assume the configuration above in the examples that follow.
Expand All @@ -137,11 +119,8 @@ Requirements:
When configuring Mobility, ensure that you include the `sequel` plugin:

```diff
plugins do
backend :key_value

- active_record
+ sequel
- config.plugin(:active_record)
+ config.plugin(:sequel)
```

You can extend `Mobility` just like in ActiveRecord, or you can use the
Expand Down Expand Up @@ -284,9 +263,7 @@ accessors" in Mobility, and can be enabled by including the `locale_accessors`
plugin, with a default set of accessors:

```diff
plugins do
# ...
+ locale_accessors [:en, :ja]
+ config.plugin(:locale_accessors, [:en, :ja])
```

You can also override this default from `translates` in any model:
Expand Down Expand Up @@ -332,9 +309,7 @@ defined for a given locale.)
Ensure the plugin is enabled:

```diff
plugins do
# ...
+ fallthrough_accessors
+ config.plugin(:fallthrough_accessors)
```

... then we can access any locale we want, without specifying them upfront:
Expand Down Expand Up @@ -457,10 +432,8 @@ Mobility offers basic support for translation fallbacks. First, enable the
`fallbacks` plugin:

```diff
plugins do
# ...
+ fallbacks
+ locale_accessors
+ config.plugin(:fallbacks)
+ config.plugin(:locale_accessors)
```

Fallbacks will require `fallthrough_accessors` to handle methods like
Expand Down Expand Up @@ -564,9 +537,7 @@ fallbacks](https://github.com/svenfuchs/i18n/wiki/Fallbacks).
Another option is to assign a default value, using the `default` plugin:

```diff
plugins do
# ...
+ default 'foo'
+ config.plugin(:default, 'foo')
```

Here we've set a "default default" of `'foo'`, which will be returned if a fetch would
Expand Down Expand Up @@ -617,10 +588,7 @@ have enabled an ORM plugin (either `active_record` or `sequel`), since the
dirty plugin will depend on one of these being enabled.

```diff
plugins do
# ...
active_record
+ dirty
+ config.plugin(:dirty)
```

(Once enabled globally, the dirty plugin can be selectively disabled on classes
Expand Down Expand Up @@ -707,9 +675,7 @@ can be quickly retrieved again. The cache plugin is included in the default
configuration created by the install generator:

```diff
plugins do
# ...
+ cache
+ config.plugin(:cache)
```

It can be disabled selectively per model by passing `cache: false` when
Expand Down Expand Up @@ -737,10 +703,7 @@ this feature, include the `query` plugin, and ensure you also have an ORM
plugin enabled (`active_record` or `sequel`):

```diff
plugins do
# ...
active_record
+ query
+ config.plugin(:query)
```

Querying defines a scope or dataset class method, whose default name is `i18n`.
Expand Down
229 changes: 113 additions & 116 deletions lib/rails/generators/mobility/templates/initializer.rb
Original file line number Diff line number Diff line change
@@ -1,129 +1,126 @@
Mobility.configure do
# PLUGINS
plugins do
# Backend
#
# Sets the default backend to use in models. This can be overridden in models
# by passing +backend: ...+ to +translates+.
#
# To default to a different backend globally, replace +:key_value+ by another
# backend name.
#
backend :key_value
Mobility.configure do |config|
# Backend
#
# Sets the default backend to use in models. This can be overridden in models
# by passing +backend: ...+ to +translates+.
#
# To default to a different backend globally, replace +:key_value+ by another
# backend name.
#
config.plugin(:backend, :key_value)

# ActiveRecord
#
# Defines ActiveRecord as ORM, and enables ActiveRecord-specific plugins.
active_record
# ActiveRecord
#
# Defines ActiveRecord as ORM, and enables ActiveRecord-specific plugins.
config.plugin(:active_record)

# Accessors
#
# Define reader and writer methods for translated attributes. Remove either
# to disable globally, or pass +reader: false+ or +writer: false+ to
# +translates+ in any translated model.
#
reader
writer
# Accessors
#
# Define reader and writer methods for translated attributes. Remove either
# to disable globally, or pass +reader: false+ or +writer: false+ to
# +translates+ in any translated model.
#
config.plugin(:reader)
config.plugin(:writer)

# Backend Reader
#
# Defines reader to access the backend for any attribute, of the form
# +<attribute>_backend+.
#
backend_reader
#
# Or pass an interpolation string to define a different pattern:
# backend_reader "%s_translations"
# Backend Reader
#
# Defines reader to access the backend for any attribute, of the form
# +<attribute>_backend+.
#
config.plugin(:backend_reader)
#
# Or pass an interpolation string to define a different pattern:
# backend_reader "%s_translations"

# Query
#
# Defines a scope on the model class which allows querying on
# translated attributes. The default scope is named +i18n+, pass a different
# name as default to change the global default, or to +translates+ in any
# model to change it for that model alone.
#
query
# Query
#
# Defines a scope on the model class which allows querying on
# translated attributes. The default scope is named +i18n+, pass a different
# name as default to change the global default, or to +translates+ in any
# model to change it for that model alone.
#
config.plugin(:query)

# Cache
#
# Comment out to disable caching reads and writes.
#
cache
# Cache
#
# Comment out to disable caching reads and writes.
#
config.plugin(:cache)

# Dirty
#
# Uncomment this line to include and enable globally:
# dirty
#
# Or uncomment this line to include but disable by default, and only enable
# per model by passing +dirty: true+ to +translates+.
# dirty false

# Column Fallback
#
# Uncomment line below to fallback to original column. You can pass
# +column_fallback: true+ to +translates+ to return original column on
# default locale, or pass +column_fallback: [:en, :de]+ to +translates+
# to return original column for those locales or pass
# +column_fallback: ->(locale) { ... }+ to +translates to evaluate which
# locales to return original column for.
# column_fallback
#
# Or uncomment this line to enable column fallback with a global default.
# column_fallback true
# Dirty
#
# Uncomment this line to include and enable globally:
# config.plugin(:dirty)
#
# Or uncomment this line to include but disable by default, and only enable
# per model by passing +dirty: true+ to +translates+.
# config.plugin(:dirty, false)

# Fallbacks
#
# Uncomment line below to enable fallbacks, using +I18n.fallbacks+.
# fallbacks
#
# Or uncomment this line to enable fallbacks with a global default.
# fallbacks(pt: :en)
# Column Fallback
#
# Uncomment line below to fallback to original column. You can pass
# +column_fallback: true+ to +translates+ to return original column on
# default locale, or pass +column_fallback: [:en, :de]+ to +translates+
# to return original column for those locales or pass
# +column_fallback: ->(locale) { ... }+ to +translates to evaluate which
# locales to return original column for.
# config.plugin(:column_fallback)
#
# Or uncomment this line to enable column fallback with a global default.
# config.plugin(:column_fallback, true)

# Presence
#
# Converts blank strings to nil on reads and writes. Comment out to
# disable.
#
presence
# Fallbacks
#
# Uncomment line below to enable fallbacks, using +I18n.fallbacks+.
# config.plugin(:fallbacks)
#
# Or uncomment this line to enable fallbacks with a global default.
# config.plugin(fallbacks, { pt: :en })

# Default
#
# Set a default translation per attributes. When enabled, passing +default:
# 'foo'+ sets a default translation string to show in case no translation is
# present. Can also be passed a proc.
#
# default 'foo'
# Presence
#
# Converts blank strings to nil on reads and writes. Comment out to
# disable.
#
config.plugin(:presence)

# Fallthrough Accessors
#
# Uses method_missing to define locale-specific accessor methods like
# +title_en+, +title_en=+, +title_fr+, +title_fr=+ for each translated
# attribute. If you know what set of locales you want to support, it's
# generally better to use Locale Accessors (or both together) since
# +method_missing+ is very slow. (You can use both fallthrough and locale
# accessor plugins together without conflict.)
#
# fallthrough_accessors
# Default
#
# Set a default translation per attributes. When enabled, passing +default:
# 'foo'+ sets a default translation string to show in case no translation is
# present. Can also be passed a proc.
#
# config.plugin(:default, 'foo')

# Locale Accessors
#
# Uses +def+ to define accessor methods for a set of locales. By default uses
# +I18n.available_locales+, but you can pass the set of locales with
# +translates+ and/or set a global default here.
#
# locale_accessors
#
# Or define specific defaults by uncommenting line below
# locale_accessors [:en, :ja]
# Fallthrough Accessors
#
# Uses method_missing to define locale-specific accessor methods like
# +title_en+, +title_en=+, +title_fr+, +title_fr=+ for each translated
# attribute. If you know what set of locales you want to support, it's
# generally better to use Locale Accessors (or both together) since
# +method_missing+ is very slow. (You can use both fallthrough and locale
# accessor plugins together without conflict.)
#
# config.plugin(:fallthrough_accessors)

# Attribute Methods
#
# Adds translated attributes to +attributes+ hash, and defines methods
# +translated_attributes+ and +untranslated_attributes+ which return hashes
# with translated and untranslated attributes, respectively. Be aware that
# this plugin can create conflicts with other gems.
#
# attribute_methods
end
# Locale Accessors
#
# Uses +def+ to define accessor methods for a set of locales. By default uses
# +I18n.available_locales+, but you can pass the set of locales with
# +translates+ and/or set a global default here.
#
# config.plugin(:locale_accessors)
#
# Or define specific defaults by uncommenting line below
# config.plugin(:locale_accessors, [:en, :ja])

# Attribute Methods
#
# Adds translated attributes to +attributes+ hash, and defines methods
# +translated_attributes+ and +untranslated_attributes+ which return hashes
# with translated and untranslated attributes, respectively. Be aware that
# this plugin can create conflicts with other gems.
#
# config.plugin(:attribute_methods)
end
Loading

0 comments on commit 49ec9b0

Please sign in to comment.