actionview_attribute_builders 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b86da009d7cc1776185d530b5a36d0b987c45ae6decbe56e6417d16d491462bb
-  data.tar.gz: 53e398656df6d9e343c4efa880ebb49b8ae2db108dc5467cb77b6abb8467970f
+  metadata.gz: 43274cf57e396d3787e0edc0c015784d9cf2a5f2eadc0ca10c2a64cd3ab8f162
+  data.tar.gz: 4e1dccf8cb53ba229f2a3285338831a01632f2fbc5a2f313404684fe2179c819
 SHA512:
-  metadata.gz: 599cc0f4d55bddea629a960f26d0f4a681af8510e4c37b82db6085dedc8ca5791acb4024dc7b151347bd8a63aa738b775895b10c2b59fc2cc19b2e869b116fc7
-  data.tar.gz: 38594b7e1a5ef99db5ce279ecabc97957803cf099dd1c13183c44ceacd4ccbe8bfe07a522b4125ce3508ea5f5b56f84e6248106fce40c0c67a9e9b6d711954bd
+  metadata.gz: 6115d771857a6ea74ddf94c104fa0b9cdedbfeb67599b57a1c4c21576ad8639234b0d9b130d0349a29c11e63d2d324ad4d17e913655b3fa5c9f97a73ae8c5046
+  data.tar.gz: fe14aa3aefbd5a87f86fbbcf9ba68dd077f22d39006022d8f25d32e98589d5f92286e12f0f004c514b5a3f22458ac91fda1c27207c555bbb2dd0eaa1c861a530

data/README.md

@@ -1,28 +1,185 @@
-# ActionviewAttributeBuilders
-Short description and motivation.
+# Actionview::AttributeBuilders
+> 🧪 ☣️ This gem is an experiment. Please do not use it for anything other than to explore the new concepts it brings into Rails.
 
-## Usage
-How to use my plugin.
+**New!**
 
-## Installation
-Add this line to your application's Gemfile:
+Visit the AttributeBuilders playground https://attributebuilders.julianpinzon.com to see all of this in action!
+
+## 🧑🏽‍💻 Installation
+
+Install the gem in your Rails application. Use:
+```bash
+$ bundle add actionview_attribute_builders
+```
+
+Or add it directly in your Gemfile
 
 ```ruby
-gem "actionview_attribute_builders"
+gem 'actionview_attribute_builders', '~> 0.1.0'
 ```
 
 And then execute:
 ```bash
 $ bundle
 ```
+## 🧑🏽‍🎨 Usage
 
-Or install it yourself as:
-```bash
-$ gem install actionview_attribute_builders
+**1. Create a custom form builder**
+
+```ruby
+# app/form_builders/example_form_builder.rb
+ 
+class ExampleFormBuilder < ActionView::Helpers::FormBuilder
+end
+```
+
+**2. Add a `text_field` method, overriding the one inherited from its parent (Rails' default)**
+
+```ruby
+# app/form_builders/example_form_builder.rb
+ 
+class ExampleFormBuilder < ActionView::Helpers::FormBuilder
+  def text_field(method, options = {})
+    # ...
+  end
+end
 ```
 
+**3. Use the appropriate `<helper>_attribute_builder` method for the type of field you're creating**
+
+In this case `text_field_attribute_builder`
+
+```ruby
+# app/form_builders/example_form_builder.rb
+ 
+class ExampleFormBuilder < ActionView::Helpers::FormBuilder
+  def text_field(method, options = {})
+    # 1. Retreive an instance of the `AttributeBuilders::TextField` class via the helper method
+    attribute_builder = text_field_attribute_builder(method, options)
+    # 2. Use the `html_attributes` method to retrieve the computed attributes. Commonly, `id`, `name`, `value` etc.
+    html_attributes = attribute_builder.html_attributes
+    # => { id: "user_name", name: "user[name]", value: "Julian" }
+  end
+end
+```
+
+**4. Render the HTML form element**
+
+```ruby
+# app/form_builders/example_form_builder.rb
+ 
+class ExampleFormBuilder < ActionView::Helpers::FormBuilder
+  def text_field(method, options = {})
+    # ...
+    # 3. Use the attributes to create the markup.
+    
+    # 3.1 For example, use a web component
+    @template.content_tag("example-text-field", nil,  html_attributes.merge!(options))
+
+    # 3.1 Or a ViewComponent
+    @template.render(ExampleFieldComponent.new(html_attributes, options))
+  end
+end
+```
+
+**5. Use the new form builder in a template**
+
+```erb
+<%= form_with model: @user, builder: ExampleFormBuilder do |form| %>
+  <%= form.text_field :name, required: true, label: "Name" %>
+<% end %>
+```
+
+**6. Check the output in your browser's inspector to verify the new markup**
+
+Note how, just like in a plain Rails application, the field includes the conventional `name`, `type` and `id` attributes based on the model used.
+
+```html
+<form action="/users" accept-charset="UTF-8" method="post"><input type="hidden" name="authenticity_token" value="3EgNNhL-HUI-2gxV_-9T_cEaT8p6b4CWtVbQMCeHlaKlfgd_p9sFuuLVKaDkUt3gEQKhc_d7YdR-TFzp-LiAuA" autocomplete="off">
+  <example-text-field required="" type="text" name="user[name]" id="user_name"></example-text-field>
+</form>
+
+```
+
+**6. Do this for \*every form helper**
+
+`number_field`, `password_field`, `checkbox` etc. 
+
+<small>* _every helper that's currently supported. Not all of them are done_<small>
+
+## 🏞️ Concrete examples
+
+### Playground
+Visit the Attribute Builders playground https://attributebuilders.julianpinzon.com for an interactive preview of this gem in action.
+
+### Implementation guides
+
+> 👀 Images inside!
+
+Visit the [examples](/examples) folder and follow the guides on how to use this with real components using Shoelace and Material Design Web Components.
+
+## 🔧 API
+
+This library exposes helpers that use _the exact same mechanics to create form input element attributes_ that Rails uses internally to create input elements that are compliant with `ActiveModel` and `ActiveRecord`conventions.
+
+Check out the [lib/actionview_attribute_builders/attribute_builders_helper](AttributeBuildersHelper) for a list of all currently supported builders.
+
+## ☢️ Status
+
+This library is **not finished**. There are several things missing. For example:
+1. Not all attribute builders have been extracted from Rails. There are currently 4 missing input fields and some extra missing helpers (like buttons and input submit fields)
+2. Some helpers are far more complex than others and probably can't be used yet in a real scenario. For example, `<select>` tags (and similar elements) are harder because they are composed of not one but multiple html elements (`<select>` and `<option>`). This problem is yet to be solved.
+3. The way the gem is loaded is a bit hacky and has a lot of garbage comments.
+
+### ⚙️ Current AttributeBuilders compatibility with ActionView Tags
+| Attributer Builder        | Available? |
+|---------------------------|------------|
+| check_box                 | ✅          |
+| collection_check_boxes    | ◻️         |
+| collection_radio_buttons  | ◻️         |
+| collection_select         | ✅          |
+| color_field               | ✅          |
+| date_field                | ✅          |
+| date_select               | ◻️         |
+| datetime_field            | ✅          |
+| datetime_select           | ◻️         |
+| email_field               | ✅          |
+| file_field                | ✅          |
+| grouped_collection_select | ✅          |
+| hidden_field              | ✅          |
+| label                     | ✅          |
+| month_field               | ✅          |
+| number_field              | ✅          |
+| password_field            | ✅          |
+| radio_button              | ✅          |
+| range_field               | ✅          |
+| search_field              | ✅          |
+| select                    | ✅          |
+| tel_field                 | ✅          |
+| text_area                 | ✅          |
+| text_field                | ✅          |
+| time_field                | ✅          |
+| time_select               | ◻️         |
+| time_zone_select          | ✅          |
+| url_field                 | ✅          |
+| week_field                | ✅          |
+| weekday_select            | ✅          |
+| submit                    | ❌          |
+| button                    | ❌          |
+
+## 💎 What problem is this solving?
+The short version is that Rails has a lot of conventions for form fields to work seamlessly with `ActiveModel` and `ActiveRecord`. However, these are not exposed to developers; they are deeply nested and coupled to the rendering of the actual markup. This makes creating new `FormBuilders` notoriously hard or even impossible in some cases. This forces developers to abandon Rails' conventions which is not desirable.
+
+This gem's objective is to separate those responsibilities so developers can leverage Rails' conventions to build custom form elements and keep enjoying the advantages of [convention over configuraiton](https://rubyonrails.org/doctrine#convention-over-configuration).
+
+I have written extensively about this problem. If you're interested, please read the following:
+1. https://dev.julianpinzon.com/series/exploring-rails-forms
+2. https://github.com/ViewComponent/view_component/discussions/420#discussioncomment-867525
+
 ## Contributing
-Contribution directions go here.
+The best way to contribute to this gem in its current state is:
+1. to experiment with it and build custom `FormBuilder` classes.
+2. start a discussion or issue on this repo
 
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/actionview_attribute_builders/attribute_builders/button.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+require "action_view/helpers/attribute_builders/submittable"
+
+module ActionView
+  module Helpers
+    module AttributeBuilders # :nodoc:
+      class Button # :nodoc:
+        include Submittable
+
+        attr_reader :value
+
+        def initialize(value = nil, options = {}, object, object_name, template_object)
+          @object_name = object_name
+          @object = object
+          @template_object = template_object
+          @value = value
+          @options = options
+
+          case @value
+          when Hash
+            @options = @value
+            @value = nil
+          when Symbol
+            @options = { name: @template_object.field_name(@value), id: @template_object.field_id(@value) }.merge!(@options.to_h)
+            @value = nil
+          end
+
+          @value ||= submit_default_value
+
+          formmethod = @options[:formmethod]
+          if formmethod.present? && !/post|get/i.match?(formmethod) && !@options.key?(:name) && !@options.key?(:value)
+            @options.merge! formmethod: :post, name: "_method", value: formmethod
+          end
+        end
+
+        def html_attributes
+          @options
+        end
+      end
+    end
+  end
+end

data/lib/actionview_attribute_builders/attribute_builders/submit.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+require "action_view/helpers/attribute_builders/submittable"
+
+module ActionView
+  module Helpers
+    module AttributeBuilders # :nodoc:
+      class Submit # :nodoc:
+        include Submittable
+
+        attr_reader :value
+
+        def initialize(value = nil, options = {}, object, object_name)
+          @object_name = object_name
+          @object = object
+          @value = value
+          @options = options
+
+          @value, @options = nil, @value if @value.is_a?(Hash)
+          @value ||= submit_default_value
+        end
+
+        def html_attributes
+          @options
+        end
+      end
+    end
+  end
+end

data/lib/actionview_attribute_builders/attribute_builders/submittable.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module ActionView
+  module Helpers
+    module AttributeBuilders # :nodoc:
+      module Submittable # :nodoc:
+        include ModelNaming
+
+        private
+          def submit_default_value
+            object = convert_to_model(@object)
+            key    = object ? (object.persisted? ? :update : :create) : :submit
+
+            model = if object.respond_to?(:model_name)
+              object.model_name.human
+            else
+              @object_name.to_s.humanize
+            end
+
+            defaults = []
+            # Object is a model and it is not overwritten by as and scope option.
+            if object.respond_to?(:model_name) && @object_name.to_s == model.downcase
+              defaults << :"helpers.submit.#{object.model_name.i18n_key}.#{key}"
+            else
+              defaults << :"helpers.submit.#{@object_name}.#{key}"
+            end
+            defaults << :"helpers.submit.#{key}"
+            defaults << "#{key.to_s.humanize} #{model}"
+
+            I18n.t(defaults.shift, model: model, default: defaults)
+          end
+      end
+    end
+  end
+end

data/lib/actionview_attribute_builders/attribute_builders.rb

@@ -26,36 +26,12 @@ require_relative "attribute_builders/range_field"
 require_relative "attribute_builders/url_field"
 require_relative "attribute_builders/week_field"
 
+require_relative "attribute_builders/button"
+require_relative "attribute_builders/submit"
+
 module ActionView
   module Helpers # :nodoc:
     module AttributeBuilders # :nodoc:
-      # extend ActiveSupport::Autoload
-      #
-      # eager_autoload do
-      #   autoload :Base
-      #   autoload :CheckBox
-      #   autoload :ColorField
-      #   autoload :DateField
-      #   autoload :DatetimeField
-      #   autoload :DatetimeLocalField
-      #   autoload :EmailField
-      #   autoload :FileField
-      #   autoload :HiddenField
-      #   autoload :Label
-      #   autoload :MonthField
-      #   autoload :NumberField
-      #   autoload :RadioButton
-      #   autoload :SearchField
-      #   autoload :Select
-      #   autoload :TelField
-      #   autoload :TextArea
-      #   autoload :TextField
-      #   autoload :TimeField
-      #   autoload :PasswordField
-      #   autoload :RangeField
-      #   autoload :UrlField
-      #   autoload :WeekField
-      # end
     end
   end
 end

data/lib/actionview_attribute_builders/attribute_builders_helper.rb

@@ -1,39 +1,127 @@
 module ActionviewAttributeBuilders
   module AttributeBuildersHelper
+
+    def checkbox_attribute_builder(method, options, checked_value)
+      ActionView::Helpers::AttributeBuilders::CheckBox.new(object_name, method, @template, checked_value, options)
+    end
+
+    def collection_check_boxes_attribute_builder
+      raise NotImplementedError
+    end
+
+    def collection_radio_buttons_attribute_builder
+      raise NotImplementedError
+    end
+
     def color_field_attribute_builder(method, options)
       ActionView::Helpers::AttributeBuilders::ColorField.new(object_name, method, @template, options)
     end
 
+    def date_field_attribute_builder(method, options)
+      ActionView::Helpers::AttributeBuilders::DateField.new(object_name, method, @template, options)
+    end
+
+    def date_select_attribute_builder
+      raise NotImplementedError
+    end
+
+    def datetime_field_attribute_builder(method, options)
+      ActionView::Helpers::AttributeBuilders::DatetimeField.new(object_name, method, @template, options)
+    end
+
+    def datetime_select_attribute_builder
+      raise NotImplementedError
+    end
+
     def email_field_attribute_builder(method, options)
       ActionView::Helpers::AttributeBuilders::EmailField.new(object_name, method, @template, options)
     end
 
+    def file_field_attribute_builder(method, options)
+      ActionView::Helpers::AttributeBuilders::FileField.new(object_name, method, @template, options)
+    end
+
+    # grouped_collection_select
+
+    def hidden_field_attribute_builder(method, options)
+      ActionView::Helpers::AttributeBuilders::HiddenField.new(object_name, method, @template, options)
+    end
+
+    def label_attribute_builder(method, content_or_options, options)
+      ActionView::Helpers::AttributeBuilders::Label.new(object_name, method, @template, content_or_options, options)
+    end
+
+    def month_field_attribute_builder(method, options)
+      ActionView::Helpers::AttributeBuilders::MonthField.new(object_name, method, @template, options)
+    end
+
     def number_field_attribute_builder(method, options)
       ActionView::Helpers::AttributeBuilders::NumberField.new(object_name, method, @template, options)
     end
 
+    def password_field_attribute_builder(method, options)
+      ActionView::Helpers::AttributeBuilders::PasswordField.new(object_name, method, @template, options)
+    end
+
+    def radio_button_attribute_builder(method, tag_value, options)
+      ActionView::Helpers::AttributeBuilders::RadioButton.new(object_name, method, @template, tag_value, options)
+    end
+
+    def range_field_attribute_builder(method, options)
+      ActionView::Helpers::AttributeBuilders::RangeField.new(object_name, method, @template, options)
+    end
+
     def search_field_attribute_builder(method, options)
       ActionView::Helpers::AttributeBuilders::SearchField.new(object_name, method, @template, options)
     end
 
+    def select_attribute_builder(method, options, html_options)
+      ActionView::AttributeBuilders::AttributeBuilders::Select.new(object, method, @template, options, html_options)
+    end
+
     def tel_field_attribute_builder(method, options)
       ActionView::Helpers::AttributeBuilders::TelField.new(object_name, method, @template, options)
     end
 
+    def text_area_attribute_builder(method, options)
+      ActionView::Helpers::AttributeBuilders::TextArea.new(object_name, method, @template, options)
+    end
+
     def text_field_attribute_builder(method, options)
       ActionView::Helpers::AttributeBuilders::TextField.new(object_name, method, @template, options)
     end
 
-    def password_field_attribute_builder(method, options)
-      ActionView::Helpers::AttributeBuilders::PasswordField.new(object_name, method, @template, options)
+    def time_field_attribute_builder(method, options)
+      ActionView::Helpers::AttributeBuilders::TimeField.new(object_name, method, @template, options)
+    end
+
+    def time_select_attribute_builder
+      raise NotImplementedError
+    end
+
+    def time_zone_select_attribute_builder(method, options, html_options)
+      ActionView::Helpers::AttributeBuilders::Select.new(object_name, method, @template, options, html_options)
     end
 
     def url_field_attribute_builder(method, options)
       ActionView::Helpers::AttributeBuilders::UrlField.new(object_name, method, @template, options)
     end
 
-    def checkbox_attribute_builder(method, options, checked_value)
-      ActionView::Helpers::AttributeBuilders::CheckBox.new(object_name, method, @template, checked_value, options)
+    def week_field_attribute_builder(method, options)
+      ActionView::Helpers::AttributeBuilders::WeekField.new(object_name, method, @template, options)
     end
+
+    def weekday_select_attribute_builder(method, options, html_options)
+      ActionView::Helpers::AttributeBuilders::Select.new(object_name, method, @template, options, html_options)
+    end
+
+    def button_attribute_builder(value, options)
+      ActionView::Helpers::AttributeBuilders::Button.new(value, options, object_name, @template)
+    end
+
+    def submit_attribute_builder(value, options)
+      ActionView::Helpers::AttributeBuilders::Submit.new(value, options, object_name)
+    end
+
   end
 end

data/lib/actionview_attribute_builders/version.rb

@@ -1,3 +1,3 @@
 module ActionviewAttributeBuilders
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: actionview_attribute_builders
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Julián Pinzón Eslava
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-20 00:00:00.000000000 Z
+date: 2023-11-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -38,6 +38,7 @@ files:
 - lib/actionview_attribute_builders.rb
 - lib/actionview_attribute_builders/attribute_builders.rb
 - lib/actionview_attribute_builders/attribute_builders/base.rb
+- lib/actionview_attribute_builders/attribute_builders/button.rb
 - lib/actionview_attribute_builders/attribute_builders/check_box.rb
 - lib/actionview_attribute_builders/attribute_builders/checkable.rb
 - lib/actionview_attribute_builders/attribute_builders/color_field.rb
@@ -55,6 +56,8 @@ files:
 - lib/actionview_attribute_builders/attribute_builders/range_field.rb
 - lib/actionview_attribute_builders/attribute_builders/search_field.rb
 - lib/actionview_attribute_builders/attribute_builders/select.rb
+- lib/actionview_attribute_builders/attribute_builders/submit.rb
+- lib/actionview_attribute_builders/attribute_builders/submittable.rb
 - lib/actionview_attribute_builders/attribute_builders/tel_field.rb
 - lib/actionview_attribute_builders/attribute_builders/text_area.rb
 - lib/actionview_attribute_builders/attribute_builders/text_field.rb