bootstrap_form
v5.4.0
bootstrap_form es un creador de formularios Rails que hace que sea muy fácil integrar formularios estilo Bootstrap v5 en su aplicación Rails. Proporciona ayudas de formulario que aumentan los ayudantes de forma de Rails. Los ayudantes de formulario de bootstrap_forms generan el campo del formulario y su etiqueta y todo el marcado de Bootstrap necesario para una visualización adecuada de Bootstrap. bootstrap_form también proporciona:
bootstrap_form y hacerlo usted mismo. Tenga en cuenta que esto se aplica a los mensajes de validación generados por Rails. La validación del lado del cliente HTML 5 y la validación de Rails lista para usar realmente no funcionan bien juntas. Una discusión sobre los desafíos y algunas soluciones está aquí.required en los campos obligatorios.bootstrap_form no puede hacer. Algunas otras cosas interesantes que bootstrap_form hace por ti son:
.erb . bootstrap_form funciona como los asistentes de formulario estándar de Rails, y este README asume que sabes cómo funcionan. Comienza un formulario con uno de bootstrap_form_with , bootstrap_form_for o bootstrap_form_tag en un archivo de vista. Obtiene un creador de formularios que llama a los ayudantes bootstrap_form en lugar de a los ayudantes estándar de Rails. Utilice ese creador de formularios en el archivo de vista para representar uno o más campos de formulario.
bootstrap_form admite como mínimo las versiones actualmente admitidas de Ruby y Rails:
Instale Bootstrap 5. Hay muchas formas de hacerlo, según la canalización de activos que esté utilizando en su aplicación Rails. Una forma es utilizar la gema que funciona con Sprockets. Para hacerlo, en una nueva aplicación Rails 7.0+ creada sin la opción --webpacker , agregue la gema bootstrap a su Gemfile :
gem "bootstrap" , "~> 5.0" Y siga las instrucciones restantes en la guía oficial de instalación de bootstrap para configurar application.scss y application.js .
Agrega la gema bootstrap_form a tu Gemfile :
gem "bootstrap_form" , "~> 5.4"Entonces:
bundle install
Dependiendo del preprocesador CSS que esté utilizando, agregar los estilos de formulario de arranque difiere ligeramente. Si usa Rails en el modo predeterminado sin ningún preprocesador, deberá agregar la siguiente línea a su archivo application.css :
* = require rails_bootstrap_forms Si siguió la guía oficial de instalación de bootstrap, probablemente habrá cambiado a SCSS. En este caso agregue la siguiente línea a su application.scss :
@import " rails_bootstrap_forms.css " ; Para comenzar, use el asistente bootstrap_form_for en lugar del asistente Rails form_for . He aquí un ejemplo:
<%= bootstrap_form_for(@user) do |f| %>
<%= f.email_field :email %>
<%= f.password_field :password %>
<%= f.check_box :remember_me %>
<%= f.submit "Log In" %>
<% end %> Esto genera el siguiente HTML:
< form accept-charset =" UTF-8 " action =" /users " class =" new_user " id =" new_user " method =" post " >
< div class =" mb-3 " >
< label class =" form-label required " for =" user_email " > Email </ label >
< input class =" form-control " id =" user_email " name =" user[email] " required =" required " type =" email " value =" [email protected] " >
</ div >
< div class =" mb-3 " >
< label class =" form-label " for =" user_password " > Password </ label >
< input class =" form-control " id =" user_password " name =" user[password] " type =" password " >
</ div >
< div class =" form-check mb-3 " >
< input autocomplete =" off " name =" user[remember_me] " type =" hidden " value =" 0 " >
< input class =" form-check-input " id =" user_remember_me " name =" user[remember_me] " type =" checkbox " value =" 1 " >
< label class =" form-check-label " for =" user_remember_me " > Remember me </ label >
</ div >
< input class =" btn btn-secondary " data-disable-with =" Log In " name =" commit " type =" submit " value =" Log In " >
</ form > Si su formulario no está respaldado por un modelo, use bootstrap_form_tag . El uso de este asistente es el mismo que bootstrap_form_for , excepto que no se pasa ningún objeto modelo como primer argumento. He aquí un ejemplo:
<%= bootstrap_form_tag url: '/subscribe' do |f| %>
<%= f.email_field :email, value: '[email protected]' %>
<%= f.submit %>
<% end %>Esto genera:
< form accept-charset =" UTF-8 " action =" /subscribe " method =" post " >
< div class =" mb-3 " >
< label class =" form-label " for =" email " > Email </ label >
< input class =" form-control " id =" email " name =" email " type =" email " value =" [email protected] " >
</ div >
< input class =" btn btn-secondary " data-disable-with =" Save " name =" commit " type =" submit " value =" Save " >
</ form > Para comenzar, simplemente use el asistente bootstrap_form_with en lugar de form_with . He aquí un ejemplo:
<%= bootstrap_form_with(model: @user, local: true) do |f| %>
<%= f.email_field :email %>
<%= f.password_field :password, help: 'A good password should be at least six characters long' %>
<%= f.check_box :remember_me %>
<%= f.submit "Log In" %>
<% end %> Esto genera:
< form accept-charset =" UTF-8 " action =" /users " method =" post " >
< div class =" mb-3 " >
< label class =" form-label required " for =" user_email " > Email </ label >
< input class =" form-control " id =" user_email " name =" user[email] " required =" required " type =" email " value =" [email protected] " >
</ div >
< div class =" mb-3 " >
< label class =" form-label " for =" user_password " > Password </ label >
< input class =" form-control " id =" user_password " name =" user[password] " type =" password " >
< small class =" form-text text-muted " > A good password should be at least six characters long </ small >
</ div >
< div class =" form-check mb-3 " >
< input autocomplete =" off " name =" user[remember_me] " type =" hidden " value =" 0 " >
< input class =" form-check-input " id =" user_remember_me " name =" user[remember_me] " type =" checkbox " value =" 1 " >
< label class =" form-check-label " for =" user_remember_me " > Remember me </ label >
</ div >
< input class =" btn btn-secondary " data-disable-with =" Log In " name =" commit " type =" submit " value =" Log In " >
</ form > bootstrap_form_with admite los casos de uso model: y url: en form_with .
form_with tiene algunas diferencias importantes en comparación con form_for y form_tag , y estas diferencias se aplican a bootstrap_form_with . Puede encontrar un buen resumen de las diferencias en: https://m.patrikonrails.com/rails-5-1s-form-with-vs-old-form-helpers-3a5f72a8c78a, o en la documentación de Rails.
Se pueden agregar campos para un objeto diferente sin anidar usando los ayudantes bootstrap_fields_for y bootstrap_fields de la misma manera que se hace en Rails.
<%= bootstrap_form_with model: @user do |f| %>
<%= f.email_field :email %>
<%= bootstrap_fields_for :parent do |pf| %>
<%= pf.email_field :email, label: 'Parent email' %>
<% end %>
<%= bootstrap_fields @user.address do |af| %>
<%= af.text_field :street_name %>
<% end %>
<%= f.primary "Save" %>
<% end %> HTML generado:
< form accept-charset =" UTF-8 " action =" /users " method =" post " >
< div class =" mb-3 " >
< label class =" form-label required " for =" user_email " > Email </ label >
< input class =" form-control " id =" user_email " name =" user[email] " required =" required " type =" email " value =" [email protected] " >
</ div >
< div class =" mb-3 " >
< label class =" form-label " for =" parent_email " > Parent email </ label >
< input class =" form-control " id =" parent_email " name =" parent[email] " type =" email " >
</ div >
< div class =" mb-3 " >
< label class =" form-label " for =" street_name " > Street name </ label >
< input class =" form-control " id =" street_name " name =" street_name " type =" text " >
</ div >
< input class =" btn btn-primary " data-disable-with =" Save " name =" commit " type =" submit " value =" Save " >
</ form > bootstrap_form se puede utilizar de forma inmediata y sin ninguna configuración. Sin embargo, bootstrap_form tiene un archivo de configuración opcional en config/initializers/bootstrap_form.rb para configurar opciones que afectan a todos los formularios generados en una aplicación.
Las opciones de configuración actuales son:
| Opción | Valor predeterminado | Descripción |
|---|---|---|
default_form_attributes | bootstrap_form las versiones 3 y 4 agregaron un atributo role="form" a todos los formularios. El validador del W3C generará una advertencia en los formularios con un atributo role="form". bootstrap_form versión 5 elimina este atributo de forma predeterminada. Establezca esta opción en { role: "form" } para que los formularios no cumplan con W3C, pero genere el atributo role="form" como bootstrap_form versiones 3 y 4. |
Ejemplo:
# config/initializers/bootstrap_form.rb
BootstrapForm . configure do | c |
c . default_form_attributes = { role : "form" } # to make forms non-compliant with W3C.
end bootstrap_form proporciona su propia versión de los siguientes ayudantes de formulario Rails:
button email_field search_field
check_box file_field select
collection_check_boxes grouped_collection_select submit
collection_radio_buttons hidden_field (not wrapped, but supported) telephone_field
collection_select month_field text_area
color_field number_field text_field
date_field password_field time_field
date_select phone_field time_select
datetime_field radio_button time_zone_select
datetime_local_field range_field url_field
datetime_select rich_text_area week_field
De forma predeterminada, los ayudantes generan una etiqueta label y una etiqueta input , select o textarea llamando al ayudante label Rails y luego al ayudante Rails con el mismo nombre que el ayudante bootstrap_form .
Los ayudantes bootstrap_form aceptan las mismas opciones que los ayudantes de formulario Rails estándar y pasan esas opciones al ayudante de Rails. También aceptan opciones adicionales, descritas en la siguiente sección.
Muchos de los ayudantes aceptan las mismas opciones. Las excepciones son:
botón, casilla de verificación, casillas de verificación de colección, botones de radio de colección, selección de colección, selección de fecha, selección de fecha y hora, campo de archivo, selección de colección agrupada, campo oculto, botón de radio, área de texto enriquecido, seleccionar, enviar, selección de tiempo, selección de zona horaria
Las opciones para los asistentes de formulario que no están en la lista de excepciones se describen en las siguientes subsecciones:
Utilice la opción label si desea especificar el texto de la etiqueta del campo:
<%= f.password_field :password_confirmation, label: "Confirm Password" %> Esto genera:
< div class =" mb-3 " >
< label class =" form-label " for =" user_password_confirmation " > Confirm Password </ label >
< input class =" form-control " id =" user_password_confirmation " name =" user[password_confirmation] " type =" password " >
</ div > Para ocultar una etiqueta, utilice la opción hide_label: true . Esto agrega la clase visually-hidden , que mantiene sus etiquetas accesibles para quienes usan lectores de pantalla.
<%= f.text_area :comment, hide_label: true, placeholder: "Leave a comment..." %> Esto genera:
< div class =" mb-3 " >
< label class =" visually-hidden " for =" user_comment " > Comment </ label >
< textarea class =" form-control " id =" user_comment " name =" user[comment] " placeholder =" Leave a comment... " >
</ textarea >
</ div >Para agregar clases personalizadas a la etiqueta del campo:
<%= f.email_field :email, label_class: "custom-class" %> Esto genera:
< div class =" mb-3 " >
< label class =" custom-class required " for =" user_email " > Email </ label >
< input class =" form-control " id =" user_email " name =" user[email] " required =" required " type =" email " value =" [email protected] " >
</ div >O puedes agregar la etiqueta como marcador de posición de entrada (esto oculta automáticamente la etiqueta):
<%= f.email_field :email, value: '', label_as_placeholder: true %> Esto genera:
< div class =" mb-3 " >
< label class =" visually-hidden required " for =" user_email " > Email </ label >
< input class =" form-control " id =" user_email " name =" user[email] " placeholder =" Email " required =" required " type =" email " value ="" >
</ div > Para especificar la clase de la etiqueta de entrada generada, use la opción control_class :
<%= f.text_field :email, control_class: "custom-class" %> Esto genera:
< div class =" mb-3 " >
< label class =" form-label required " for =" user_email " > Email </ label >
< input class =" custom-class " id =" user_email " name =" user[email] " required =" required " type =" text " value =" [email protected] " >
</ div > Para agregar texto de ayuda, use la opción help :
<%= f.password_field :password, help: "Must be at least 6 characters long" %> Esto genera:
< div class =" mb-3 " >
< label class =" form-label " for =" user_password " > Password </ label >
< input class =" form-control " id =" user_password " name =" user[password] " type =" password " >
< small class =" form-text text-muted " > Must be at least 6 characters long </ small >
</ div >Esta gema también reconoce los mensajes de ayuda en los archivos de traducción local (i18n):
en :
activerecord :
help :
user :
password : " A good password should be at least six characters long " Las traducciones de ayuda que contengan HTML deben seguir la convención de agregar _html al nombre:
en :
activerecord :
help :
user :
password_html : " A <strong>good</strong> password should be at least six characters long " Si el nombre de su modelo tiene varias palabras (como SuperUser ), la clave en el archivo de traducción debe estar subrayada ( super_user ).
Puede anular las traducciones de ayuda para un campo en particular pasando la opción help o desactivarlas por completo pasando help: false .
Puede pasar opciones de prepend y/o append a los campos de entrada:
<%= f.text_field :price, prepend: "$", append: ".00" %> Esto genera:
< div class =" mb-3 " >
< label class =" form-label " for =" user_price " > Price </ label >
< div class =" input-group " >
< span class =" input-group-text " > $ </ span >
< input class =" form-control " id =" user_price " name =" user[price] " type =" text " >
< span class =" input-group-text " > .00 </ span >
</ div >
</ div >Si desea adjuntar varios elementos a la entrada, páselos como una matriz:
<% icon = capture do %> < i class =" bi bi-currency-dollar " > </ i > <% end %>
<%= f . text_field :price , prepend : [ 'Net' , icon ] , append : [ '.00' , 'per day' ] %>Esto genera:
< div class =" mb-3 " >
< label class =" form-label " for =" user_price " > Price </ label >
< div class ="
