formtastic_tristate_radio 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c29b06aadeb4938a06be81d4b33c23c904d7033011aec8346d43b765f54d262
-  data.tar.gz: 471d66686e0aa7db2526642214602aa49ede7ab6183100877e9bda5954bab37d
+  metadata.gz: c61035dc61996da98086ef61f099baa1552221ccbae23e7f67a7d430494f400f
+  data.tar.gz: 870da0885677bfe7e1ccfbf02cf7b3c0c1b6803c01de4167dfd4f7cda3c5fa16
 SHA512:
-  metadata.gz: 7292702606d47a360a308d89c322bb3dda27adc62866c4bc0fa45e6939ebb841a30760684b8b299b7312838b83ebc800d1d5b83624a6d73b37d2f21f2ea33cc5
-  data.tar.gz: 97251242621b60cc2d1c9f381f29a58f408eddd44c202ba9f57ddf6c7075c54212733c70c9b7ef83c317e8fde8991b7aaaa9f79439e7d060f8f111fc6d0f6c11
+  metadata.gz: c36a9fe479ada5422ccfaf5feed00da1d9efaeeea737779bf9cfc87826ecd16864780f1c70f47d7ecb4854040bf5ef751e51aae24abd8381afaa82cfc1a1cf2a
+  data.tar.gz: b6952ce6cc1b434103f4f0abe58a6e7b8fe5d96d0691afd5275fa61c37635bcf420f18511e7bbdf6ecf7de3825d2b8416dc8e071557be5d67b51b4a9571e91f6

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [0.2.0] - 2021-11-04
+
+- Custom translation override from form via options
+- Custom error class
+- YARD documentation for everything
+- Inherits from `Formtastic::Inputs::RadioInput` and patches only necessary methods
+- Error YAML example for ActiveAdmin included only if ActiveAdmin is detected
+
+## [0.1.0] - 2021-11-01
+
+Initial release

data/README.md

@@ -1,50 +1,63 @@
 # Formtastic tri-state radio
 
+[![Gem Version](https://badge.fury.io/rb/formtastic_tristate_radio.svg)](https://badge.fury.io/rb/formtastic_tristate_radio)
+
 ## What is “tri-state”?
 
-— that which has 3 states.
+— that which has 3 states.
 
-By defenition Boolean values have 2 states: True | False.
+By defenition Boolean values have 2 states: True & False.
 
-However, if you store a Boolean value in a database column with no `NOT FULL` restriction, it aquires a 3d possible state: `null`.
+However, if you store a Boolean value in a database column with no `NOT NULL` restriction, it aquires a 3<sup>d</sup> possible state: `null`.
 
-Some may say this is a questionable practice — I don’t think so. In real life you always have a case when the answer to your question may be only “yes” or “no”, but you don’t know the answer yet. Using a string type column, storing there `"yes"`, `"no"` and `"unset"` + using a state machine + validations — feels overkill to me.
+Some may consider this practice questionable — I don’t think so. In real life you always have a case when the answer to your question may be only “yes” or “no”, but you don’t know the answer yet. Using a string type column, storing there `"yes"`, `"no"` and `"unset"` + using a state machine + validations — feels overkill to me.
 
 
 ## What the gem does
 
-1. Provides a custom Formtastic input type `:tristate_radio` which renders 3 radios (“Yes”, “No”, “Unset”) instead of a checkbox (only where you put it).
-1. Teaches Rails recognize `"null"` and `"nil"` param values as `nil`. See “[How it works](#how-it-works)” ☟ section for technical details on this.
-1. Encourages you to add translations for ActiveAdmin “status tag” so that `nil` be correctly translated as “Unset” instead of “False”.
+1. Provides a custom Formtastic input type `:tristate_radio` which renders 3 radios (“Yes”, “No”, “Unset”) instead of a checkbox (only where you put it).
+1. Teaches Rails recognize `"null"` and `"nil"` param values as `nil`. See “[How it works](#how-it-works)” ☟ section for technical details on this.
+1. Encourages you to add translations for ActiveAdmin “status tag” so that `nil` be correctly translated as “Unset” instead of “False”.
 
 
 ## Usage
 
-For a Boolean column with 3 possible states:
+For a Boolean column with 3 possible states:
 
 ```ruby
-f.input :column_name, as: :tristate_radio
+f.input :am_i_awake,      as: :tristate_radio
+f.input :is_this_a_dream, as: :tristate_radio, null: "Reality is a persistent hallucination"
 ```
 
-You get (HTML is simplified):
+You get (HTML is simplified, actually there are more classes etc.):
 
 ```html
 <fieldset>
-  <input name="column_name" type="radio" value="true">  <label>Yes</label>
-  <input name="column_name" type="radio" value="false"> <label>No</label>
-  <input name="column_name" type="radio" value="null">  <label>Unset</label>
+  <legend>Am i awake?</legend>
+  <input name="am_i_awake" type="radio" value="true">  <label>Yes</label>
+  <input name="am_i_awake" type="radio" value="false"> <label>No</label>
+  <input name="am_i_awake" type="radio" value="null">  <label>Unset</label>
 </fieldset>
-```
 
-In the future `:tristate_radio` will be registered for Boolean columns with `null` by default. Until then you have to assign it manually.
+<fieldset>
+  <legend>Is this a dream?</legend>
+  <input name="is_this_a_dream" type="radio" value="true">  <label>Yes</label>
+  <input name="is_this_a_dream" type="radio" value="false"> <label>No</label>
+  <input name="is_this_a_dream" type="radio" value="null">  <label>Reality is a persistent hallucination</label>
+</fieldset>
+```
 
 
 ## Installation
 
+### Gem
+
 ```ruby
 gem "formtastic_tristate_radio"
 ```
 
+### Translations
+
 Add translation for the new “unset” option:
 
 ```yaml
@@ -55,7 +68,15 @@ ru:
     null: Неизвестно # <- this you must provide youself
 ```
 
-ActiveAdmin will automatically translate `nil` as “No”, so if you use ActiveAdmin, add translation like so:
+As noted in [Usage](#usage), you can override individual translations like so:
+
+```ruby
+f.input :attribute, as: :tristate_radio, null: "Your text"
+```
+
+### ActiveAdmin translations
+
+ActiveAdmin will automatically translate `nil` as “No”, so if you use ActiveAdmin, add translation like so:
 
 ```yaml
 ru:
@@ -63,23 +84,25 @@ ru:
     status_tag:
       :yes: Да
       :no: Нет
-      null: Неизвестно
+      unset: Неизвестно
 ```
 
+Notice that the key ActiveAdmin uses is “unset”, not “null”.
+
 
 ## Configuration
 
-Nothing is configurable yet. I think of making configurable which values are regognized as `nil`.
+Nothing is configurable yet. I think of making configurable which values are regognized as `nil`.
 
 
 ## Dependencies
 
-Now the gem depends on [Formtastic](https://github.com/formtastic/formtastic) (naturally) and Rails. Frankly I am not sure whether I will have time to make it work with other frameworks.
+Now the gem depends on [Formtastic](https://github.com/formtastic/formtastic) (naturally) and Rails. Frankly I am not sure whether I will have time to make it work with other frameworks.
 
 
 ## How it works
 
-In Ruby any String is cast to `true`:
+In Ruby any String is cast to `true`:
 
 ```ruby
 !!""      #=> true
@@ -89,11 +112,11 @@ In Ruby any String is cast to `true`:
 !!"null"  #=> true
 ```
 
-Web form params are passed as plain text and are interpreted as String by Rack.
+Web form params are passed as plain text and are interpreted as String by Rack.
 
-So how Boolean values are transfered as strings if a `"no"` or `"0"` and even `""` is truthy in Ruby?
+So how Boolean values are transfered as strings if a `"no"` or `"0"` and even `""` is truthy in Ruby?
 
-Frameworks just have a list of string values to be recognized and mapped to Boolean values:
+Frameworks just have a list of string values to be recognized and mapped to Boolean values:
 
 ```ruby
 ActiveModel::Type::Boolean::FALSE_VALUES
@@ -115,7 +138,7 @@ ActiveModel::Type::Boolean.new.cast("off")  #=> false
 # etc
 ```
 
-So what [I do in this gem](https://github.com/sergeypedan/formtastic_tristate_radio/blob/master/config/initializers/activemodel_type_boolean.rb) is extend `ActiveModel::Type::Boolean` in a consistent way to teach it recognize null-ish values as `nil`:
+So what [I do in this gem](https://github.com/sergeypedan/formtastic_tristate_radio/blob/master/config/initializers/activemodel_type_boolean.rb) is extend `ActiveModel::Type::Boolean` in a consistent way to teach it recognize null-ish values as `nil`:
 
 ```ruby
 module ActiveModel
@@ -143,9 +166,17 @@ ActiveModel::Type::Boolean.new.cast("nil")  #=> nil
 ActiveModel::Type::Boolean.new.cast(:nil)   #=> nil
 ```
 
-**Warning**: as you might have noticed, default Rails behavior is changed. If you rely on Rails’ automatic conversion of strings with value `"null"` into `true`, this gem might not be for you (and you are definitely doing something weird).
+**Warning**: as you might have noticed, default Rails behavior is changed. If you rely on Rails’ automatic conversion of strings with value `"null"` into `true`, this gem might not be for you (and you are definitely doing something weird).
+
+
+## Roadmap
+
+- [ ] Load translations from gem
+- [ ] Add translations into most popular languages
+- [ ] Rgister `:tristate_radio` for Boolean columns with `null`
+- [ ] Decouple from Rails
 
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/inputs/tristate_radio_input.rb

@@ -3,168 +3,109 @@
 require "formtastic"
 
 # It may also be appropriate to put this file in `app/inputs`
-class TristateRadioInput
+class TristateRadioInput < Formtastic::Inputs::RadioInput
 
-  include Formtastic::Inputs::Base
-  include Formtastic::Inputs::Base::Collections
-  include Formtastic::Inputs::Base::Choices
-
-
-  # UNSET_KEY = :null
-  UNSET_KEY = ActiveModel::Type::Boolean::NULL_VALUES.reject(&:blank?).first
+  # No equals `:null`.
   #
-  # Mind ActiveAdmin status resolving logic:
-  # https://github.com/activeadmin/activeadmin/blob/master/lib/active_admin/views/components/status_tag.rb#L51
-  # In status tag builder the value is lowercased before casting into boolean, and the keyword for nil is "unset", so
-  # if we have lowercase "unset", translations from `ru.formtastic.unset` will be overriden by `ru.active_admin.status_tag.unset`.
-
-  MISSING_TRANSLATION_ERROR_MSG = <<~HEREDOC
-
+  # Mind ActiveAdmin [status resolving logic](https://github.com/activeadmin/activeadmin/blob/master/lib/active_admin/views/components/status_tag.rb#L51):
+  # in status tag builder the value is lowercased before casting into Boolean, and the keyword for nil is `"unset"`.
+  # So if we have lowercase `"unset"`, translations from `ru.formtastic.unset` will be overriden by `ru.active_admin.status_tag.unset`.
+  #
+  UNSET_KEY = ActiveModel::Type::Boolean::NULL_VALUES.reject(&:blank?).first
 
-    For ActiveAdmin status tags in index & view tables:
+  I18N_EXAMPLE_ACTIVEADMIN = <<~YAML.chomp
     ru:
       active_admin:
         status_tag:
           :yes: Да
           :no: Нет
           :#{UNSET_KEY}: Неизвестно
+  YAML
 
-    For radiobutton labels in forms:
+  I18N_EXAMPLE_FORMTASTIC = <<~YAML.chomp
     ru:
       formtastic:
         :yes: Да
         :no: Нет
         :#{UNSET_KEY}: Неизвестно
-
-    Note: “yes”, “no”, “null” and some other words are reserved, converted into Boolean values in YAML, so you need to quote or symbolize them.
-  HEREDOC
+  YAML
 
 
-  # template => an instance of ActionView::Base
+  # @note In you have ActiveAdmin installed, it will give you YAML example for ActiveAdmin as well, otherwise only for Formtastic
   #
-  # @param choice [Array], ["Completed", "completed"]
+  # @return [String] error message with YAML examples for the “unset” label translation lookup error
   #
-  def choice_html(choice)
-    template.content_tag(:label, tag_content(choice), tag_options(choice))
+  def self.missing_i18n_error_msg
+    msg = []
+    msg << "Add translations for the “unset” radio label"
+    msg << ["For radiobutton labels in forms:", I18N_EXAMPLE_FORMTASTIC].join("\n")
+    msg << "Note: “yes”, “no” and some other reserved words are converted into Boolean values in YAML, so you need to quote or symbolize them."
+    msg << ["For ActiveAdmin status tags in index & view tables:", I18N_EXAMPLE_ACTIVEADMIN].join("\n") if !!defined?(ActiveAdmin)
+    msg.join("\n\n")
   end
 
 
-  # collection => [["Completed", "completed"], ["In progress", "in_progress"], ["Unknown", "unset"]]
+  # @see https://github.com/formtastic/formtastic/blob/35dc806964403cb2bb0a6074b951ceef906c8581/lib/formtastic/inputs/base/choices.rb#L59 Original Formtastic method
   #
-  # @return [Array]
+  # @return [Hash] HTML options for the `<input type="radio" />` tag
   #
-  def collection_with_unset
-    collection + [[unset_label_translation, UNSET_KEY]]
+  # Adds `{ selected: true }` to the original options Hash if the choice value equals attribute value (to ultimately set for `checked="checked"`)
+  #
+  def choice_html_options(choice)
+    super.merge({ checked: selected?(choice) })
   end
 
 
-  # Override to remove the for attribute since this isn't associated with any element, as it's nested inside the legend
-  # @return [Hash]
+  # @example Original method
+  #   def collection_for_boolean
+  #     true_text  = options[:true]  || Formtastic::I18n.t(:yes)
+  #     false_text = options[:false] || Formtastic::I18n.t(:no)
+  #     [ [true_text, true], [false_text, false] ]
+  #   end
   #
-  # @example
-  #   { for: nil, class: ["label"] }
+  #   collection_for_boolean #=> [["Да", true], ["Нет", false]]
   #
-  def label_html_options
-    super.merge({ for: nil })
-  end
-
-
-  # choice_value(choice) => true | false | UNSET_KEY <- in our version
-  # choice_value(choice) => true | false | ?         <- in regular radio-buttons version
-  # method               => :status
-  # object               => ActiveRecord::Base model subclass, `User`
+  # @example This patched method
+  #   collection_for_boolean #=> [["Да", true], ["Нет", false], ["Неизвестно", :null]]
   #
-  # @param choice [Array], ["Completed", "completed"]
+  # @return [Array<[String, (Boolean|String|Symbol)]>] an array of “choices”, each presented as an array with 2 items: HTML label text and HTML input value
   #
-  # For this to work, ActiveModel::Type::Boolean must be patched to resolve `UNSET_KEY` as nil
+  # @see https://github.com/formtastic/formtastic/blob/e34baba470d2fda75bf9748cff8898ee0ed29075/lib/formtastic/inputs/base/collections.rb#L131 Original Formtastic method
   #
-  def selected?(choice)
-    ActiveModel::Type::Boolean.new.cast(choice_value(choice)) == object.public_send(method)
+  def collection_for_boolean
+    super + [[label_text_for_unset, UNSET_KEY]]
   end
 
 
-  # @returns [String]
-  #   "<input ...> Text..."
+  # Checks translation passed as option, then checks in locale
   #
-  # @param choice [Array], ["Completed", "completed"]
-  #
-  # input_html_options => { id: "task_status", required: false, autofocus: false, readonly: false}
+  # @example
+  #   label_text_for_unset #=> "Неизвестно"
   #
-  # input_html_options.merge(choice_html_options(choice)).merge({ required: false })
-  # => { id: "task_status_completed", required: false, autofocus: false, readonly: false }
+  # @return [String] Label of the radio that stands for the unknown choice
   #
-  # builder                     => an instance of ActiveAdmin::FormBuilder
-  # choice_label(choice)        => "Completed"
-  # choice_html_options(choice) => { id: "task_status_completed" }
-  # choice_value(choice)        => "completed"
-  # input_name                  => :status
+  # @raise [StandardError] if the translation could not be found
+  # @see missing_i18n_error_msg
   #
-  def tag_content(choice)
-    builder.radio_button(
-      input_name,
-      choice_value(choice),
-      input_html_options.merge(choice_html_options(choice)).merge({ required: false, checked: selected?(choice) })
-    ) << choice_label(choice)
+  def label_text_for_unset
+    options.fetch(:null, Formtastic::I18n.t(UNSET_KEY)).presence or \
+      fail FormtasticTristateRadio::MissingTranslationError.new(self.class.missing_i18n_error_msg)
   end
 
 
-  # choice_input_dom_id(choice) => "task_status_completed"
-  # label_html_options          => { for: nil, class: ["label"] }
-  #
-  # @param choice [Array], ["Completed", "completed"]
+  # @example For each item of `collection` it runs:
+  #   selected?(["Да", true]) #=> false
+  #   selected?(["Нет", false]) #=> false
+  #   selected?(["Неизвестно", :null]) #=> true
   #
-  def tag_options(choice)
-    label_html_options.merge({ for: choice_input_dom_id(choice), class: nil })
-  end
-
-
-  # choice_wrapping_html_options(choice) #=> { class: "choice" }
+  # @param choice [Array<[String, (Boolean|String|Symbol)]>]
   #
-  # legend_html         => "<legend class="label">
-  #                           <label>Status</label>
-  #                         </legend>"
+  # @return [Boolean] answer to the question “Is the passed option selected?”
   #
-  # choice_html(choice) => "<label for="task_status_completed">
-  #                           <input type="radio" value="completed" name="task[status]" /> Completed
-  #                         </label>"
+  # @note For this to work, `ActiveModel::Type::Boolean` must be patched to resolve `UNSET_KEY` as `nil`.
   #
-  # collection.map do |choice|
-  #   choice_wrapping({ class: "choice" }) do
-  #     choice_html(choice)
-  #   end
-  # end
-  # => ["<li class="choice">
-  #        <label for="task_status_completed">
-  #          <input type="radio" value="completed" name="task[status]" /> Completed
-  #        </label>
-  #      </li>",
-  #     "<li class="choice">
-  #      ...
-  #    ]
-  #
-  # This method relies on ActiveAdmin
-  #
-  def to_html
-    choices = collection_with_unset #=> [["Completed", "completed"], ["In progress", "in_progress"], ["Unknown", "unset"]]
-
-    input_wrapping do
-      choices_wrapping do
-        legend_html <<  choices_group_wrapping do
-                          choices.map { |choice|
-                            choice_wrapping(choice_wrapping_html_options(choice)) do
-                              choice_html(choice)
-                            end
-                          }.join("\n").html_safe
-                        end
-      end
-    end
-  end
-
-
-  # @return [String] Label of the radio that stands for the unknown choice
-  #
-  def unset_label_translation
-    Formtastic::I18n.t(UNSET_KEY).presence or fail StandardError.new(MISSING_TRANSLATION_ERROR_MSG)
+  def selected?(choice)
+    ActiveModel::Type::Boolean.new.cast(choice_value(choice)) == object.public_send(method)
   end
 
 end

data/app/models/active_record/base.rb

@@ -2,7 +2,11 @@
 
 class ActiveRecord::Base
 
-  # @return [Array] of symbols — names of Boolean columns, which can be `NULL`
+  # @return [Array<Symbol>] names of Boolean columns which can store `NULL` values
+  # @example
+  #  Company.tristate_column_names
+  #  #=> [:is_profitable, :is_run_by_psychopaths, :evades_taxation, ...]
+  #
   def self.tristate_column_names
     columns.select { |col| col.type == :boolean && col.null }.map(&:name)
   end

data/config/initializers/activemodel_type_boolean.rb

@@ -4,7 +4,7 @@ module ActiveModel
   module Type
     class Boolean < Value
 
-      NULL_VALUES = [nil, "", "null", :null, "nil", :nil].to_set.freeze
+      NULL_VALUES = [nil, "", :null, "null", :nil, "nil"].to_set.freeze
 
       private def cast_value(value)
         NULL_VALUES.include?(value) ? nil : !FALSE_VALUES.include?(value)

data/lib/formtastic_tristate_radio/engine.rb

@@ -1,4 +1,11 @@
+# frozen_string_literal: true
+
 module FormtasticTristateRadio
+
+  # This is standard Rails way to autoload gem’s contents dynamically as an “engine”
+  # https://guides.rubyonrails.org/engines.html
+  #
   class Engine < ::Rails::Engine
   end
+
 end

data/lib/formtastic_tristate_radio/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module FormtasticTristateRadio
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/formtastic_tristate_radio.rb

@@ -1,8 +1,9 @@
-require "formtastic_tristate_radio/version"
-require "formtastic_tristate_radio/engine"
-
+require_relative "formtastic_tristate_radio/version"
+require_relative "formtastic_tristate_radio/engine"
 require_relative "../app/models/active_record/base"
-# require_relative "../app/inputs/tristate_radio_input"
 
 module FormtasticTristateRadio
+
+  class MissingTranslationError < StandardError; end
+
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: formtastic_tristate_radio
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Sergey Pedan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-11-03 00:00:00.000000000 Z
+date: 2021-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: formtastic
@@ -115,7 +115,9 @@ executables: []
 extensions: []
 extra_rdoc_files:
 - README.md
+- CHANGELOG.md
 files:
+- CHANGELOG.md
 - README.md
 - Rakefile
 - app/inputs/tristate_radio_input.rb
@@ -135,7 +137,7 @@ licenses:
 - MIT
 metadata:
   changelog_uri: https://github.com/sergeypedan/formtastic-tristate-radio/blob/master/Changelog.md
-  documentation_uri: https://github.com/sergeypedan/formtastic-tristate-radio#usage
+  documentation_uri: https://www.rubydoc.info/gems/
   homepage_uri: https://github.com/sergeypedan/formtastic-tristate-radio
   source_code_uri: https://github.com/sergeypedan/formtastic-tristate-radio
 post_install_message: