formular 0.2.0

data/lib/formular/element/modules/collection.rb

@@ -0,0 +1,17 @@
+require 'formular/element/module'
+module Formular
+  class Element
+    module Modules
+      # This module adds the relevant option keys and defaults
+      # for elements that support collections
+      module Collection
+        include Formular::Element::Module
+
+        add_option_keys :collection, :label_method, :value_method
+
+        set_default :label_method, 'first'
+        set_default :value_method, 'last'
+      end
+    end
+  end
+end

data/lib/formular/element/modules/container.rb

@@ -0,0 +1,60 @@
+require 'formular/element/module'
+module Formular
+  class Element
+    module Modules
+      # this module is used for element that contain something
+      # e.g. <label>Label Words</label>
+      # it is designed to accept content as a string (via the :content option)
+      # or as a block
+      # Alternatively you can produce blockless content by making use of the
+      # #start and #end methods e.g.
+      #
+      # element = Container.()
+      # element.start
+      # add your own content
+      # element.end
+      module Container
+        include Formular::Element::Module
+
+        add_option_keys :content
+
+        html do |element|
+          concat start_tag
+          concat element.content
+          concat end_tag
+        end
+
+        html(:start) { start_tag }
+
+        html(:end) { end_tag }
+
+        module InstanceMethods
+          def content
+            @block ? HtmlBlock.new(self, @block).call : options[:content].to_s
+          end
+
+          def has_content?
+            @block || options[:content]
+          end
+
+          def end
+            to_html(context: :end)
+          end
+
+          def start
+            to_html(context: :start)
+          end
+
+          # Delegate missing methods to the builder
+          # TODO:: @apotonick is going to do something fancy here to delegate
+          # the builder methods rather then using this method missing.
+          def method_missing(method, *args, &block)
+            return super unless builder
+
+            builder.send(method, *args, &block)
+          end
+        end # module InstanceMethods
+      end # module Container
+    end # module Modules
+  end # class Element
+end # module Formular

data/lib/formular/element/modules/control.rb

@@ -0,0 +1,42 @@
+require 'formular/element/module'
+module Formular
+  class Element
+    module Modules
+      # include this module in an element to set the id,
+      # name & value based on the attribute name
+      module Control
+        include Formular::Element::Module
+
+        add_option_keys :attribute_name
+
+        set_default :name, :form_encoded_name
+        set_default :id, :form_encoded_id
+        set_default :value, :reader_value
+
+        module InstanceMethods
+          def attribute_name
+            options[:attribute_name]
+          end
+
+          private
+
+          def path
+            @path ||= builder.path(attribute_name) if attribute_name && builder
+          end
+
+          def form_encoded_name
+            path.to_encoded_name if path
+          end
+
+          def form_encoded_id
+            path.to_encoded_id if path
+          end
+
+          def reader_value
+            builder.reader_value(attribute_name) if attribute_name && builder
+          end
+        end # model InstanceMethods
+      end # module Control
+    end # module Modules
+  end # class Element
+end # module Formular

data/lib/formular/element/modules/error.rb

@@ -0,0 +1,48 @@
+require 'formular/element/module'
+module Formular
+  class Element
+    module Modules
+      # this module provides error methods and options to a control when included
+      module Error
+        include Formular::Element::Module
+        add_option_keys :error
+
+        # options functionality (same as SimpleForm):
+        # options[:error] == false NO ERROR regardless of model errors
+        # options[:error] == String return the string, regardless of model errors
+        module InstanceMethods
+          def error_text
+            has_custom_error? ? options[:error] : errors_on_attribute.send(error_method) if has_errors?
+          end
+
+          def has_errors?
+            options[:error] != false && (has_custom_error? || has_attribute_errors?)
+          end
+
+          protected
+
+          # attribute_errors is an array, what method should we use to return a
+          # string? (:first, :last, :join etc.)
+          # ideally this should be configurable via the builder...
+          def error_method
+            :first
+          end
+
+          # I bet we could clean this up alot but it needs to be flexible
+          # enough not to error with nils
+          def has_attribute_errors?
+            builder != nil && builder.errors != nil && errors_on_attribute != nil && errors_on_attribute.size > 0
+          end
+
+          def has_custom_error?
+            options[:error].is_a?(String)
+          end
+
+          def errors_on_attribute
+            @errors ||= builder.errors[options[:attribute_name]]
+          end
+        end # module InstanceMethods
+      end # module Error
+    end # module Modules
+  end # class Element
+end # module Formular

data/lib/formular/element/modules/hint.rb

@@ -0,0 +1,36 @@
+require 'formular/element/module'
+module Formular
+  class Element
+    module Modules
+      # this module provides hints to a control when included.
+      module Hint
+        include Formular::Element::Module
+        add_option_keys :hint, :hint_options
+
+        # options functionality (same as SimpleForm):
+        # options[:hint] == String return the string
+        module InstanceMethods
+          def hint_text
+            options[:hint] if has_hint?
+          end
+
+          def has_hint?
+            options[:hint].is_a?(String)
+          end
+
+          private
+          def hint_id
+            return hint_options[:id] if hint_options[:id]
+
+            id = attributes[:id] || form_encoded_id
+            "#{id}_hint" if id
+          end
+
+          def hint_options
+            @hint_options ||= Attributes[options[:hint_options]]
+          end
+        end # module InstanceMethods
+      end # module Hint
+    end # module Modules
+  end # class Element
+end # module Formular

data/lib/formular/element/modules/label.rb

@@ -0,0 +1,30 @@
+require 'formular/element/module'
+module Formular
+  class Element
+    module Modules
+      # this module provides label options and methods to a control when included.
+      module Label
+        include Formular::Element::Module
+        add_option_keys :label, :label_options
+
+        # options functionality:
+        # options[:label] == String return the string
+        # currently we don't infer label text so if you don't include
+        # label as an option, you wont get one rendered
+        module InstanceMethods
+          def label_text
+            options[:label]
+          end
+
+          def has_label?
+            !label_text.nil? && label_text != false
+          end
+
+          def label_options
+            @label_options ||= Attributes[options[:label_options]]
+          end
+        end # module InstanceMethods
+      end # module Label
+    end # module Modules
+  end # class Element
+end # module Formular

data/lib/formular/element/modules/wrapped_control.rb

@@ -0,0 +1,73 @@
+require 'formular/element/module'
+require 'formular/element/modules/control'
+require 'formular/element/modules/hint'
+require 'formular/element/modules/error'
+require 'formular/element/modules/label'
+module Formular
+  class Element
+    module Modules
+      # include this module to enable an element to render the entire wrapped input
+      # e.g. wrapper{label+control+hint+error}
+      module WrappedControl
+        include Formular::Element::Module
+        include Control
+        include Hint
+        include Error
+        include Label
+
+        add_option_keys :error_options, :wrapper_options
+        set_default :aria_describedby, :hint_id, if: :has_hint?
+
+        self.html_context = :wrapped
+
+        html(:wrapped) do |input|
+          input.wrapper do
+            concat input.label
+            concat input.to_html(context: :default)
+            concat input.hint
+            concat input.error
+          end
+        end
+
+        module InstanceMethods
+          def wrapper(&block)
+            wrapper_element = has_errors? ? :error_wrapper : :wrapper
+            builder.send(wrapper_element, Attributes[options[:wrapper_options]], &block)
+          end
+
+          def label
+            return '' unless has_label?
+
+            label_options[:content] = label_text
+            label_options[:labeled_control] = self
+            builder.label(label_options).to_s
+          end
+
+          def error
+            return '' unless has_errors?
+
+            error_options[:content] = error_text
+            builder.error(error_options).to_s
+          end
+
+          def hint
+            return '' unless has_hint?
+
+            hint_options[:content] = hint_text
+            hint_options[:id] ||= hint_id
+            builder.hint(hint_options).to_s
+          end
+
+          private
+          def error_options
+            @error_options ||= Attributes[options[:error_options]]
+          end
+
+          def wrapper_options
+            @wrapper_options ||= Attributes[options[:wrapper_options]]
+          end
+        end # module InstanceMethods
+      end # module WrappedControl
+    end # module Modules
+  end # class Element
+end # module Formular

data/lib/formular/elements.rb

@@ -0,0 +1,295 @@
+require 'formular/element'
+require 'formular/element/module'
+require 'formular/element/modules/container'
+require 'formular/element/modules/wrapped_control'
+require 'formular/element/modules/control'
+require 'formular/element/modules/checkable'
+require 'formular/element/modules/error'
+
+module Formular
+  class Element
+    # These three are really just provided for convenience when creating other elements
+    Container = Class.new(Formular::Element) { include Formular::Element::Modules::Container }
+    Control = Class.new(Formular::Element) { include Formular::Element::Modules::Control }
+    WrappedControl = Class.new(Formular::Element) { include Formular::Element::Modules::WrappedControl }
+
+    # define some base classes to build from or easily use elsewhere
+    Option = Class.new(Container) { tag :option }
+    OptGroup = Class.new(Container) { tag :optgroup }
+    Fieldset = Class.new(Container) { tag :fieldset }
+    Legend = Class.new(Container) { tag :legend }
+    Div = Class.new(Container) { tag :div }
+    P = Class.new(Container) { tag :p }
+    Span = Class.new(Container) { tag :span }
+    Small = Class.new(Container) { tag :small }
+
+    class Hidden < Control
+      tag :input
+      set_default :type, 'hidden'
+
+      html { closed_start_tag }
+    end
+
+    class Form < Container
+      tag :form
+
+      add_option_keys :enforce_utf8, :csrf_token, :csrf_token_name
+
+      set_default :method, 'post'
+      set_default :accept_charset, 'utf-8'
+      set_default :enforce_utf8, true
+
+      html(:start) do |form|
+        hidden_tags = element.extra_hidden_tags
+        concat start_tag
+        concat hidden_tags
+      end
+
+      html do |form|
+        concat form.to_html(context: :start)
+        concat form.content
+        concat end_tag
+      end
+
+      def extra_hidden_tags
+        token_tag + utf8_enforcer_tag + method_tag
+      end
+
+      private
+
+      def token_tag
+        return '' unless options[:csrf_token].is_a? String
+
+        name = options[:csrf_token_name] || '_csrf_token'
+
+        Hidden.(value: options[:csrf_token], name: name).to_s
+      end
+
+      def utf8_enforcer_tag
+        return '' unless options[:enforce_utf8]
+
+        # Use raw HTML to ensure the value is written as an HTML entity; it
+        # needs to be the right character regardless of which encoding the
+        # browser infers.
+        %(<input name="utf8" type="hidden" value="✓"/>)
+      end
+
+      # because this mutates attributes, we have to call this before rendering the start_tag
+      def method_tag
+        method = attributes[:method]
+
+        case method
+        when /^get$/ # must be case-insensitive, but can't use downcase as might be nil
+          attributes[:method] = 'get'
+          ''
+        when /^post$/, '', nil
+          attributes[:method] = 'post'
+          ''
+        else
+          attributes[:method] = 'post'
+          Hidden.(value: method, name: '_method').to_s
+        end
+      end
+    end
+
+    class ErrorNotification < Formular::Element
+      tag :div
+      add_option_keys :message
+
+      html do |element|
+        if element.builder_errors?
+          concat start_tag
+          concat element.error_message
+          concat end_tag
+        else
+          ''
+        end
+      end
+
+      def error_message
+        options[:message] || 'Please review the problems below:'
+      end
+
+      def builder_errors?
+        return false if builder.nil?
+        !builder.errors.empty?
+      end
+    end
+
+    class Error < P
+      include Formular::Element::Modules::Error
+      add_option_keys :attribute_name
+      set_default :content, :error_text
+    end # class Error
+
+    class Textarea < Control
+      include Formular::Element::Modules::Container
+      tag :textarea
+      add_option_keys :value
+
+      def content
+        options[:value] || super
+      end
+    end # class Textarea
+
+    class Label < Container
+      tag :label
+      add_option_keys :labeled_control, :attribute_name
+      set_default :for, :labeled_control_id
+
+      # as per MDN A label element can have both a 'for' attribute and a contained control element,
+      # as long as the for attribute points to the contained control element.
+      def labeled_control_id
+        return options[:labeled_control].attributes[:id] if options[:labeled_control]
+        return builder.path(options[:attribute_name]).to_encoded_id if options[:attribute_name] && builder
+      end
+    end # class Label
+
+    class Submit < Formular::Element
+      tag :input
+
+      set_default :type, 'submit'
+
+      html { closed_start_tag }
+    end # class Submit
+
+    class Button < Formular::Element::Container
+      tag :button
+      add_option_keys :value
+
+      def content
+        options[:value] || super
+      end
+    end # class Button
+
+    class Input < Control
+      tag :input
+      set_default :type, 'text'
+      html { closed_start_tag }
+    end # class Input
+
+    class Select < Control
+      include Formular::Element::Modules::Collection
+      tag :select
+
+      add_option_keys :value
+
+      html do |input|
+        concat start_tag
+        concat input.option_tags
+        concat end_tag
+      end
+
+      # convert the collection array into option tags also supports option groups
+      # when the array is nested
+      # example 1:
+      # [[1,"True"], [0,"False"]] =>
+      # <option value="1">true</option><option value="0">false</option>
+      # example 2:
+      # [
+      #   ["Genders", [["m", "Male"], ["f", "Female"]]],
+      #   ["Booleans", [[1,"true"], [0,"false"]]]
+      # ] =>
+      # <optgroup label="Genders">
+      #  <option value="m">Male</option>
+      #  <option value="f">Female</option>
+      # </optgroup>
+      # <optgroup label="Booleans">
+      #   <option value="1">true</option>
+      #   <option value="0">false</option>
+      # </optgroup>
+      def option_tags
+        collection_to_options(options[:collection])
+      end
+
+      private
+
+      def collection_to_options(collection)
+        collection.map do |item|
+          if item.last.is_a?(Array)
+            opts = { label: item.first, content: collection_to_options(item.last) }
+
+            Formular::Element::OptGroup.new(opts).to_s
+          else
+            item_to_option(item)
+          end
+        end.join ''
+      end
+
+      def item_to_option(item)
+        opts = if item.is_a?(Array) && item.size > 2
+                 item.pop
+               else
+                 {}
+               end
+
+        opts[:value] = item.send(options[:value_method])
+        opts[:content] = item.send(options[:label_method])
+        opts[:selected] = 'selected' if opts[:value] == options[:value]
+
+        Formular::Element::Option.new(opts).to_s
+      end
+    end # class Select
+
+    class Checkbox < Control
+      tag :input
+
+      add_option_keys :unchecked_value, :include_hidden, :multiple
+
+      set_default :type, 'checkbox'
+      set_default :unchecked_value, :default_unchecked_value
+      set_default :value, '1' # instead of reader value
+      set_default :include_hidden, true
+
+      include Formular::Element::Modules::Checkable
+
+      html do |element|
+        if element.collection?
+          element.to_html(context: :with_collection)
+        else
+          concat element.hidden_tag
+          concat closed_start_tag
+        end
+      end
+
+      html(:with_collection) do |element|
+        concat element.to_html(context: :collection)
+        concat element.hidden_tag
+      end
+
+      def hidden_tag
+        return '' unless options[:include_hidden]
+
+        Hidden.(value: options[:unchecked_value], name: attributes[:name]).to_s
+      end
+
+      private
+
+      def default_unchecked_value
+        collection? ? '' : '0'
+      end
+
+      # only append the [] to name if part of a collection, or the multiple option is set
+      def form_encoded_name
+        return unless path
+
+        options[:multiple] || options[:collection] ? super + '[]' : super
+      end
+
+      def collection_base_options
+        super.merge(include_hidden: false)
+      end
+    end # class Checkbox
+
+    class Radio < Control
+      tag :input
+
+      set_default :type, 'radio'
+      set_default :value, nil # instead of reader value
+
+      include Formular::Element::Modules::Checkable
+
+      html { closed_start_tag }
+    end # class Radio
+  end # class Element
+end # module Formular