headmin 0.2.8 → 0.3.4

data/app/views/headmin/forms/_base.html.erb

@@ -1,61 +1,114 @@
-<%
-  # headmin/forms/base
-  #
-  # ==== Options
-  # * <tt>append<tt> - Text or icon to be shown on the left hand side of the input, Doesn't work with float
-  # * <tt>attribute<tt> - Name of the attribute of the form model
-  # * <tt>float<tt> - Set to true if you want to show floating labels
-  # * <tt>form<tt> - Form object
-  # * <tt>label<tt> - Text to show as label. Label will be hidden if value is false
-  # * <tt>options<tt> - Hash with all HTML options to pass to
-  # * <tt>prepend<tt> - Text or icon to be shown on the right hand side of the input, Doesn't work with float
-  # * <tt>required<tt> - Set to true to mark as required
-  #
-  # ==== Examples
-  #   Basic version
-  #   <%= render 'headmin/forms/date', form: form, attribute: :title %#>
-  #
-  #   With datepicker
-  #   <%= render 'headmin/forms/text', form: form, attribute: :title, datepicker: true %#>
-
-  append = local_assigns.has_key?(:append) ? append : nil
-  prepend = local_assigns.has_key?(:prepend) ? prepend : nil
-  group = append || prepend
-  float = local_assigns.has_key?(:float) ? float : false
-  label = local_assigns.has_key?(:label) ? label : nil
-  required = local_assigns.has_key?(:required) ? required : false
-
-  show_label = label != false
-%>
-
-<div class="<%= 'form-floating' if float %> <%= ('mb-3 text-start' if show_label) %>">
-  <% if show_label && !float %>
-    <%= render 'headmin/forms/label', form: form, attribute: attribute, name: label, required: required %>
-  <% end %>
-
-  <% if group %>
+<!--
+<% documentation do %>
+  # Base
+  This serves as a wrapper around most form views. It allows defining everything that happens outside the input field.
+  The main purpose of this view is to coordinate labels and appendages.
+
+  ```erbx
+  <%= form_with do |form| %>
+    <%= render "headmin/forms/base", form: form, attribute: "basic_example" do |form| %>
+      <%= form.text_field("attribute", class: 'form-control') %>
+    <% end %>
+  <% end %>
+  ```
+
+  # Parameters
+  | Name         | Required | Type             | Description |
+  | ------------ | -------- | ---------------- | ----------- |
+  | form         | yes      | Object           | Form object |
+  | attribute    | yes      | String, Symbol   | Name of the attribute of the form model |
+  | append       | no       | Boolean          | Text or icon to be shown on the left hand side of the input, Doesn't work with float |
+  | class        | no       | String           | A space separated string of HTML class names |
+  | float        | no       | Boolean          | Set to true if you want to show floating labels |
+  | id           | no       | String           | Input identifier to be used as "for" in the label |
+  | label        | no       | Hash             | Text to show as label. Label will be hidden if value is false |
+  | prepend      | no       | Boolean          | Text or icon to be shown on the right hand side of the input, Doesn't work with float |
+
+  ## Examples
+
+  ### Sizing
+  ```erbx
+  <%= form_with do |form| %>
+    <%= render "headmin/forms/base", form: form, attribute: "small", class: 'input-group-sm' do |form| %>
+      <%= form.text_field("attribute", class: 'form-control', placeholder: '.input-group-sm') %>
+    <% end %>
+    <%= render "headmin/forms/base", form: form, attribute: "medium" do |form| %>
+      <%= form.text_field("attribute", class: 'form-control', placeholder: 'Default size') %>
+    <% end %>
+    <%= render "headmin/forms/base", form: form, attribute: "large", class: 'input-group-lg' do |form| %>
+      <%= form.text_field("attribute", class: 'form-control', placeholder: '.input-group-lg') %>
+    <% end %>
+  <% end %>
+  ```
+
+  ### Labels
+  ```erbx
+  <%= form_with do |form| %>
+    <%= render "headmin/forms/base", form: form, attribute: "no_label", label: false do |form| %>
+      <%= form.text_field("attribute", class: 'form-control', placeholder: 'Without label') %>
+    <% end %>
+    <%= render "headmin/forms/base", form: form, attribute: "floating_label", float: true do |form| %>
+      <%= form.text_field("attribute", class: 'form-control', placeholder: 'Default size') %>
+    <% end %>
+    <%= render "headmin/forms/base", form: form, attribute: "custom_label", label: 'Custom label' do |form| %>
+      <%= form.text_field("attribute", class: 'form-control') %>
+    <% end %>
+  <% end %>
+  ```
+
+  ### Appendages
+  ```erbx
+  <%= form_with do |form| %>
+    <%= render "headmin/forms/base", form: form, attribute: "prepend", prepend: "€" do |form| %>
+      <%= form.text_field("attribute", class: 'form-control') %>
+    <% end %>
+    <%= render "headmin/forms/base", form: form, attribute: "append", append: "m²" do |form| %>
+      <%= form.text_field("attribute", class: 'form-control') %>
+    <% end %>
+    <%= render "headmin/forms/base", form: form, attribute: "prepend_and_append", prepend: "€", append: "m²" do |form| %>
+      <%= form.text_field("attribute", class: 'form-control') %>
+    <% end %>
+  <% end %>
+  ```
+<% end %>
+-->
+
+<% base = Headmin::Form::Base.new(local_assigns) %>
+
+<%= tag.div(class: base.class_names, data: base.data) do %>
+  <% if base.label != false && !base.float %>
+    <%= render 'headmin/forms/label', base.label_options %>
+  <% end %>
+
+  <% if base.append || base.prepend %>
     <div class="input-group w-100">
-      <% if prepend %>
+      <% if base.prepend %>
       <span class="input-group-text">
-        <%= prepend %>
+        <%= base.prepend %>
       </span>
       <% end %>
 
       <%= yield form %>
-      <%= render 'headmin/forms/validation', form: form, attribute: attribute if form.object.respond_to?(:errors) %>
+      <%= render 'headmin/forms/validation', base.validation_options if form.object.respond_to?(:errors) %>
 
-      <% if append %>
+      <% if base.append %>
       <span class="input-group-text">
-        <%= append %>
+        <%= base.append %>
       </span>
       <% end %>
     </div>
   <% else %>
     <%= yield form %>
-    <%= render 'headmin/forms/validation', form: form, attribute: attribute if form.object.respond_to?(:errors) %>
+    <%= render 'headmin/forms/validation', base.validation_options if form.object.respond_to?(:errors) %>
+  <% end %>
+
+  <% if base.label != false && base.float %>
+    <%= render 'headmin/forms/label', base.label_options %>
   <% end %>
 
-  <% if show_label && float %>
-    <%= render 'headmin/forms/label', form: form, attribute: attribute, name: label, required: required %>
+  <% if base.list %>
+    <datalist id="<%= base.list_id %>">
+      <%= options_for_select(base.list) %>
+    </datalist>
   <% end %>
-</div>
+<% end %>

data/app/views/headmin/forms/_blocks.html.erb

@@ -2,9 +2,9 @@
   # headmin/forms/blocks
   #
   # ==== Options
-  # * <tt>form</tt> - Form object
-  # * <tt>path</tt> - Directory where to look for block templates
-  # * <tt>allow</tt> - Names of block templates that can be added
+  # * +form</tt> - Form object
+  # * +path</tt> - Directory where to look for block templates
+  # * +allow</tt> - Names of block templates that can be added
   #
   # ==== Examples
   #   Basic version. This will only look for blocks in 'admin/blocks'
@@ -29,7 +29,7 @@
   <%= block_form.hidden_field :name, value: name %>
 
   <!-- Render block form fields -->
-  <% view_path = BlockService.form_view(name, path: path).gsub('/_', '/') %>
+  <% view_path = BlockService.form_view(name, path: path).gsub('/_', '/').split('.')[0] %>
   <%= render view_path, form: block_form %>
 
   <!-- Label -->

data/app/views/headmin/forms/_checkbox.html.erb

@@ -2,9 +2,9 @@
   # headmin/forms/checkbox
   #
   # ==== Options
-  # * <tt>form<tt> - Form object
-  # * <tt>attribute<tt> - Name of the attribute of the form model
-  # * <tt>label<tt> - Text to show as label. Label will be hidden if value is false
+  # * +form+ - Form object
+  # * +attribute+ - Name of the attribute of the form model
+  # * +label+ - Text to show as label. Label will be hidden if value is false
   #
   # ==== Examples
   #   Basic version
@@ -33,7 +33,7 @@
 <div class="<%= ('mb-3 text-start' if show_label) %>">
   <%= form.check_box(attribute, options) %>
   <% if show_label %>
-    <%= render 'headmin/forms/label', form: form, attribute: attribute, name: label, required: required %>
+    <%= render 'headmin/forms/label', form: form, attribute: attribute, text: label, required: required %>
   <% end %>
   <%= render 'headmin/forms/validation', form: form, attribute: attribute %>
 </div>

data/app/views/headmin/forms/_date.html.erb

@@ -1,57 +1,41 @@
 <%
   # headmin/forms/date
   #
-  # ==== Options
-  # * <tt>append<tt> - Text or icon to be shown on the left hand side of the input, Doesn't work with float
-  # * <tt>attribute<tt> - Name of the attribute of the form model
-  # * <tt>class<tt> - Optional HTML class attribute
-  # * <tt>data<tt> - Optional HTML data attributes
-  # * <tt>disabled<tt> - Set to true if the input should be shown as disabled
-  # * <tt>float<tt> - Set to true if you want to show floating labels
-  # * <tt>form<tt> - Form object
-  # * <tt>label<tt> - Text to show as label. Label will be hidden if value is false
-  # * <tt>name<tt> - The name of the field
-  # * <tt>prepend<tt> - Text or icon to be shown on the right hand side of the input, Doesn't work with float
-  # * <tt>readonly<tt> - Set to true if the value of the field can only be read and not be modified
-  # * <tt>required<tt> - Set to true to show a HTML5 validation message when left blank
+  # ==== Required parameters
+  # * +form+ - Form object
+  # * +attribute+ - Name of the attribute of the form model
+  #
+  # ==== Optional parameters
+  # * +aria+ - Provide a hash to define all aria attributes
+  # * +autocomplete+ - Value to be autofilled by the browser
+  # * +autofocus+ - Set to true to focus on this field when the page renders
+  # * +data+ - Optional HTML data attributes
+  # * +disabled+ - Set to true if the input should be shown as disabled
+  # * +id+ - Input identifier
+  # * +list+ - Add array of options to show in a data list
+  # * +readonly+ - Set to true if the value of the field can only be read and not be modified
+  # * +required+ - Set to true to mark as required
+  # * +step+ - The acceptable value granularity
+  # * +value+ - Overrides the value of the form
+  #
+  # ==== Extra parameters
+  # Listed in 'headmin/forms/base'
+  #
+  # ==== References
+  # https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/date
+  # https://apidock.com/rails/ActionView/Helpers/FormHelper/date_field
   #
   # ==== Examples
   #   Basic version
   #   <%= render 'headmin/forms/date', form: form, attribute: :date %#>
 
-  append = local_assigns.has_key?(:append) ? append : nil
-  class_names = local_assigns.has_key?(:class) ? local_assigns[:class] : false
-  data = local_assigns.has_key?(:data) ? data : nil
-  disabled = local_assigns.has_key?(:disabled) ? disabled : false
-  float = local_assigns.has_key?(:float) ? float : false
-  label = local_assigns.has_key?(:label) ? label : nil
-  prepend = local_assigns.has_key?(:prepend) ? prepend : nil
-  readonly = local_assigns.has_key?(:readonly) ? readonly : false
-  required = local_assigns.has_key?(:required) ? required : false
-
-  options = {
-    'aria-describedby': form_field_validation_id(form, attribute),
-    class: "form-control #{form_field_validation_class(form, attribute)} #{class_names}",
-    data: data,
-    disabled: disabled,
-    placeholder: label ? label.to_s.humanize : nil,
-    readonly: readonly,
-    required: required,
-  }
-
-  options[:name] = name if local_assigns.has_key?(:name)
-
-  template_locals = {
-    append: append,
-    attribute: attribute,
-    float: float,
-    form: form,
-    label: label,
-    prepend: prepend,
-    required: required
-  }
+  option_keys = %i(aria autocomplete autofocus data disabled id list readonly required step value)
+  options = local_assigns.slice(*option_keys).merge(
+    aria: { describedby: form_field_validation_id(form, attribute) },
+    class: ['form-control', form_field_validation_class(form, attribute)].join(' '),
+  )
 %>
 
-<%= render 'headmin/forms/base', template_locals do |form| %>
+<%= render 'headmin/forms/base', local_assigns do |form| %>
   <%= form.date_field(attribute, options) %>
 <% end %>

data/app/views/headmin/forms/_date_range.html.erb

@@ -1,21 +1,18 @@
 <%
   # headmin/forms/date_range
   #
-  # ==== Options
-  # * <tt>append<tt> - Text or icon to be shown on the left hand side of the input, Doesn't work with float
-  # * <tt>class<tt> - Optional HTML class attribute
-  # * <tt>data<tt> - Optional HTML data attributes
-  # * <tt>end_attribute<tt> - Name of the end date attribute of the form model
-  # * <tt>end_label<tt> - Label for the end attribute
-  # * <tt>float<tt> - Set to true if you want to show floating labels
-  # * <tt>form<tt> - Form object
-  # * <tt>label<tt> - Text to show as label. Label will be hidden if value is false
-  # * <tt>prepend<tt> - Text or icon to be shown on the right hand side of the input, Doesn't work with float
-  # * <tt>readonly<tt> - Set to true if the value of the field can only be read and not be modified
-  # * <tt>required<tt> - Set to true to show a HTML5 validation message when left blank
-  # * <tt>single<tt> - Set to true if only one field should be displayed
-  # * <tt>start_attribute<tt> - Name of the start date attribute of the form model
-  # * <tt>start_label<tt> - Label for the start attribute
+  # ==== Required parameters
+  # * +form+ - Form object
+  # * +start_attribute+ - Name of the start date attribute of the form model
+  # * +end_attribute+ - Name of the end date attribute of the form model
+  #
+  # ==== Optional parameters
+  # * +end_label+ - Label for the end attribute
+  # * +start_label+ - Label for the start attribute
+  #
+  # ==== Extra parameters
+  # Listed in 'headmin/forms/date'
+  # Listed in 'headmin/forms/base'
   #
   # ==== Examples
   #   Basic version
@@ -24,61 +21,22 @@
   #   With custom labels
   #   <%= render 'headmin/forms/date_range', form: form, start_attribute: :start_date_2, start_label: :start_date, end_attribute: :end_date_2, end_label: :end_date %#>
 
-  append = local_assigns.has_key?(:append) ? append : nil
-  class_names = local_assigns.has_key?(:class) ? local_assigns[:class] : false
-  data = local_assigns.has_key?(:data) ? data : {}
-  disabled = local_assigns.has_key?(:disabled) ? disabled : false
-  end_attribute = local_assigns.has_key?(:end_attribute) ? end_attribute : nil
-  end_label = local_assigns.has_key?(:end_label) ? end_label : nil
-  float = local_assigns.has_key?(:float) ? float : false
-  label = local_assigns.has_key?(:label) ? label : nil
-  prepend = local_assigns.has_key?(:prepend) ? prepend : nil
-  readonly = local_assigns.has_key?(:readonly) ? readonly : false
-  required = local_assigns.has_key?(:required) ? required : false
-  start_attribute = local_assigns.has_key?(:start_attribute) ? start_attribute : nil
-  start_label = local_assigns.has_key?(:start_label) ? start_label : nil
-  single = local_assigns.has_key?(:single) ? single : false
-
-  template_locals = {
-    form: form,
-    append: append,
-    prepend: prepend,
-    float: float,
-    label: label,
-    class: class_names,
-    data: data.merge(action: 'change->date-range#update'),
-    disabled: disabled,
-    readonly: readonly,
-    required: required
-  }
-
-  start_template_locals = template_locals.merge(
-    attribute: start_attribute,
-    placeholder: start_attribute,
-    label: start_label
+  start_date_options = local_assigns.merge(
+    attribute: local_assigns[:start_attribute],
+    label: local_assigns[:start_label]
   )
-
-  end_template_locals = template_locals.merge(
-    attribute: end_attribute,
-    placeholder: end_attribute,
-    label: end_label
+  end_date_options = local_assigns.merge(
+    attribute: local_assigns[:end_attribute],
+    label: local_assigns[:end_label]
   )
 %>
 
-<% if single %>
-  <div data-controller="date-range">
-    <%= render 'headmin/forms/hidden', start_template_locals.merge(class: nil, data: { 'date-range-target': 'startDateInput' }) %>
-    <%= render 'headmin/forms/hidden', end_template_locals.merge(class: nil, data: { 'date-range-target': 'endDateInput' }) %>
-    <%= render 'headmin/forms/date', template_locals.merge(attribute: :date, name: nil) %>
+<div class="row">
+  <div class="col">
+    <%= render 'headmin/forms/date', start_date_options %>
   </div>
-<% else %>
-  <div class="row">
-    <div class="col">
-      <%= render 'headmin/forms/date', start_template_locals %>
-    </div>
-    <div class="col">
-      <%= render 'headmin/forms/date', end_template_locals %>
-    </div>
+  <div class="col">
+    <%= render 'headmin/forms/date', end_date_options %>
   </div>
-<% end %>
+</div>
 

data/app/views/headmin/forms/_email.html.erb

@@ -1,39 +1,48 @@
 <%
   # headmin/forms/email
   #
-  # ==== Options
-  # * <tt>form<tt> - Form object
-  # * <tt>attribute<tt> - Name of the attribute of the form model
-  # * <tt>label<tt> - Text to show as label. Label will be hidden if value is false
-  # * <tt>float<tt> - Set to true if you want to show floating labels
-  # * <tt>append<tt> - Text or icon to be shown on the left hand side of the input, Doesn't work with float
-  # * <tt>prepend<tt> - Text or icon to be shown on the right hand side of the input, Doesn't work with float
+  # ==== Required parameters
+  # * +form+ - Form object
+  # * +attribute+ - Name of the attribute of the form model
+  #
+  # ==== Optional parameters
+  # * +aria+ - Provide a hash to define all aria attributes
+  # * +autocomplete+ - Value to be autofilled by the browser
+  # * +data+ - Provide a hash to define all data attributes
+  # * +disabled+ - Sets the placeholder of the field
+  # * +id+ - Input identifier
+  # * +list+ - Add array of options to show in a data list
+  # * +maxlength+ - Maximum amount of characters to be used
+  # * +minlength+ - Minimum amount of characters to be used
+  # * +multiple+ - Allow multiple comma-separated email addresses to be entered
+  # * +pattern+ -a  A regular expression that the input's value must match
+  # * +placeholder+ - Sets the placeholder of the field
+  # * +readonly+ - Sets the placeholder of the field
+  # * +required+ - Set to true to mark as required
+  # * +size+ - How much of the input should be shown
+  # * +value+ - Overrides the value of the form
+  #
+  # ==== Extra parameters
+  # Listed in 'headmin/forms/base'
+  #
+  # ==== References
+  # https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/text
+  # https://apidock.com/rails/ActionView/Helpers/FormHelper/text_field
   #
   # ==== Examples
   #   Basic version
   #   <%= render 'headmin/forms/email', form: form, attribute: :email_address %#>
 
-  append = local_assigns.has_key?(:append) ? append : nil
-  class_names = local_assigns.has_key?(:class) ? local_assigns[:class] : false
-  data = local_assigns.has_key?(:data) ? data : nil
-  disabled = local_assigns.has_key?(:disabled) ? disabled : false
-  float = local_assigns.has_key?(:float) ? float : false
-  label = local_assigns.has_key?(:label) ? label : nil
-  prepend = local_assigns.has_key?(:prepend) ? prepend : nil
-  readonly = local_assigns.has_key?(:readonly) ? readonly : false
-  required = local_assigns.has_key?(:required) ? required : false
+  placeholder = local_assigns[:float] ? local_assigns[:placeholder] || attribute : local_assigns[:placeholder]
 
-  options = {
-    'aria-describedby': form_field_validation_id(form, attribute),
-    class: "form-control #{form_field_validation_class(form, attribute)} #{class_names}",
-    data: data,
-    disabled: disabled,
-    placeholder: attribute,
-    readonly: readonly,
-    required: required,
-  }
+  option_keys = %i(aria autocomplete data disabled id maxlenght minlength multiple pattern placeholder readonly required size value)
+  options = local_assigns.slice(*option_keys).merge(
+    aria: { describedby: form_field_validation_id(form, attribute) },
+    class: ['form-control', form_field_validation_class(form, attribute)].join(' '),
+    placeholder: placeholder
+  )
 %>
 
-<%= render 'headmin/forms/base', form: form, attribute: attribute, append: append, prepend: prepend, float: float, label: label, required: required do |form| %>
+<%= render 'headmin/forms/base', local_assigns do |form| %>
   <%= form.email_field(attribute, options) %>
 <% end %>