bootstrap_form
v5.4.0
bootstrap_form est un générateur de formulaires Rails qui facilite l'intégration de formulaires de style Bootstrap v5 dans votre application Rails. Il fournit des assistants de formulaire qui complètent les assistants de formulaire Rails. Les assistants de formulaire de bootstrap_forms génèrent le champ de formulaire et son étiquette ainsi que tout le balisage Bootstrap requis pour un affichage Bootstrap correct. bootstrap_form fournit également :
bootstrap_form et le faire vous-même. Notez que cela s'applique aux messages de validation générés par Rails. La validation côté client HTML 5 et la validation Rails prête à l'emploi ne fonctionnent pas vraiment bien ensemble. Une discussion sur les défis et quelques solutions est icirequired dans les champs obligatoires.bootstrap_form ne peut pas faire. Voici quelques autres choses intéressantes que bootstrap_form fait pour vous :
.erb . bootstrap_form fonctionne comme les assistants de formulaire Rails standard, et ce README suppose que vous savez comment ils fonctionnent. Vous démarrez un formulaire avec l'un des bootstrap_form_with , bootstrap_form_for ou bootstrap_form_tag dans un fichier de vue. Vous obtenez un générateur de formulaire qui appelle les assistants bootstrap_form au lieu des assistants Rails standard. Vous utilisez ce générateur de formulaire dans le fichier de vue pour afficher un ou plusieurs champs de formulaire.
bootstrap_form prend en charge au minimum les versions actuellement prises en charge de Ruby et Rails :
Installez Bootstrap 5. Il existe de nombreuses façons de procéder, en fonction du pipeline d'actifs que vous utilisez dans votre application Rails. Une solution consiste à utiliser la gemme qui fonctionne avec Sprockets. Pour ce faire, dans une toute nouvelle application Rails 7.0+ créée sans l'option --webpacker , ajoutez la gem bootstrap à votre Gemfile :
gem "bootstrap" , "~> 5.0" Et suivez les instructions restantes du guide d'installation officiel de bootstrap pour configurer application.scss et application.js .
Ajoutez la gem bootstrap_form à votre Gemfile :
gem "bootstrap_form" , "~> 5.4"Alors:
bundle install
Selon le préprocesseur CSS que vous utilisez, l'ajout des styles de formulaire d'amorçage diffère légèrement. Si vous utilisez Rails en mode par défaut sans aucun préprocesseur, vous devrez ajouter la ligne suivante à votre fichier application.css :
* = require rails_bootstrap_forms Si vous avez suivi le guide d'installation officiel du bootstrap, vous serez probablement passé à SCSS. Dans ce cas ajoutez la ligne suivante à votre application.scss :
@import " rails_bootstrap_forms.css " ; Pour commencer, utilisez l'assistant bootstrap_form_for à la place de l'assistant Rails form_for . Voici un exemple :
<%= bootstrap_form_for(@user) do |f| %>
<%= f.email_field :email %>
<%= f.password_field :password %>
<%= f.check_box :remember_me %>
<%= f.submit "Log In" %>
<% end %> Cela génère le code HTML suivant :
< 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 votre formulaire n'est pas soutenu par un modèle, utilisez le bootstrap_form_tag . L'utilisation de cet assistant est la même que celle bootstrap_form_for , sauf qu'aucun objet modèle n'est transmis comme premier argument. Voici un exemple :
<%= bootstrap_form_tag url: '/subscribe' do |f| %>
<%= f.email_field :email, value: '[email protected]' %>
<%= f.submit %>
<% end %>Cela génère :
< 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 > Pour commencer, utilisez simplement l'assistant bootstrap_form_with à la place de form_with . Voici un exemple :
<%= 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 %> Cela génère :
< 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 prend en charge à la fois les cas d'utilisation model: et url: dans form_with .
form_with présente des différences importantes par rapport à form_for et form_tag , et ces différences s'appliquent à bootstrap_form_with . Un bon résumé des différences peut être trouvé sur : https://m.patrikonrails.com/rails-5-1s-form-with-vs-old-form-helpers-3a5f72a8c78a, ou dans la documentation Rails.
L'ajout de champs pour un objet différent sans imbrication peut être réalisé à l'aide des assistants bootstrap_fields_for et bootstrap_fields de la même manière que dans 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 généré :
< 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 peut être utilisé directement sans aucune configuration. Cependant, bootstrap_form dispose d'un fichier de configuration facultatif dans config/initializers/bootstrap_form.rb pour définir les options qui affectent tous les formulaires générés dans une application.
Les options de configuration actuelles sont :
| Option | Valeur par défaut | Description |
|---|---|---|
default_form_attributes | bootstrap_form versions 3 et 4 ont ajouté un attribut role="form" à tous les formulaires. Le validateur du W3C émettra un avertissement sur les formulaires avec un attribut role="form". bootstrap_form version 5 supprime cet attribut par défaut. Définissez cette option sur { role: "form" } pour rendre les formulaires non conformes au W3C, mais générez l'attribut role="form" comme bootstrap_form versions 3 et 4. |
Exemple:
# 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 fournit sa propre version des assistants de formulaire Rails suivants :
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
Par défaut, les assistants génèrent une balise label et une balise input , select ou textarea en appelant l'assistant label Rails, puis l'assistant Rails portant le même nom que l'assistant bootstrap_form .
Les assistants bootstrap_form acceptent les mêmes options que les assistants de formulaire Rails standard et transmettent ces options à l'assistant Rails. Ils acceptent également des options supplémentaires, décrites dans la section suivante.
De nombreux assistants acceptent les mêmes options. Les exceptions sont :
bouton, check_box, collection_check_boxes, collection_radio_buttons, collection_select, date_select, datetime_select, file_field, grouped_collection_select, Hidden_field, radio_button, rich_text_area, sélectionner, soumettre, time_select, time_zone_select
Les options des assistants de formulaire qui ne figurent pas dans la liste des exceptions sont décrites dans les sous-sections suivantes :
Utilisez l'option label si vous souhaitez spécifier le texte de l'étiquette du champ :
<%= f.password_field :password_confirmation, label: "Confirm Password" %> Cela génère :
< 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 > Pour masquer une étiquette, utilisez l'option hide_label: true . Cela ajoute la classe visually-hidden , qui garde vos étiquettes accessibles à ceux qui utilisent des lecteurs d'écran.
<%= f.text_area :comment, hide_label: true, placeholder: "Leave a comment..." %> Cela génère :
< 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 >Pour ajouter des classes personnalisées au libellé du champ :
<%= f.email_field :email, label_class: "custom-class" %> Cela génère :
< 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 >Ou vous pouvez ajouter l'étiquette comme espace réservé d'entrée à la place (cela masque automatiquement l'étiquette) :
<%= f.email_field :email, value: '', label_as_placeholder: true %> Cela génère :
< 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 > Pour spécifier la classe de la balise d'entrée générée, utilisez l'option control_class :
<%= f.text_field :email, control_class: "custom-class" %> Cela génère :
< 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 > Pour ajouter un texte d'aide, utilisez l'option help :
<%= f.password_field :password, help: "Must be at least 6 characters long" %> Cela génère :
< 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 >Cette gemme est également consciente des messages d'aide dans les fichiers de traduction de paramètres régionaux (i18n) :
en :
activerecord :
help :
user :
password : " A good password should be at least six characters long " Les traductions d'aide contenant du HTML doivent suivre la convention consistant à ajouter _html au nom :
en :
activerecord :
help :
user :
password_html : " A <strong>good</strong> password should be at least six characters long " Si le nom de votre modèle comporte plusieurs mots (comme SuperUser ), la clé du fichier de traduction doit être soulignée ( super_user ).
Vous pouvez remplacer les traductions d'aide pour un champ particulier en passant l'option help ou les désactiver complètement en passant help: false .
Vous pouvez transmettre des options prepend et/ou append aux champs de saisie :
<%= f.text_field :price, prepend: "$", append: ".00" %> Cela génère :
< 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 vous souhaitez attacher plusieurs éléments à l'entrée, transmettez-les sous forme de tableau :
<% icon = capture do %> < i class =" bi bi-currency-dollar " > </ i > <% end %>
<%= f . text_field :price , prepend : [ 'Net' , icon ] , append : [ '.00' , 'per day' ] %>Cela génère :
< div class =" mb-3 " >
< label class =" form-label " for =" user_price " > Price </ label >
< div class ="
