with_form 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a78f39980ba03659bd61b33c94e65e8987dc590647ba8870271141a879eafca
-  data.tar.gz: ad43310ff4fd4a42ddb3f154af5c9e799f1a25c82dafdd46c9d18a6f41f48304
+  metadata.gz: 66df9d30fbbd5e884be9e81fe23e5641ed5dabc6ef6fb5a1ce06925b42f80892
+  data.tar.gz: 3e8da161fbd871b3be23be62d5f7ba83b9105c49a67333195987a7a9359364a8
 SHA512:
-  metadata.gz: 2a300ce3b20953400496bc7b7cf09e0bb9206870526c8d63cfb6987db7537ffe702788cd1543ad9eb28f83b99ac44bb39063b628be3677eac73069874a0bdbd6
-  data.tar.gz: b596e4300be6ac53de36e9e81e85514722d1763f3c877ed82aa1b5b38a04adb8d02995d625d89eb800a07938f42343a76d565aa62c0523e338e16845aa675e95
+  metadata.gz: 138a371036a91a32ccec7edd66a5dbf80a69c7def7d608d47413a3fa07c44219a34c1a6b8183acd0ef95dd71841c80ebba59ba3a40e21f96ea5362b3a06cb879
+  data.tar.gz: 4a736600b9813271f9993394d3fc0186215ee76d8abd030b9d0e2d9303dcc6e4519335e074f04aa4e4f185bcc6206d570b74b5d45d61dbf0ca7881d3c8c1b453

data/README.md

@@ -199,6 +199,165 @@ Those include:
 
 [actions]: https://www.rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Actions
 
+### `check` and `uncheck` support
+
+The `check` and `uncheck` helpers can support a mixture of argument types and
+use cases.
+
+#### `with_form(scope:)`
+
+When a call to `with_form` is passed the `scope:` option, the `check` and
+`uncheck` helpers can accept both a `String` argument, or an `Array` argument
+populated with `String` values.
+
+For example, consider the following `features/new` template:
+
+```html+erb
+<%# app/views/features/new.html.erb %>
+
+<%= form_with(scope: :features) do |form| %>
+  <%= form.label(:supported) %>
+  <%= form.check_box(:supported) %>
+
+  <%= form.label(:languages) %>
+  <%= form.collection_check_boxes(
+    :languages,
+    [
+      [ "Ruby", "ruby" ],
+      [ "JavaScript", "js" ],
+    ],
+    :last,
+    :first,
+  ) %>
+<% end %>
+```
+
+There are two styles of [`<input type="checkbox">` elements][mdn-checkbox]
+at-play in this template:
+
+* a singular `<input type="checkbox">` element that corresponds to a
+  `Boolean`-backed `supported` attribute, constructed by
+  [`ActionView::Helpers::FormBuilder#check_box`][check_box]
+
+* a collection of `<input type="checkbox">` elements that correspond to an
+  association of related `language` models, constructed by
+  [`ActionView::Helpers::FormBuilder#collection_check_boxes`][collection_check_boxes]
+
+The corresponding `check` and `uncheck` method exposed by
+`WithForm::TestHelpers` can interact with both.
+
+To check or checked the `Boolean`-backed `<input type="checkbox">` elements,
+pass the attribute's name as a [`Symbol`][ruby-symbol]:
+
+```ruby
+with_form scope: :features do |form| %>
+  form.check :supported
+
+  form.uncheck :supported
+end
+```
+
+To check or checked the `Array`-backed `<input type="checkbox">` elements,
+pass the values as either an `Array` of `String` values, or a singular `String`
+value:
+
+```ruby
+with_form scope: :features do |form| %>
+  form.check ["Ruby", "JavaScript"]
+
+  form.uncheck "JavaScript"
+end
+```
+
+#### `with_form(model:)`
+
+When a call to `with_form` is passed the `model:` option, the `check` and
+`uncheck` helpers can accept a `String` argument, an `Array` argument populated
+with `String` values, or a singular [`Symbol` argument][ruby-symbol].
+
+For example, consider the following hypothetical models:
+
+Next, consider rendering a `<form>` element within the `features/new` template:
+
+```html+erb
+<%# app/views/features/new.html.erb %>
+
+<%= form_with(model: Feature.new) do |form| %>
+  <%= form.label(:supported) %>
+  <%= form.check_box(:supported) %>
+
+  <%= form.label(:language_ids) %>
+  <%= form.collection_check_boxes(
+    :language_ids,
+    Language.all,
+    :id,
+    :name,
+  ) %>
+<% end %>
+```
+
+There are two styles of [`<input type="checkbox">` elements][mdn-checkbox]
+at-play in this template:
+
+* a singular `<input type="checkbox">` element that corresponds to a
+  `Boolean`-backed `supported` attribute, constructed by
+  [`ActionView::Helpers::FormBuilder#check_box`][check_box]
+
+* a collection of `<input type="checkbox">` elements that correspond to an
+  association of related `Language` models, constructed by
+  [`ActionView::Helpers::FormBuilder#collection_check_boxes`][collection_check_boxes]
+
+The corresponding `check` and `uncheck` method exposed by
+`WithForm::TestHelpers` can interact with both.
+
+To check or checked the `Boolean`-backed `<input type="checkbox">` elements,
+pass the attribute's name as a [`Symbol`][ruby-symbol]:
+
+```ruby
+with_form model: Feature.new(supported: false) do |form| %>
+  form.check :supported
+
+  form.uncheck :supported
+end
+```
+
+To check or checked the `Array`-backed `<input type="checkbox">` elements,
+pass the values as either an `Array` of `String` values, or a singular `String`
+value:
+
+```ruby
+feature = Feature.new(languages: Language.all, supported: true)
+
+with_form model: feature do |form| %>
+  form.uncheck :supported
+
+  form.uncheck feature.languages.map(&:name)
+
+  form.check ["Ruby", "JavaScript"]
+
+  form.uncheck "JavaScript"
+end
+```
+
+When interacting with the `Boolean`-backed variation of the `<input
+type="checkbox">` element through the `form.check` or `form.uncheck` calls, the
+end-state of the `<input>` element will **always** correspond to the variation
+of `check` or `uncheck`.
+
+More directly stated: calls to `check` **will always** result in `<input
+type="checkbox" checked>`, and calls to `uncheck` **will always** result in
+`<input type="checkbox">`, regardless of the value of `Feature#supported`.
+
+If your intention is that the `<input>` have the [`checked`
+attribute][mdn-checked], call `check`. If your intention is that the `<input>`
+_not_ have the [`checked` attribute][mdn-checked], call `uncheck`.
+
+[mdn-checkbox]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input/checkbox
+[check_box]: https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html#method-i-check_box
+[collection_check_boxes]: https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html#method-i-collection_check_boxes
+[ruby-symbol]: https://ruby-doc.org/core-2.7.1/Symbol.html
+[mdn-checked]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input/checkbox#checked
+
 #### ActionText `rich_text_area` support
 
 When [`ActionText`][actiontext] is available, `with_form` provides a

data/db/migrate/20200310042146_create_widget_records.rb

@@ -1,4 +1,4 @@
-class CreateWidgetRecords < ActiveRecord::Migration[Rails.version.to_f]
+class CreateWidgetRecords < ActiveRecord::Migration[5.2]
   def change
     create_table :widget_records do |t|
       t.text :text_field

data/db/migrate/20200417133424_add_boolean_check_box_field_to_widget_records.rb

@@ -0,0 +1,7 @@
+class AddBooleanCheckBoxFieldToWidgetRecords < ActiveRecord::Migration[5.2]
+  def change
+    change_table :widget_records do |t|
+      t.boolean :boolean_check_box_field
+    end
+  end
+end

data/lib/with_form/model_form.rb

@@ -32,9 +32,8 @@ module WithForm
     end
 
     def choose(attribute, **options)
-      case attribute
-      when Symbol
-        value = @model.public_send(attribute)
+      if attribute.kind_of? Symbol
+        value = read_attribute(attribute)
       else
         value = attribute
       end
@@ -43,31 +42,28 @@ module WithForm
     end
 
     def check(attribute, **options)
-      case attribute
-      when Symbol
-        values = Array(@model.public_send(attribute))
+      if attribute.kind_of? Symbol
+        value = read_attribute(attribute)
       else
-        values = Array(attribute)
+        value = attribute
       end
 
-      values.each { |value| scope_form.check(value, **options) }
+      Array(value).each { |value| scope_form.check(value, **options) }
     end
 
     def uncheck(attribute, **options)
-      case attribute
-      when Symbol
-        values = Array(@model.public_send(attribute))
+      if attribute.kind_of? Symbol
+        value = read_attribute(attribute)
       else
-        values = Array(attribute)
+        value = attribute
       end
 
-      values.each { |value| scope_form.uncheck(value, **options) }
+      Array(value).each { |value| scope_form.uncheck(value, **options) }
     end
 
     def select(attribute, from: nil, **options)
-      case attribute
-      when Symbol
-        value = @model.public_send(attribute)
+      if attribute.kind_of? Symbol
+        value = read_attribute(attribute)
       else
         value = attribute
       end
@@ -76,9 +72,8 @@ module WithForm
     end
 
     def unselect(attribute, from: nil, **options)
-      case attribute
-      when Symbol
-        value = @model.public_send(attribute)
+      if attribute.kind_of? Symbol
+        value = read_attribute(attribute)
       else
         value = attribute
       end
@@ -102,5 +97,15 @@ module WithForm
     def scope_form
       WithForm::ScopeForm.new(scope: @model.model_name.i18n_key, page: @page)
     end
+
+    def read_attribute(attribute)
+      attribute_value = @model.public_send(attribute)
+
+      if attribute_value.in?([true, false, nil])
+        attribute
+      else
+        attribute_value
+      end
+    end
   end
 end

data/lib/with_form/version.rb

@@ -1,3 +1,3 @@
 module WithForm
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: with_form
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Sean Doyle
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-04-12 00:00:00.000000000 Z
+date: 2020-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -106,6 +106,7 @@ files:
 - README.md
 - Rakefile
 - db/migrate/20200310042146_create_widget_records.rb
+- db/migrate/20200417133424_add_boolean_check_box_field_to_widget_records.rb
 - lib/tasks/with_form_tasks.rake
 - lib/with_form.rb
 - lib/with_form/engine.rb