formtastic_tristate_radio 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3c29b06aadeb4938a06be81d4b33c23c904d7033011aec8346d43b765f54d262
+  data.tar.gz: 471d66686e0aa7db2526642214602aa49ede7ab6183100877e9bda5954bab37d
+SHA512:
+  metadata.gz: 7292702606d47a360a308d89c322bb3dda27adc62866c4bc0fa45e6939ebb841a30760684b8b299b7312838b83ebc800d1d5b83624a6d73b37d2f21f2ea33cc5
+  data.tar.gz: 97251242621b60cc2d1c9f381f29a58f408eddd44c202ba9f57ddf6c7075c54212733c70c9b7ef83c317e8fde8991b7aaaa9f79439e7d060f8f111fc6d0f6c11

data/README.md

@@ -0,0 +1,151 @@
+# Formtastic tri-state radio
+
+## What is “tri-state”?
+
+— that which has 3 states.
+
+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`.
+
+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.
+
+
+## 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”.
+
+
+## Usage
+
+For a Boolean column with 3 possible states:
+
+```ruby
+f.input :column_name, as: :tristate_radio
+```
+
+You get (HTML is simplified):
+
+```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>
+</fieldset>
+```
+
+In the future `:tristate_radio` will be registered for Boolean columns with `null` by default. Until then you have to assign it manually.
+
+
+## Installation
+
+```ruby
+gem "formtastic_tristate_radio"
+```
+
+Add translation for the new “unset” option:
+
+```yaml
+ru:
+  formtastic:
+    # :yes: Да       # <- these two fall back to translations
+    # :no: Нет       #    in Formtastic gem but have only English
+    null: Неизвестно # <- this you must provide youself
+```
+
+ActiveAdmin will automatically translate `nil` as “No”, so if you use ActiveAdmin, add translation like so:
+
+```yaml
+ru:
+  active_admin:
+    status_tag:
+      :yes: Да
+      :no: Нет
+      null: Неизвестно
+```
+
+
+## Configuration
+
+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.
+
+
+## How it works
+
+In Ruby any String is cast to `true`:
+
+```ruby
+!!""      #=> true
+!!"false" #=> true
+!!"nil"   #=> true
+!!"no"    #=> true
+!!"null"  #=> true
+```
+
+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?
+
+Frameworks just have a list of string values to be recognized and mapped to Boolean values:
+
+```ruby
+ActiveModel::Type::Boolean::FALSE_VALUES
+#=> [
+   0, "0", :"0",
+  "f", :f, "F", :F,
+  false, "false", :false, "FALSE", :FALSE,
+  "off", :off, "OFF", :OFF,
+]
+```
+
+so that
+
+```ruby
+ActiveModel::Type::Boolean.new.cast("0")    #=> false
+ActiveModel::Type::Boolean.new.cast("f")    #=> false
+ActiveModel::Type::Boolean.new.cast(:FALSE) #=> false
+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`:
+
+```ruby
+module ActiveModel
+  module Type
+    class Boolean < Value
+
+      NULL_VALUES = [nil, "", "null", :null, "nil", :nil].to_set.freeze
+
+      private def cast_value(value)
+        NULL_VALUES.include?(value) ? nil : !FALSE_VALUES.include?(value)
+      end
+
+    end
+  end
+end
+```
+
+And voila!
+
+```ruby
+ActiveModel::Type::Boolean.new.cast("")     #=> nil
+ActiveModel::Type::Boolean.new.cast("null") #=> nil
+ActiveModel::Type::Boolean.new.cast(:null)  #=> nil
+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).
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+
+# APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+task default: :spec

data/app/inputs/tristate_radio_input.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "formtastic"
+
+# It may also be appropriate to put this file in `app/inputs`
+class TristateRadioInput
+
+  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
+  #
+  # 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
+
+
+    For ActiveAdmin status tags in index & view tables:
+    ru:
+      active_admin:
+        status_tag:
+          :yes: Да
+          :no: Нет
+          :#{UNSET_KEY}: Неизвестно
+
+    For radiobutton labels in forms:
+    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
+
+
+  # template => an instance of ActionView::Base
+  #
+  # @param choice [Array], ["Completed", "completed"]
+  #
+  def choice_html(choice)
+    template.content_tag(:label, tag_content(choice), tag_options(choice))
+  end
+
+
+  # collection => [["Completed", "completed"], ["In progress", "in_progress"], ["Unknown", "unset"]]
+  #
+  # @return [Array]
+  #
+  def collection_with_unset
+    collection + [[unset_label_translation, UNSET_KEY]]
+  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
+  #   { for: nil, class: ["label"] }
+  #
+  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`
+  #
+  # @param choice [Array], ["Completed", "completed"]
+  #
+  # For this to work, ActiveModel::Type::Boolean must be patched to resolve `UNSET_KEY` as nil
+  #
+  def selected?(choice)
+    ActiveModel::Type::Boolean.new.cast(choice_value(choice)) == object.public_send(method)
+  end
+
+
+  # @returns [String]
+  #   "<input ...> Text..."
+  #
+  # @param choice [Array], ["Completed", "completed"]
+  #
+  # input_html_options => { id: "task_status", required: false, autofocus: false, readonly: false}
+  #
+  # input_html_options.merge(choice_html_options(choice)).merge({ required: false })
+  # => { id: "task_status_completed", required: false, autofocus: false, readonly: false }
+  #
+  # 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
+  #
+  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)
+  end
+
+
+  # choice_input_dom_id(choice) => "task_status_completed"
+  # label_html_options          => { for: nil, class: ["label"] }
+  #
+  # @param choice [Array], ["Completed", "completed"]
+  #
+  def tag_options(choice)
+    label_html_options.merge({ for: choice_input_dom_id(choice), class: nil })
+  end
+
+
+  # choice_wrapping_html_options(choice) #=> { class: "choice" }
+  #
+  # legend_html         => "<legend class="label">
+  #                           <label>Status</label>
+  #                         </legend>"
+  #
+  # choice_html(choice) => "<label for="task_status_completed">
+  #                           <input type="radio" value="completed" name="task[status]" /> Completed
+  #                         </label>"
+  #
+  # 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)
+  end
+
+end

data/app/models/active_record/base.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class ActiveRecord::Base
+
+  # @return [Array] of symbols — names of Boolean columns, which can be `NULL`
+  def self.tristate_column_names
+    columns.select { |col| col.type == :boolean && col.null }.map(&:name)
+  end
+
+end

data/config/initializers/activemodel_type_boolean.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ActiveModel
+  module Type
+    class Boolean < Value
+
+      NULL_VALUES = [nil, "", "null", :null, "nil", :nil].to_set.freeze
+
+      private def cast_value(value)
+        NULL_VALUES.include?(value) ? nil : !FALSE_VALUES.include?(value)
+      end
+
+    end
+  end
+end

data/config/locales/active_admin.en.yml

@@ -0,0 +1,5 @@
+---
+en:
+  active_admin:
+    status_tag:
+      unset: Unset

data/config/locales/active_admin.ru.yml

@@ -0,0 +1,7 @@
+---
+ru:
+  active_admin:
+    status_tag:
+      :no: Нет
+      :yes: Да
+      unset: Неизвестно

data/config/locales/formtastic.en.yml

@@ -0,0 +1,4 @@
+---
+en:
+  formtastic:
+    :null: Unset

data/config/locales/formtastic.ru.yml

@@ -0,0 +1,6 @@
+---
+ru:
+  formtastic:
+    :no: Нет
+    :null: Неизвестно
+    :yes: Да

data/config/routes.rb

@@ -0,0 +1,2 @@
+Rails.application.routes.draw do
+end

data/lib/formtastic_tristate_radio/engine.rb

@@ -0,0 +1,4 @@
+module FormtasticTristateRadio
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/formtastic_tristate_radio/version.rb

@@ -0,0 +1,3 @@
+module FormtasticTristateRadio
+  VERSION = '0.1.0'
+end

data/lib/formtastic_tristate_radio.rb

@@ -0,0 +1,8 @@
+require "formtastic_tristate_radio/version"
+require "formtastic_tristate_radio/engine"
+
+require_relative "../app/models/active_record/base"
+# require_relative "../app/inputs/tristate_radio_input"
+
+module FormtasticTristateRadio
+end

data/lib/tasks/formtastic_tristate_radio_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :formtastic_tristate_radio do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,166 @@
+--- !ruby/object:Gem::Specification
+name: formtastic_tristate_radio
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sergey Pedan
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2021-11-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: formtastic
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: 'Have 3-state radiobuttons instead of a 2-state checkbox for your Boolean
+  columns which can store NULL. Does not change controls, you need to turn it on via
+  `as: :tristate_radio` option.'
+email:
+- sergey.pedan@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- Rakefile
+- app/inputs/tristate_radio_input.rb
+- app/models/active_record/base.rb
+- config/initializers/activemodel_type_boolean.rb
+- config/locales/active_admin.en.yml
+- config/locales/active_admin.ru.yml
+- config/locales/formtastic.en.yml
+- config/locales/formtastic.ru.yml
+- config/routes.rb
+- lib/formtastic_tristate_radio.rb
+- lib/formtastic_tristate_radio/engine.rb
+- lib/formtastic_tristate_radio/version.rb
+- lib/tasks/formtastic_tristate_radio_tasks.rake
+homepage: https://github.com/sergeypedan/formtastic-tristate-radio
+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
+  homepage_uri: https://github.com/sergeypedan/formtastic-tristate-radio
+  source_code_uri: https://github.com/sergeypedan/formtastic-tristate-radio
+post_install_message:
+rdoc_options:
+- "--charset=UTF-8"
+require_paths:
+- lib
+- app/inputs
+- app/models/active_record
+- config/initializers
+- config/locales
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.15
+signing_key:
+specification_version: 4
+summary: Have 3-state radiobuttons instead of a 2-state checkbox for your Boolean
+  columns which can store NULL
+test_files: []