diff --git a/README.md b/README.md index 632e0dcb..e4ebe5ad 100644 --- a/README.md +++ b/README.md @@ -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 ``` @@ -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). @@ -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. @@ -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 @@ -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: @@ -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: @@ -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 @@ -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 @@ -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 @@ -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 @@ -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`. diff --git a/lib/rails/generators/mobility/templates/initializer.rb b/lib/rails/generators/mobility/templates/initializer.rb index 895b08a8..2b8efaa5 100644 --- a/lib/rails/generators/mobility/templates/initializer.rb +++ b/lib/rails/generators/mobility/templates/initializer.rb @@ -1,129 +1,133 @@ -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 - # +_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 + # +_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 diff --git a/spec/generators/rails/mobility/install_generator_spec.rb b/spec/generators/rails/mobility/install_generator_spec.rb index cba3f5dc..d3fe2a95 100644 --- a/spec/generators/rails/mobility/install_generator_spec.rb +++ b/spec/generators/rails/mobility/install_generator_spec.rb @@ -25,10 +25,9 @@ directory "initializers" do file "mobility.rb" do contains "Mobility.configure do" - contains "plugins do" - contains "backend :key_value" - contains "backend_reader" - contains "query" + contains "config.plugin(:backend, :key_value)" + contains "config.plugin(:backend_reader)" + contains "config.plugin(:query)" end end end