Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/airblade/template_form

Rails form builder using templates to define the HTML
https://github.com/airblade/template_form

form-builder rails

Last synced: 3 months ago
JSON representation

Rails form builder using templates to define the HTML

Awesome Lists containing this project

README 

        
# Template Form - a Rails form builder where you bring your own HTML



Template Form makes defining the HTML your form inputs generate as simple as possible: you just write it out.  Most other form builders, e.g. Simple Form, add a layer of indirection and make you use their own DSL.



Templates are namespaced so you can define different HTML for different situations, e.g. stacked or horizontal, in the same Rails app.



Right now Template Form includes templates for [Bulma](https://bulma.io/documentation/form/) because those are defined by Bulma.  For Tailwind, or Bootstrap, you define your inputs yourself.



Template Form works with all template engines supported by [Tilt](https://github.com/rtomayko/tilt).



### Installation



Add it to your Gemfile:



```

gem 'template_form'

```



And then `bundle install`.



### Example



Let's say you use Bulma.  Here's what your view might look like:



```erb

<%= template_form_with model: Post.new do |f| %>

  <%= f.input :title %>

  <%= f.input :body %>

<% end %>

```



This will be rendered as:



```html



  


    Title

    


      

    


  



  


    Title

    


      

    


  



```



Now let's say you want a horizontal form instead.  The only change you need to make is to specify the form type:



```diff

- <%= template_form_with model: Post.new do |f| %>

+ <%= template_form_with model: Post.new, form_type: :bulma_horizontal do |f| %>

```



And then you will get this HTML instead:



```html



  


    


      Title

    


    


      


        


          

        


      


    


  



  


    


      Body

    


    


      


        


          

        


      


    


  



```



### Defining your templates



Your templates live at `TemplateForm.template_path` which defaults to `/app/forms//` where `` is a name that makes sense to you, and the value that you use with the `:form_type` option to `#template_form_with`.



They should have these names:



- `text_input.html.erb`

- `textarea_input.html.erb`

- `select_input.html.erb`

- `grouped_select_input.html.erb`

- `checkbox_input.html.erb`

- `date_input.html.erb`



Use whatever extension goes with your template engine.



You can have several variations of a template, for example a [text input with inline add-on](https://tailwindui.com/components/application-ui/forms/input-groups#component-3620fb44e0a49ebce229526254018508).  First, write your template at `_.html.erb`; say, `text_input_inline_add_on.html.erb`.  Then use a `with: ` option in your view, e.g. `<%= form.input :name, with: :inline_add_on %>`.



Inside each template you can use the normal Rails form helpers.  Here's the template for Bulma's [text input](https://github.com/airblade/template_form/blob/master/lib/template_form/templates/bulma/text_input.html.erb):



```erb




  <% if has_label %>

    <%- label_options[:class] << ' label' %>

    <%- label_options[:class] << ' required' if options.delete(:required) %>

    <%= label attribute_name, label_text, label_options %>

  <% end %>



  


    <%- options[:class] << ' input' %>

    <%- options[:class] << ' is-danger' if errors[attribute_name].present? %>

    <%= text_field attribute_name, options %>

  



  <%- if hint_text.present? %>

    
<%= hint_text %>


  <%- end %>



  <%- if errors[attribute_name].present? %>

    
<%= errors.full_messages_for(attribute_name).to_sentence %>


  <%- end %>





```



The methods available inside the template are defined in the corresponding [models](https://github.com/airblade/template_form/blob/master/lib/template_form/)' `#render` method.  For example, here is the [text input](https://github.com/airblade/template_form/blob/c80b445a5a50e836635fd1bdf010d32f49902604/lib/template_form/base_input.rb#L28-L42)'s:



```ruby

def render

  template.render(

    builder,

    attribute_name: attribute_name,



    has_label:      has_label,

    label_text:     label_text,

    label_options:  label_options,



    hint_text:      hint_text,



    options:        options,

    errors:         errors

  ).html_safe

end

```



You also have access to the `view` in which the template is contained.  This is handy if you need to call methods on the view inside your template.  For example, translating values for data attributes.



```erb





```



### Attribute types and form inputs



Template Form looks up the type for the attribute, falling back to `:string` if it can't find one.  Then it uses the corresponding form input.



 Attribute type | Form input

--|--

 `:string` | `TextInput`

 `:text` | `TextareaInput`

 `:date` | `DateInput`

 `:boolean` | `CheckboxInput`

 `:file` | `FileInput`

 `:select` | `SelectInput`

 `:grouped_select` | `GroupedSelectInput`



You can specify a type to use with `:as`, e.g. `<%= f.input :reason, as: :text %>`.