bootstrap_form
v5.4.0
bootstrap_form é um construtor de formulários Rails que torna muito fácil integrar formulários estilo Bootstrap v5 em sua aplicação Rails. Ele fornece auxiliares de formulário que aumentam os auxiliares de formulário do Rails. Os auxiliares de formulário do bootstrap_forms geram o campo do formulário e seu rótulo e toda a marcação do Bootstrap necessária para a exibição adequada do Bootstrap. bootstrap_form também fornece:
bootstrap_form e fazer você mesmo. Observe que isso se aplica a mensagens de validação geradas pelo Rails. A validação do lado do cliente HTML 5 e a validação Rails pronta para uso não funcionam bem juntas. Uma discussão sobre os desafios e algumas soluções está aquirequired nos campos obrigatórios.bootstrap_form não pode fazer. Algumas outras coisas legais que bootstrap_form faz por você são:
.erb . bootstrap_form funciona como os auxiliares de formulário padrão do Rails, e este README pressupõe que você saiba como eles funcionam. Você inicia um formulário com bootstrap_form_with , bootstrap_form_for ou bootstrap_form_tag em um arquivo de visualização. Você obtém um construtor de formulários que chama os auxiliares bootstrap_form em vez dos auxiliares padrão do Rails. Você usa esse construtor de formulário no arquivo de visualização para renderizar um ou mais campos de formulário.
bootstrap_form suporta no mínimo as versões atualmente suportadas de Ruby e Rails:
Instale o Bootstrap 5. Há muitas maneiras de fazer isso, dependendo do pipeline de ativos que você está usando em sua aplicação Rails. Uma maneira é usar a gema que funciona com Sprockets. Para fazer isso, em uma nova aplicação Rails 7.0+ criada sem a opção --webpacker , adicione a gem bootstrap ao seu Gemfile :
gem "bootstrap" , "~> 5.0" E siga as instruções restantes no guia oficial de instalação do bootstrap para configurar application.scss e application.js .
Adicione a gem bootstrap_form ao seu Gemfile :
gem "bootstrap_form" , "~> 5.4"Então:
bundle install
Dependendo de qual pré-processador CSS você está usando, a adição de estilos de formulário de bootstrap difere um pouco. Se você usar Rails no modo padrão sem qualquer pré-processador, você terá que adicionar a seguinte linha ao seu arquivo application.css :
* = require rails_bootstrap_forms Se você seguiu o guia oficial de instalação do bootstrap, provavelmente terá mudado para SCSS. Neste caso adicione a seguinte linha ao seu application.scss :
@import " rails_bootstrap_forms.css " ; Para começar, use o auxiliar bootstrap_form_for no lugar do auxiliar Rails form_for . Aqui está um exemplo:
<%= bootstrap_form_for(@user) do |f| %>
<%= f.email_field :email %>
<%= f.password_field :password %>
<%= f.check_box :remember_me %>
<%= f.submit "Log In" %>
<% end %> Isso gera o seguinte 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 > Se o seu formulário não for apoiado por um modelo, use bootstrap_form_tag . O uso deste auxiliar é o mesmo que bootstrap_form_for , exceto que nenhum objeto de modelo é passado como primeiro argumento. Aqui está um exemplo:
<%= bootstrap_form_tag url: '/subscribe' do |f| %>
<%= f.email_field :email, value: '[email protected]' %>
<%= f.submit %>
<% end %>Isso gera:
< 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 começar, basta usar o auxiliar bootstrap_form_with no lugar de form_with . Aqui está um exemplo:
<%= 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 %> Isso gera:
< 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 suporta os casos de uso model: e url: em form_with .
form_with tem algumas diferenças importantes em comparação com form_for e form_tag , e essas diferenças se aplicam a bootstrap_form_with . Um bom resumo das diferenças pode ser encontrado em: https://m.patrikonrails.com/rails-5-1s-form-with-vs-old-form-helpers-3a5f72a8c78a, ou na documentação do Rails.
Adicionar campos para um objeto diferente sem aninhamento pode ser feito usando os auxiliares bootstrap_fields_for e bootstrap_fields da mesma forma que é feito no 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 gerado:
< 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 pode ser usado imediatamente, sem qualquer configuração. No entanto, bootstrap_form possui um arquivo de configuração opcional em config/initializers/bootstrap_form.rb para definir opções que afetam todos os formulários gerados em um aplicativo.
As opções de configuração atuais são:
| Opção | Valor padrão | Descrição |
|---|---|---|
default_form_attributes | bootstrap_form versões 3 e 4 adicionaram um atributo role="form" a todos os formulários. O validador W3C irá gerar um aviso em formulários com um atributo role="form". bootstrap_form versão 5 descarta esse atributo por padrão. Defina esta opção como { role: "form" } para tornar os formulários não compatíveis com W3C, mas gere o atributo role="form" como bootstrap_form versões 3 e 4. |
Exemplo:
# 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 fornece sua própria versão dos seguintes auxiliares de formulário 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
Por padrão, os auxiliares geram uma tag label e uma tag input , select ou textarea , chamando o auxiliar label Rails e, em seguida, o auxiliar Rails com o mesmo nome do auxiliar bootstrap_form .
Os auxiliares bootstrap_form aceitam as mesmas opções que os auxiliares de formulário padrão do Rails e passam essas opções para o auxiliar do Rails. Eles também aceitam opções adicionais, descritas na seção a seguir.
Muitos dos ajudantes aceitam as mesmas opções. As exceções são:
botão, check_box, coleção_check_boxes, coleção_radio_buttons, coleção_select, date_select, datetime_select, file_field, grouped_collection_select, hidden_field, radio_button, rich_text_area, selecionar, enviar, time_select, time_zone_select
As opções para os auxiliares de formulário que não estão na lista de exceções são descritas nas seguintes subseções:
Use a opção label se quiser especificar o texto do rótulo do campo:
<%= f.password_field :password_confirmation, label: "Confirm Password" %> Isso gera:
< 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 um rótulo, use a opção hide_label: true . Isso adiciona a classe visually-hidden , que mantém seus rótulos acessíveis para quem usa leitores de tela.
<%= f.text_area :comment, hide_label: true, placeholder: "Leave a comment..." %> Isso gera:
< 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 adicionar classes personalizadas ao rótulo do campo:
<%= f.email_field :email, label_class: "custom-class" %> Isso gera:
< 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 você pode adicionar o rótulo como espaço reservado de entrada (isso oculta automaticamente o rótulo):
<%= f.email_field :email, value: '', label_as_placeholder: true %> Isso gera:
< 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 a classe da tag de entrada gerada, use a opção control_class :
<%= f.text_field :email, control_class: "custom-class" %> Isso gera:
< 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 adicionar texto de ajuda, use a opção help :
<%= f.password_field :password, help: "Must be at least 6 characters long" %> Isso gera:
< 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 gem também conhece mensagens de ajuda em arquivos de tradução de localidade (i18n):
en :
activerecord :
help :
user :
password : " A good password should be at least six characters long " As traduções de ajuda contendo HTML devem seguir a convenção de anexar _html ao nome:
en :
activerecord :
help :
user :
password_html : " A <strong>good</strong> password should be at least six characters long " Se o nome do seu modelo tiver várias palavras (como SuperUser ), a chave no arquivo de tradução deverá ser sublinhada ( super_user ).
Você pode substituir as traduções de ajuda para um campo específico passando a opção help ou desativá-las completamente passando help: false .
Você pode passar opções prepend e/ou append para campos de entrada:
<%= f.text_field :price, prepend: "$", append: ".00" %> Isso gera:
< 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 >Se você quiser anexar vários itens à entrada, passe-os como um array:
<% icon = capture do %> < i class =" bi bi-currency-dollar " > </ i > <% end %>
<%= f . text_field :price , prepend : [ 'Net' , icon ] , append : [ '.00' , 'per day' ] %>Isso gera:
< div class =" mb-3 " >
< label class =" form-label " for =" user_price " > Price </ label >
< div class ="
